## Reference: Fuel

Fuel stations and pump prices in Canada

**Availability: live** on `https://api.cardog.app`.

### GET /v2/fuel/stations

Fuel stations near a point, with current prices *Since 2026-10-26.*

Radius search over our daily snapshot of Canadian fuel stations — no live upstream. Each station carries its current posted prices (newest post per fuel and payment, at most 7 days old) in Canadian cents per litre. Nearest first, or cheapest first with `sort=price` and a `fuel`.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lat` | number | yes | Search-center latitude |
| `lng` | number | yes | Search-center longitude |
| `radius_km` | number | no | Search radius in km |
| `fuel` | "regular" \| "midgrade" \| "premium" \| "diesel" \| "e85" \| "propane" | no | Only stations with a current price for this fuel |
| `sort` | "distance" \| "price" | no | Nearest first, or cheapest current credit price first (needs `fuel`) |
| `limit` | integer | no | Station cap |

**Response 200** `FuelStationSearch`: Stations with current prices

- `total` (integer): Number of stations returned, at most `limit`
- `stations` (object[])
  - `stations[].ref` (string): Entity ref ({domain}:{key}) in the "poi" domain. Example: "poi:dpz9cxmmw0"
  - `stations[].id` (string): The station's id: a 10-character geohash of its location, the ref without "poi:" (e.g. "dpz9cxmmw0")
  - `stations[].name` (string | null)
  - `stations[].brand` (string | null)
  - `stations[].address` (object)
    - `stations[].address.street` (string | null)
    - `stations[].address.city` (string | null)
    - `stations[].address.state` (string | null): Province or territory code, e.g. "ON"
    - `stations[].address.postalCode` (string | null)
    - `stations[].address.country` (string | null): Country code (ISO 3166-1 alpha-2)
  - `stations[].location` (object)
    - `stations[].location.latitude` (number)
    - `stations[].location.longitude` (number)
  - `stations[].fuels` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"[]): Fuels the station sells
  - `stations[].amenities` (string[]): e.g. "c_store", "pay_at_pump", "restrooms". Other values may be added.
  - `stations[].openingHours` (string | null)
  - `stations[].prices` (object[]): Current prices: the newest post per fuel and payment, at most 7 days old
    - `stations[].prices[].fuel` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"): Fuel: a gasoline grade (regular, midgrade, premium) or diesel, e85, propane
    - `stations[].prices[].fuelType` (string): Fuel-type entity ref, e.g. "fuel-type:gasoline"
    - `stations[].prices[].payment` ("credit" | "cash"): Price paying by card or by cash; most stations post credit only
    - `stations[].prices[].centsPerLitre` (number): Posted price, Canadian cents per litre
    - `stations[].prices[].currency` ("CAD")
    - `stations[].prices[].postedAt` (string): When the price was posted (ISO 8601)
    - `stations[].prices[].reportedBy` (string | null): Who posted it: "owner" (the station) or "member" / "visitor" (a driver). Other values may be added.
  - `stations[].lastSeen` (string): The newest daily snapshot the station appeared in (YYYY-MM-DD)
  - `stations[].distanceKm`? (number): Distance from the search point, in km (search results only)
  - `stations[].links`? (object): Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
- `asOf`? (string): The newest daily snapshot served (YYYY-MM-DD)
- `links`? (object): Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

**Errors** (all use the ErrorEnvelope): 400, 401, 402, 429, 500

**Example: cURL**

```bash
curl "https://api.cardog.app/v2/fuel/stations?lat=43.6532&lng=-79.3832&radius_km=5&fuel=regular" \
  -H "x-api-key: $CARDOG_API_KEY"
```

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const fuelStationSearch = await client.v2.fuel.search({
  lat: 43.6532,
  lng: -79.3832,
  radius_km: 5,
  fuel: "regular",
});
console.log(fuelStationSearch.total);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

fuel_station_search = client.v2.fuel.search(lat=43.6532, lng=-79.3832, radius_km=5, fuel="regular")
print(fuel_station_search.total)
```

### GET /v2/fuel/stations/{id}

One fuel station by id, with current prices *Since 2026-10-26.*

The id is the station's 10-character geohash: its ref without "poi:" (e.g. `dpz9cxmmw0` for `poi:dpz9cxmmw0`). Anything else is a 404.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Station id: a 10-character geohash, the ref without "poi:" (e.g. "dpz9cxmmw0") |

**Response 200** `FuelStationDetail`: The station record with its current prices

