FuelService partner API

FuelService Stations API

A read-only web API for partners who need a structured list of active FuelService stations and the features available at each site.

HTTP Basic authentication Maximum 1000 stations per request Cursor or page pagination

Need access? Request API_KEY and API_SECRET by contacting support@fuelservice.org.

What you can query

  • Only active stations are returned.
  • The only data endpoint is GET /stations.
  • The base URL for this environment is https://api.fuelservice.org.
  • Use filters for idstations, country, and brand.

Authentication

Send API_KEY as the HTTP Basic username and API_SECRET as the HTTP Basic password. 

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?limit=10"

Query Parameters

All filters are optional. Combine them as needed to sync a full feed or request a narrow subset.

idstations

Comma-separated station IDs. Use this when you already know the exact sites you need.

Example: 10001,10002,10003

country

Comma-separated full country names, not abbreviations. Example values include United Kingdom and Ireland.

Example: United Kingdom,Ireland

brand

Comma-separated brand names with exact matching against the station data.

Example: Tesco,Shell

limit

Controls batch size. The limit must be between 1 and 1000. If omitted, the API defaults to 1000.

Example: 1000

after_id

Cursor mode. Return stations with idstations greater than this value, ordered ascending.

Example: 10001

page

Page mode. Return a stable page of results ordered by idstations ascending.

Example: 3

Pagination Modes

The API supports both sync-friendly cursor pagination and simpler page-based browsing.

Cursor Pagination

Use after_id when you want to walk forward through the feed in ascending idstations order. 

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?country=United%20Kingdom,Ireland&after_id=10001&limit=2"
{
  "data": [
    {
      "idstations": 10001,
      "name": "Abingdon Extra PFS",
      "brand": "Tesco",
      "brandid": "tesco",
      "country": "United Kingdom",
      "electric": 0
    },
    {
      "idstations": 10002,
      "name": "Sample Station",
      "brand": "Shell",
      "brandid": "shell",
      "country": "Ireland",
      "electric": 1
    }
  ],
  "pagination": {
    "limit": 2,
    "mode": "cursor",
    "page": null,
    "after_id": 10001,
    "next_after_id": 10002,
    "has_more": true,
    "returned": 2
  }
}

Page Pagination

Use page when you want a stable numbered page. Results are still ordered by idstations ascending. 

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?brand=Tesco,Shell&page=3&limit=2"
{
  "data": [
    {
      "idstations": 10201,
      "name": "Paged Station Example",
      "brand": "Tesco",
      "brandid": "tesco",
      "country": "United Kingdom",
      "wifi": 1
    }
  ],
  "pagination": {
    "limit": 2,
    "mode": "page",
    "page": 3,
    "after_id": null,
    "next_after_id": null,
    "has_more": false,
    "returned": 1
  }
}

Pagination Rules

  • Use either page or after_id, not both.
  • If you omit both, the API starts from the first batch in cursor mode.
  • The response always includes a pagination object with limit, mode, next_after_id, has_more, and returned.

Common Request Examples

These examples cover the most common partner workflows.

Filter by full country names

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?country=United%20Kingdom,Ireland&limit=1000"

Filter by brand list

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?brand=Tesco,Shell&limit=250"

Fetch specific stations

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?idstations=10001,10002,10003"

Combine filters with cursor mode

curl -u "$API_KEY:$API_SECRET" "https://api.fuelservice.org/stations?country=United%20Kingdom&brand=Tesco&limit=100&after_id=25000"

Response Shape

Every successful response returns a top-level data array and pagination metadata.

Top-level keys

  • data: an array of stations matching the filters.
  • pagination.mode: either cursor or page.
  • pagination.next_after_id: use this for the next cursor request when has_more is true.
  • pagination.page: the current page number when page mode is in use, otherwise null.

Error responses

  • 401 for missing or invalid credentials.
  • 400 for invalid filters or invalid pagination combinations.
  • 503 when the backing MySQL service is temporarily unavailable.

Returned Station Fields

These are the fields returned for each station in the data array.

Identity and location

  • idstations
  • name
  • brand
  • brandid
  • address1
  • address2
  • town
  • city
  • postcode
  • country
  • latitude
  • longitude

Opening hours

  • mondayopen
  • mondayclose
  • tuesdayopen
  • tuesdayclose
  • wednesdayopen
  • wednesdayclose
  • thursdayopen
  • thursdayclose
  • fridayopen
  • fridayclose
  • saturdayopen
  • saturdayclose
  • sundayopen
  • sundayclose

Site features

  • disabled_toilet
  • atm
  • wifi
  • carwash
  • air_and_water

Fuel and energy

  • low_octane
  • _91_octane
  • unleaded
  • super_unleaded
  • _100_octane
  • diesel
  • super_diesel
  • LPG
  • hydrogen
  • electric