Use case-How to show lists of fuel stations with location and price information

This tutorial shows how to retrieve lists of fuel stations with information on their location and fuel prices, either along a planned route or around a specific location. Use the results to display fuel stations in a list or on a map in your app.

📘
Note
This tutorial uses a HERE API key to authenticate your requests. For the available authentication options, see the Identity and Access Management Developer Guide.

User story

As a driver, you want to see a list of fuel stations that offer Diesel, together with their addresses, positions, and current prices, so that you can choose where to refuel. You want to see this list in one of the following ways:

Along a planned route - Fuel stations within a corridor around the route you are driving, from Berlin Mitte to Berlin Reinickendorf, Germany.
Based on a location - Fuel stations within 5 km of your current location at latitude 52.53087 and longitude 13.44176 in Berlin, Germany, sorted by price.

Latitude and longitude values are in WGS 84 format.

Show fuel stations along a planned route

To retrieve fuel stations along a route, send a POST request to the stations resource. The request body contains a CorridorSearchRequest object that defines the route as a list of coordinates and the width of the corridor around it. The maximum corridor area is 5000 km².

Request summary

Resource	Parameters
stations	The resource representation. Requests use the HTTP `POST` method.
fuelTypes	Indicates the type of fuel the query includes in the response; in this case `1` (`Diesel`).
limit	The maximum number of stations in the response; in this case `10`.
`corridor` (request body)	The list of route coordinates that define the planned route.
`width` (request body)	The width of the corridor around the route, in meters; in this case `2000`.

Request

This code block demonstrates the request URL and headers:

POST https://fuel.hereapi.com/v3/stations
?fuelTypes=1
&limit=10
&apiKey={YOUR_API_KEY}

Content-Type: application/json

This code block demonstrates the request body with the route coordinates:

{
  "corridor": [
    {
      "lat": 52.5310898,
      "lng": 13.3849497
    },
    {
      "lat": 52.5378799,
      "lng": 13.3735304
    },
    {
      "lat": 52.5476799,
      "lng": 13.3569899
    },
    {
      "lat": 52.5622292,
      "lng": 13.3263397
    }
  ],
  "width": 2000
}

The following example shows the complete request with cURL:

curl -X POST "https://fuel.hereapi.com/v3/stations?fuelTypes=1&limit=10&apiKey={YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "corridor": [
      { "lat": 52.5310898, "lng": 13.3849497 },
      { "lat": 52.5378799, "lng": 13.3735304 },
      { "lat": 52.5476799, "lng": 13.3569899 },
      { "lat": 52.5622292, "lng": 13.3263397 }
    ],
    "width": 2000
  }'

Response

The response contains a list of fuel stations within the corridor that offer the requested fuel type. For each station, the response includes:

The name, brand, and brand icon of the station.
The address and the geographic position of the station, and the position of its access point.
The price, delta price, and index score for the requested fuel type.

This is an example of the response in JSON format:

{
    "total": 2,
    "limit": 10,
    "count": 2,
    "stations": [
        {
            "id": "276u33db-1f4c0b8e2a1d4f3c9e6b7a5d4c3b2a10",
            "modified": "2026-09-30T05:15:00.000Z",
            "timeZone": "Europe/Berlin",
            "name": "ARAL",
            "brand": "Aral",
            "brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
            "open24x7": true,
            "address": {
                "label": "Chausseestr. 62, Berlin, 10115",
                "countryCode": "DEU",
                "state": "Berlin",
                "city": "Berlin",
                "district": "Mitte",
                "street": "Chausseestr.",
                "postalCode": "10115",
                "houseNumber": "62"
            },
            "position": {
                "lat": 52.533402,
                "lng": 13.381215
            },
            "access": {
                "lat": 52.53335,
                "lng": 13.38115
            },
            "prices": [
                {
                    "price": 1.699,
                    "deltaPrice": 0.0,
                    "indexScore": 58,
                    "fuelType": "1",
                    "unit": "l",
                    "currency": "EUR",
                    "modified": "2026-09-30T06:02:41.000Z"
                }
            ]
        },
        {
            "id": "276u33dc-8b2e4d6f1a3c4e5b9d7f6a2c1e0b3d48",
            "modified": "2026-09-30T04:45:00.000Z",
            "timeZone": "Europe/Berlin",
            "name": "SHELL",
            "brand": "Shell",
            "brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
            "open24x7": false,
            "address": {
                "label": "Seestr. 18, Berlin, 13353",
                "countryCode": "DEU",
                "state": "Berlin",
                "city": "Berlin",
                "district": "Wedding",
                "street": "Seestr.",
                "postalCode": "13353",
                "houseNumber": "18"
            },
            "position": {
                "lat": 52.548112,
                "lng": 13.354871
            },
            "access": {
                "lat": 52.54805,
                "lng": 13.35481
            },
            "prices": [
                {
                    "price": 1.729,
                    "deltaPrice": 0.03,
                    "indexScore": 71,
                    "fuelType": "1",
                    "unit": "l",
                    "currency": "EUR",
                    "modified": "2026-09-30T05:48:12.000Z"
                }
            ]
        }
    ]
}

