​

HERE Fuel Prices API

​

What problem this guide solves

​

When to use HERE Fuel Prices

• Showing priced stations around a driver’s current position
• Finding stations along a planned route, with a corridor width you control
• Filtering candidate stops by brand, fuel type, or vehicle accessibility
• Building a price-spread view across a lane or region
• Feeding station candidates into an optimizer that scores detour cost

​

When NOT to use it

• Calculating what a fleet actually pays. These are pump prices. Fuel card networks settle at negotiated rates. Use this as a reference layer and model the discount separately.
• Detour cost. distance in the response is air distance. Road distance and drive time come from Routing.
• EV charging stops. Different product entirely. See EV Routing.
• General POI discovery. If you want every amenity at a truck stop, that is Geocoding & Search, not this.

​

Your first request

curl -gX GET 'https://fuel.hereapi.com/v3/stations?'\
'in=circle:41.9921,-88.0035;r=5000&'\
'fuelTypes=-1&'\
'sort=price:asc&'\
'limit=50' \
  -H "Authorization: Bearer $HERE_TOKEN"

import os, requests

resp = requests.get(
    "https://fuel.hereapi.com/v3/stations",
    params={
        "in": "circle:41.9921,-88.0035;r=5000",
        "fuelTypes": -1,          # All Truck Diesel
        "sort": "price:asc",
        "limit": 50,
    },
    headers={"Authorization": f"Bearer {os.environ['HERE_TOKEN']}"},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()
print(data["total"], len(data["stations"]))

const params = new URLSearchParams({
  in: "circle:41.9921,-88.0035;r=5000",
  fuelTypes: "-1",
  sort: "price:asc",
  limit: "50",
});

const resp = await fetch(
  `https://fuel.hereapi.com/v3/stations?${params}`,
  { headers: { Authorization: `Bearer ${process.env.HERE_TOKEN}` } }
);
if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);
const { total, stations } = await resp.json();
console.log(total, stations.length);

​

Key concepts

​

The US cash-versus-credit trap

​

Corridor search: use POST

curl -X POST 'https://fuel.hereapi.com/v3/stations?fuelTypes=-1&limit=50&sort=price:asc' \
  -H "Authorization: Bearer $HERE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "corridor": [
      { "lat": 35.9940, "lng": -78.8986 },
      { "lat": 36.0999, "lng": -80.2442 },
      { "lat": 35.2271, "lng": -80.8431 }
    ],
    "width": 5000
  }'

import os, requests

resp = requests.post(
    "https://fuel.hereapi.com/v3/stations",
    params={"fuelTypes": -1, "limit": 50, "sort": "price:asc"},
    json={
        "corridor": [
            {"lat": 35.9940, "lng": -78.8986},
            {"lat": 36.0999, "lng": -80.2442},
            {"lat": 35.2271, "lng": -80.8431},
        ],
        "width": 5000,
    },
    headers={"Authorization": f"Bearer {os.environ['HERE_TOKEN']}"},
    timeout=20,
)
resp.raise_for_status()
print(resp.json()["total"])

​

Truck workflows

1. Query wide, on the right fuel basis. fuelTypes=-1 for truck diesel, corridor via POST, limit at the ceiling.
2. Filter on accessibility client-side. Keep only stations whose accessibilities includes Suitable for large trucks. Expect this to remove a large share of results — in a dense suburban radius it routinely halves them.
3. Score the survivors with real routing. Detour to access, not position, using Truck Routing with the vehicle profile so height and weight restrictions on the approach are respected. A station rated for large trucks is still unreachable if the only approach runs under a low bridge.
4. Apply tank state. How much range remains determines whether a detour is affordable at all, and whether you want a partial fill now and a full fill at a better price downstream.

​

Production architecture

​

Cost and usage considerations

• Undebounced map interactions. The single largest avoidable cost in any map-driven fuel UI.
• Refetching an unchanged corridor. The route did not move. The station list did not move. Only prices did, and a cached station list plus a narrow price refresh is cheaper than a full corridor search.
• Pulling full station objects to test coverage. Use the count endpoint.
• Over-wide corridors. A 20 km corridor across a long interstate leg returns a large result set, most of which fails your detour filter anyway. Start at 5 km and widen only where results are thin.

​

Common mistakes

​

Best practices

• Query -1 or -2 category IDs rather than enumerating individual grades
• Pick a price basis, cash or credit, and filter to it before any ranking
• Use POST for corridors, GET for circles and viewports
• Route to access, never to position
• Cache station geometry and price data with different TTLs
• Surface the per-price modified timestamp in any UI a driver acts on
• Debounce every map-driven query
• Paginate against truck-accessible candidates, not raw row count
• Set X-Request-Id on every call and log it beside the status code

​

API reference

• Fuel Prices API v3 — stations search
• Fuel Prices API v3 — corridor search (POST)
• Fuel Prices API concepts

​

Related guides