- `station` (object)
  - `station.ref` (string): Entity ref ({domain}:{key}) in the "poi" domain. Example: "poi:dpz9cxmmw0"
  - `station.id` (string): The station's id: a 10-character geohash of its location, the ref without "poi:" (e.g. "dpz9cxmmw0")
  - `station.name` (string | null)
  - `station.brand` (string | null)
  - `station.address` (object)
    - `station.address.street` (string | null)
    - `station.address.city` (string | null)
    - `station.address.state` (string | null): Province or territory code, e.g. "ON"
    - `station.address.postalCode` (string | null)
    - `station.address.country` (string | null): Country code (ISO 3166-1 alpha-2)
  - `station.location` (object)
    - `station.location.latitude` (number)
    - `station.location.longitude` (number)
  - `station.fuels` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"[]): Fuels the station sells
  - `station.amenities` (string[]): e.g. "c_store", "pay_at_pump", "restrooms". Other values may be added.
  - `station.openingHours` (string | null)
  - `station.prices` (object[]): Current prices: the newest post per fuel and payment, at most 7 days old
    - `station.prices[].fuel` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"): Fuel: a gasoline grade (regular, midgrade, premium) or diesel, e85, propane
    - `station.prices[].fuelType` (string): Fuel-type entity ref, e.g. "fuel-type:gasoline"
    - `station.prices[].payment` ("credit" | "cash"): Price paying by card or by cash; most stations post credit only
    - `station.prices[].centsPerLitre` (number): Posted price, Canadian cents per litre
    - `station.prices[].currency` ("CAD")
    - `station.prices[].postedAt` (string): When the price was posted (ISO 8601)
    - `station.prices[].reportedBy` (string | null): Who posted it: "owner" (the station) or "member" / "visitor" (a driver). Other values may be added.
  - `station.lastSeen` (string): The newest daily snapshot the station appeared in (YYYY-MM-DD)
  - `station.distanceKm`? (number): Distance from the search point, in km (search results only)
  - `station.links`? (object): Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
- `asOf`? (string): The newest daily snapshot served (YYYY-MM-DD)

**Errors** (all use the ErrorEnvelope): 400, 401, 402, 404, 429, 500

**Example: cURL**

```bash
curl "https://api.cardog.app/v2/fuel/stations/dpz9cxmmw0" \
  -H "x-api-key: $CARDOG_API_KEY"
```

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const fuelStationDetail = await client.v2.fuel.station("dpz9cxmmw0");
console.log(fuelStationDetail.station);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

fuel_station_detail = client.v2.fuel.station("dpz9cxmmw0")
print(fuel_station_detail.station)
```

### GET /v2/fuel/prices

Daily pump prices for Canada, a province or a postal FSA *Since 2026-10-26.*

The daily median, p10, p90 and mean of current credit prices across stations in an area, for one fuel, oldest first. Areas: `CA`, a province (`CA-ON`), or a forward sortation area (`L3Y`, the first three characters of a postal code).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `area` | string | no | "CA", a province like "CA-ON", or an FSA like "L3Y" |
| `fuel` | "regular" \| "midgrade" \| "premium" \| "diesel" \| "e85" \| "propane" | no | Fuel |
| `days` | integer | no | Days of history |

**Response 200** `FuelPrices`: The area's daily price series

- `area` (string)
- `areaKind` ("country" | "province" | "fsa")
- `fuel` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"): Fuel: a gasoline grade (regular, midgrade, premium) or diesel, e85, propane
- `fuelType` (string): Fuel-type entity ref, e.g. "fuel-type:gasoline"
- `currency` ("CAD")
- `latest` (object | null): The newest day in the series, or null when the area has no prices
  - `latest.date` (string): YYYY-MM-DD
  - `latest.stations` (integer): Stations with a current credit price that day
  - `latest.medianCentsPerLitre` (number)
  - `latest.p10CentsPerLitre` (number): 10th percentile: the cheap end
  - `latest.p90CentsPerLitre` (number): 90th percentile: the expensive end
  - `latest.meanCentsPerLitre` (number)
- `series` (object[]): One entry per day with prices, oldest first
  - `series[].date` (string): YYYY-MM-DD
  - `series[].stations` (integer): Stations with a current credit price that day
  - `series[].medianCentsPerLitre` (number)
  - `series[].p10CentsPerLitre` (number): 10th percentile: the cheap end
  - `series[].p90CentsPerLitre` (number): 90th percentile: the expensive end
  - `series[].meanCentsPerLitre` (number)
- `asOf`? (string): The newest daily snapshot served (YYYY-MM-DD)
- `links`? (object): Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

**Errors** (all use the ErrorEnvelope): 400, 401, 402, 429, 500

**Example: cURL**

```bash
curl "https://api.cardog.app/v2/fuel/prices?area=CA-ON&fuel=regular&days=30" \
  -H "x-api-key: $CARDOG_API_KEY"
```

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const fuelPrices = await client.v2.fuel.prices({ area: "CA-ON", fuel: "regular", days: 30 });
console.log(fuelPrices.area);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

fuel_prices = client.v2.fuel.prices(area="CA-ON", fuel="regular", days=30)
print(fuel_prices.area)
```

---

Previous: [Locations](https://cardog.app/docs/reference/locations.md) (API reference)
Next: [Charging](https://cardog.app/docs/reference/charging.md) (API reference)