Build with locations

Locations, fuel prices and chargers share refs with the rest of the API: a fuel price names the same fuelType ref a decoded vehicle carries, and every place has one poi: ref whatever it offers. That makes each of these a call or two, not a data project.

Real numbers only. Every price on this page is from the 2026-10-25 snapshot. Everything else is a formula you fill with your own data.

1. What this car costs to drive

A car page or a listing that says what the car costs to run where the buyer lives.

# the car's combined consumption, from the build code its decode returned
curl "https://api.cardog.app/v2/specs/nano:{code}" -H "x-api-key: $CARDOG_API_KEY"

# today's price where the buyer lives
curl "https://api.cardog.app/v2/fuel/prices?area=L3Y&fuel=regular&days=1" \
  -H "x-api-key: $CARDOG_API_KEY"

refs.fuelType on the decode or the sheet picks the fuel: fuel-type:gasoline is regular (or premium where the maker requires it), fuel-type:diesel is diesel. sections.efficiency.fuelEconomyCombined is in litres per 100 km (L100K). Cost per 100 km is that times latest.medianCentsPerLitre, divided by 100 for dollars.

In Newmarket's L3Y the regular median was 166.1 ¢/L across 14 stations, so every litre per 100 km is $1.66 per 100 km. The user sees "about $X per 100 km at prices near you today", and the figure moves when the price does.

2. The cheapest fuel on a route

A trip planner that puts the cheap stop on the way, not the nearest one.

# at each point along the route, the three cheapest within 5 km
curl "https://api.cardog.app/v2/fuel/stations?lat=43.9421&lng=-79.3797&radius_km=5&fuel=regular&sort=price&limit=3" \
  -H "x-api-key: $CARDOG_API_KEY"

# the province's median, to say how cheap is cheap
curl "https://api.cardog.app/v2/fuel/prices?area=CA-ON&fuel=regular&days=1" \
  -H "x-api-key: $CARDOG_API_KEY"

Sample the route every 10 km or so and keep the best stop per stretch. Ontario's regular median was 168.9 ¢/L across 2,803 stations. The user sees two or three stops on the map, each with its price, how long ago it was posted (postedAt), and how far under the provincial median it is.

3. EV against gas, by postal area

A side-by-side for a shopper deciding between two powertrains, priced for their own postal area.

# the gas side: the FSA's price
curl "https://api.cardog.app/v2/fuel/prices?area=L3Y&fuel=regular&days=30" \
  -H "x-api-key: $CARDOG_API_KEY"

# the EV side: public chargers near home
curl "https://api.cardog.app/v2/locations?lat=44.0500&lng=-79.4600&radius_km=5&kind=charging" \
  -H "x-api-key: $CARDOG_API_KEY"

Take the gas car's fuelEconomyCombined from its sheet as in build 1. For the EV, batteryCapacity (KWH) over range (KM) on its sheet gives kWh per km; multiply by the driver's own rate per kWh from their bill. The user sees two costs per 100 km for their FSA and how many chargers are within 5 km of home. Read stations on the price series first: an FSA with a handful of stations is a handful of prices.

4. What is around this dealer

A dealer's site or listing page that answers "where do I charge or fill up near the lot".

# the rooftop itself
curl "https://api.cardog.app/v2/locations/{id}" -H "x-api-key: $CARDOG_API_KEY"

# chargers and fuel within 3 km of it
curl "https://api.cardog.app/v2/locations?lat={latitude}&lng={longitude}&radius_km=3&kind=charging,fuel" \
  -H "x-api-key: $CARDOG_API_KEY"

The rooftop is a seller location: sellers.dealers names every dealer there, and its location gives the point for the search. A place in the results that is both kinds, pumps and chargers at one stop, comes back once, with kinds: ["fuel", "charging"]. The user sees the nearest chargers and stations with their distance, and, for an EV listing, whether there is a charger on the lot itself (charging on the rooftop's own record is not null). Where chargers show, show the charging block's attribution beside them.

5. A fleet fuel budget by province

A fleet tool that turns planned kilometres into a monthly fuel budget per province.

# once per build in the fleet
curl "https://api.cardog.app/v2/specs/nano:{code}" -H "x-api-key: $CARDOG_API_KEY"

# once per province the fleet runs in
curl "https://api.cardog.app/v2/fuel/prices?area=CA-ON&fuel=diesel&days=30" \
  -H "x-api-key: $CARDOG_API_KEY"

Budget per vehicle is planned km times fuelEconomyCombined over 100, times the price. Use the 30-day median for the plan and p90CentsPerLitre for a budget that holds when prices run high; the series shows how far they moved last month. The user sees one row per province: litres, the median budget and the high-side budget.

Calls and caching

Each request is 1 credit. Stations and prices are built once a day, so cache an answer until asOf changes. A station's current price can be up to 7 days old, so read postedAt before you call one "today's price". Refs never change while a place stays put, so a stored poi: ref is a safe key for favourites, trips and saved stops.