Show fuel stations based on a location

To retrieve fuel stations around a location, send a GET request to the stations resource and define the search area with the in parameter. To show the cheapest stations first, sort the results by price.

Request summary

Resource	Parameters
stations	The resource representation. Requests use the HTTP `GET` method.
in=circle:***	Indicates the area searched for fuel stations; in this case a circle defined by a point within Berlin and a radius of 5 km.
fuelTypes	Indicates the type of fuel the query includes in the response; in this case `1` (`Diesel`).
sort	Indicates the sort order of the results; in this case by price in ascending order.
limit	The maximum number of stations in the response; in this case `10`.

Request

This code block demonstrates the complete request, specifying that the response data is in JSON format:

https://fuel.hereapi.com/v3/stations
?in=circle:52.53087,13.44176;r=5000
&fuelTypes=1
&sort=price:asc
&limit=10
&apiKey={YOUR_API_KEY}

Response

The response contains a list of fuel stations within the search area that offer the requested fuel type, sorted from the lowest to the highest price. For each station, the response includes:

The name, brand, and brand icon of the station.
The address and the geographic position of the station, and the air distance in meters from the center of the search area.
The price, delta price, and index score for the requested fuel type.

This is an example of the response in JSON format:

{
    "total": 39,
    "limit": 10,
    "count": 10,
    "stations": [
        {
            "id": "276u33dc-3e7a9c1b5d2f4a6e8c0b1d3f5a7c9e2b",
            "modified": "2026-09-30T04:30:00.000Z",
            "timeZone": "Europe/Berlin",
            "name": "JET",
            "brand": "JET",
            "brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
            "distance": 2140,
            "open24x7": true,
            "address": {
                "label": "Landsberger Allee 190, Berlin, 10367",
                "countryCode": "DEU",
                "state": "Berlin",
                "city": "Berlin",
                "district": "Lichtenberg",
                "street": "Landsberger Allee",
                "postalCode": "10367",
                "houseNumber": "190"
            },
            "position": {
                "lat": 52.527915,
                "lng": 13.472864
            },
            "access": {
                "lat": 52.52786,
                "lng": 13.47279
            },
            "prices": [
                {
                    "price": 1.659,
                    "deltaPrice": 0.0,
                    "indexScore": 12,
                    "fuelType": "1",
                    "unit": "l",
                    "currency": "EUR",
                    "modified": "2026-09-30T06:10:05.000Z"
                }
            ]
        },
        {
            "id": "276u33dc-ac678a5a65f54b66a4243522c59eb4f8",
            "modified": "2026-09-30T04:30:00.000Z",
            "timeZone": "Europe/Berlin",
            "name": "TOTALENERGIES",
            "brand": "TotalEnergies",
            "brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
            "distance": 55,
            "open24x7": false,
            "address": {
                "label": "Margarete-Sommer-Str. 2, Berlin, 10407",
                "countryCode": "DEU",
                "state": "Berlin",
                "city": "Berlin",
                "district": "Prenzlauer Berg",
                "street": "Margarete-Sommer-Str.",
                "postalCode": "10407",
                "houseNumber": "2"
            },
            "position": {
                "lat": 52.530831,
                "lng": 13.440946
            },
            "access": {
                "lat": 52.53082,
                "lng": 13.44088
            },
            "prices": [
                {
                    "price": 1.679,
                    "deltaPrice": 0.02,
                    "indexScore": 25,
                    "fuelType": "1",
                    "unit": "l",
                    "currency": "EUR",
                    "modified": "2026-09-30T05:57:10.000Z"
                }
            ]
        }
    ]
}

📘
Note
The example response is truncated to two stations for readability. To page through all results, use the limit and offset parameters together with the total and count values in the response.

Display the results

To show the list of fuel stations in your application, use the following elements from each station in the stations array:

Element	Use
`name`, `brand`, `brandIcon`	Identify the fuel station in the list.
`address.label`	Show the address of the fuel station.
`position`	Place a marker for the fuel station on a map.
`access`	Calculate a route to the entrance of the fuel station.
`distance`	Show the distance from the search location. Available for circle searches only.
`prices[].price`, `prices[].currency`, `prices[].unit`	Show the current fuel price, for example `1.659 EUR/l`.
`prices[].indexScore`	Compare the price with other stations in the area. A lower score indicates a cheaper price.
`prices[].modified`	Show when the price was last updated.

For more information about responses to this type of request, see Fuel Stations Response.