Locations

curl "https://api.cardog.app/v2/locations?lat=43.6532&lng=-79.3832&kind=fuel,charging&limit=1" \
  -H "x-api-key: $CARDOG_API_KEY"

The places a driver goes near a point, nearest first: gas stations, charging sites, dealers' lots. Each place comes back once, with one ref, poi:dpz83errq8, whatever it offers and however many listings describe it. One credit a request.

Store the ref. The ref is derived from the place's coordinates, so it is stable for as long as the place does not move. It carries no name and no upstream id: a station that changes brand keeps its ref. That makes it a safe key for favourites, trips and saved stops.

The id is the ref without poi:, a geohash: ten characters that locate the place to within about a metre. /v2/locations/dpz83errq8 is the place. An id that is not a geohash is a 404.

Kinds

Each location lists what it is in kinds:

One place can be several kinds. A travel centre with pumps and fast chargers is one location with kinds: ["fuel", "charging"], not two records a metre apart. A dealer with a charger on the lot is ["seller", "charging"]. An auto mall is one seller location that holds several dealers.

Places near a point

The search above returns:

• radius_km defaults to 10 and caps at 100.
• limit defaults to 20 and caps at 100.
• kind is optional and takes one kind or a comma list. Without it you get every kind.
• links holds one path per kind the place is: fuel is its /v2/fuel/stations/{id}, and charging, when the place has chargers, is a /v2/charging/stations/{id} path. A search hit already knows where its prices and chargers live.

A place is listed when any kind you asked for is live there: fuel and dealers seen in the last 7 days, counted from today's date rather than from asOf, and chargers that are Operational. A place that closes drops out within a week even if a snapshot is late.

One location

curl "https://api.cardog.app/v2/locations/dpz9cxmmw0" \
  -H "x-api-key: $CARDOG_API_KEY"

The record is the search hit without distanceKm, plus one block per kind:

• fuel holds the fuels sold, the current prices (the same price records /v2/fuel serves), amenities and opening hours.
• charging holds stations, every charger at the place, each a /v2/charging station record without source, and attribution. A site with several networks' chargers has several stations.
• sellers holds dealers, every dealer that sells at the place, each with its org ref and name. Most rooftops hold one; an auto mall holds several.

A kind the place is not is null, never an empty block, so location.charging === null means "no chargers here", not "unknown".

Show the attribution with charging data. The charging block always carries attribution: "Charging station data (c) Open Charge Map contributors, ODbL 1.0 (https://openchargemap.org)". The ODbL licence requires it wherever station data is displayed, so render it beside the chargers.

Join a location to fuel prices and chargers

The location is the hub. Each kind's group is the detail.

• Fuel at the place. A fuel location's id is its fuel station's id: /v2/locations/dpz9cxmmw0 and /v2/fuel/stations/dpz9cxmmw0 are the same place, and the fuel station's ref is the location's ref.
• Fuel in the area. The first three characters of address.postalCode are the place's postal area (FSA). Pass them to /v2/fuel/prices?area=L0H for the area's daily median, or area=CA- plus address.state for the province. That tells you whether a station's price is cheap for where it is.
• Chargers. Every /v2/charging station gains a poi field: the full poi: ref of the place it stands at, or null when it has none yet. Group chargers by poi to get sites, or follow it to /v2/locations/{id} to see what else is there.
• Vehicles. Every fuel price names its fuelType with the same ref a vehicle's decode and spec sheet carry (fuel-type:gasoline), so a car and what it costs to fill join on one key.

Charging keeps its ref. A /v2/charging station's own ref, id and every other field are unchanged. poi is added beside them, so an integration that stored charging refs keeps working as it is.

For what to build on this, see Build with locations.