## Reference: Locations

Places a driver goes: fuel stations, chargers and dealers, one ref each

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

### GET /v2/locations

Places near a point: fuel stations, chargers and dealers *Since 2026-10-26.*

Radius search over every place a driver goes, one `poi:{geohash}` ref per place: a gas station with chargers is one place with two kinds. A place is listed when any requested kind is live (a fuel station seen in the last 7 days, an operational charger, a dealer seen in the last 7 days). Nearest first. Each hit links to its own group's record (`links.fuel`, `links.charging`).

**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 |
| `kind` | string | no | Only places of these kinds: a comma list of "fuel", "charging", "seller" (e.g. "fuel,charging") |
| `limit` | integer | no | Place cap |

**Response 200** `LocationSearch`: Places nearest first

- `total` (integer): Number of places returned, at most `limit`
- `locations` (object[]): Nearest first
  - `locations[].ref` (string): Entity ref ({domain}:{key}) in the "poi" domain. Example: "poi:dpz9cxmmw0"
  - `locations[].id` (string): The place's id: a 10-character geohash of its location, the ref without "poi:" (e.g. "dpz9cxmmw0")
  - `locations[].kinds` ("fuel" | "charging" | "seller"[]): Every kind the place is, e.g. a gas station with chargers is ["fuel", "charging"]
  - `locations[].name` (string | null)
  - `locations[].brand` (string | null)
  - `locations[].address` (object)
    - `locations[].address.street` (string | null)
    - `locations[].address.city` (string | null)
    - `locations[].address.state` (string | null): Province or territory code, e.g. "ON"
    - `locations[].address.postalCode` (string | null)
    - `locations[].address.country` (string | null): Country code (ISO 3166-1 alpha-2)
  - `locations[].location` (object)
    - `locations[].location.latitude` (number)
    - `locations[].location.longitude` (number)
  - `locations[].distanceKm` (number): Distance from the search point, in km
  - `locations[].links`? (object): `self`, plus `fuel` (the /v2/fuel station) when kinds has fuel and `charging` (the /v2/charging station) when kinds has charging
- `asOf`? (string): The newest day any place was seen (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/locations?lat=43.6532&lng=-79.3832&radius_km=5&kind=fuel" \
  -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 locationSearch = await client.v2.locations.search({
  lat: 43.6532,
  lng: -79.3832,
  radius_km: 5,
  kind: "fuel",
});
console.log(locationSearch.total);
```

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

```python
import os

from cardog import Cardog

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

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

### GET /v2/locations/{id}

One place by id, with each kind's detail *Since 2026-10-26.*

The id is the place's 10-character geohash: its ref without "poi:" (e.g. `dpz9cxmmw0`). Anything else is a 404. Each kind's block (`fuel`, `charging`, `sellers`) is in its own group's shape, or null when the place is not that kind. One place can hold several dealers (an auto mall): `sellers.dealers` lists those seen in the last 7 days. The charging block carries the Open Charge Map attribution (ODbL 1.0); show it wherever station data renders.

**Path parameters**

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

**Response 200** `LocationDetailResponse`: The place with its fuel, charging and sellers blocks

