# Build with locations

[Locations](https://cardog.app/docs/locations), [fuel prices](https://cardog.app/docs/fuel) and
[chargers](https://cardog.app/docs/charging) 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.

```bash
# 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.

```bash
# 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.

```bash
# 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".

```bash
# 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.

```bash
# 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.

---

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