- `location` (object)
  - `location.ref` (string): Entity ref ({domain}:{key}) in the "poi" domain. Example: "poi:dpz9cxmmw0"
  - `location.id` (string): The place's id: a 10-character geohash of its location, the ref without "poi:" (e.g. "dpz9cxmmw0")
  - `location.kinds` ("fuel" | "charging" | "seller"[]): Every kind the place is, e.g. a gas station with chargers is ["fuel", "charging"]
  - `location.name` (string | null)
  - `location.brand` (string | null)
  - `location.address` (object)
    - `location.address.street` (string | null)
    - `location.address.city` (string | null)
    - `location.address.state` (string | null): Province or territory code, e.g. "ON"
    - `location.address.postalCode` (string | null)
    - `location.address.country` (string | null): Country code (ISO 3166-1 alpha-2)
  - `location.location` (object)
    - `location.location.latitude` (number)
    - `location.location.longitude` (number)
  - `location.fuel` (object | null): Fuel detail, or null when the place is not a fuel station
    - `location.fuel.fuels` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"[]): Fuels the station sells
    - `location.fuel.prices` (object[]): Current prices: the newest post per fuel and payment, at most 7 days old
      - `location.fuel.prices[].fuel` ("regular" | "midgrade" | "premium" | "diesel" | "e85" | "propane"): Fuel: a gasoline grade (regular, midgrade, premium) or diesel, e85, propane
      - `location.fuel.prices[].fuelType` (string): Fuel-type entity ref, e.g. "fuel-type:gasoline"
      - `location.fuel.prices[].payment` ("credit" | "cash"): Price paying by card or by cash; most stations post credit only
      - `location.fuel.prices[].centsPerLitre` (number): Posted price, Canadian cents per litre
      - `location.fuel.prices[].currency` ("CAD")
      - `location.fuel.prices[].postedAt` (string): When the price was posted (ISO 8601)
      - `location.fuel.prices[].reportedBy` (string | null): Who posted it: "owner" (the station) or "member" / "visitor" (a driver). Other values may be added.
    - `location.fuel.amenities` (string[]): e.g. "c_store", "pay_at_pump", "restrooms". Other values may be added.
    - `location.fuel.openingHours` (string | null)
  - `location.charging` (object | null): Charging stations here, or null when there are none
    - `location.charging.stations` (object[])
      - `location.charging.stations[].ref` (string): Entity ref ({domain}:{key}) in the "station" domain. Example: "station:ocm/248113"
      - `location.charging.stations[].id` (string): Station id in the source dataset (Open Charge Map ChargePoint ID)
      - `location.charging.stations[].name` (string | null)
      - `location.charging.stations[].address` (object)
      - `location.charging.stations[].location` (object)
      - `location.charging.stations[].connectors` (object[])
      - `location.charging.stations[].maxPowerKw` (number | null): Highest rated power of any connector at the station, in kW
      - `location.charging.stations[].numberOfPoints` (integer | null): Number of charge points at the station
      - `location.charging.stations[].operator` (string | null)
      - `location.charging.stations[].status` (string): Station status: "Operational" or "NonOperational". Decommissioned stations are kept in the dataset, so filter on this field.
      - `location.charging.stations[].usage` (string | null): Usage class, e.g. "Public", "Private - Restricted Access"
      - `location.charging.stations[].isMembershipRequired` (boolean | null)
      - `location.charging.stations[].isPayAtLocation` (boolean | null)
      - `location.charging.stations[].dateCreated` (string | null): When the source first recorded the station (ISO 8601)
      - `location.charging.stations[].dateLastVerified` (string | null): Last source verification (ISO 8601)
      - `location.charging.stations[].poi` (string | null): The place this station is at: a `poi:{geohash}` ref, readable at `/v2/locations/{geohash}`. A fuel station or dealer at the same spot shares it. Null when the station has no place.
      - `location.charging.stations[].links`? (object): Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
    - `location.charging.attribution` (string): Open Charge Map attribution string (ODbL 1.0 licence). Must be shown wherever station data is displayed.
  - `location.sellers` (object | null): The dealers here seen in the last 7 days, or null when there are none
    - `location.sellers.dealers` (object[])
      - `location.sellers.dealers[].org` (string): The dealer organization's ref, e.g. "org:cardog/0b6f…"
      - `location.sellers.dealers[].name` (string | null)
  - `location.links`? (object): `self`, plus `fuel` and `charging` as on a search hit
- `asOf`? (string): The newest day any place was seen (YYYY-MM-DD)

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

**Example: cURL**

```bash
curl "https://api.cardog.app/v2/locations/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 locationDetail = await client.v2.locations.byId("dpz9cxmmw0");
console.log(locationDetail.location);
```

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

```python
import os

from cardog import Cardog

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

location_detail = client.v2.locations.by_id("dpz9cxmmw0")
print(location_detail.location)
```

---

Previous: [Safety](https://cardog.app/docs/reference/safety.md) (API reference)
Next: [Fuel](https://cardog.app/docs/reference/fuel.md) (API reference)