Use case-Allow sorting of fuel stations by price
This tutorial shows how to sort a list of fuel stations by fuel price, so that users of your app can find the cheapest or the most expensive stations in an area. It also shows how to page through the sorted results.
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 in Munich, Germany, you want to compare Diesel prices at fuel stations near the city center at latitude 48.13743 and longitude 11.57549. You want to:
- See the cheapest fuel stations within 5 km first.
- Switch the order to see the most expensive fuel stations first.
- Load more results when you scroll to the end of the list.
Latitude and longitude values are in WGS 84 format.
How sorting works
Use the sort parameter of the stations resource to set the order of the results. The format is {sortKey}:{sortDirection}:
| Value | Description |
|---|---|
price:asc | Sorts the stations from the lowest to the highest price. This is the default direction when you set only price. |
price:desc | Sorts the stations from the highest to the lowest price. |
Note
Prices are specific to each fuel type. To compare prices across stations, include a single fuel type in the
fuelTypesparameter. By default, stations with unknown price information aren't in the result set.
Sort fuel stations from cheapest to most expensive
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 in the center of Munich 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 price:asc. |
| limit | The maximum number of stations in the response; in this case 3. |
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:48.13743,11.57549;r=5000
&fuelTypes=1
&sort=price:asc
&limit=3
&apiKey={YOUR_API_KEY}Response
The response contains the stations in ascending order of price. The first station has the lowest price, so its deltaPrice is 0 and it has the lowest indexScore.
This is an example of the response in JSON format:
{
"total": 24,
"limit": 3,
"count": 3,
"stations": [
{
"id": "276u281z-4a9d2c7e1b3f4e8a9c6d5b2e1f0a7c34",
"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": 3870,
"open24x7": true,
"address": {
"label": "Landsberger Str. 280, München, 80687",
"countryCode": "DEU",
"state": "Bayern",
"city": "München",
"district": "Laim",
"street": "Landsberger Str.",
"postalCode": "80687",
"houseNumber": "280"
},
"position": {
"lat": 48.141372,
"lng": 11.524398
},
"prices": [
{
"price": 1.639,
"deltaPrice": 0.0,
"indexScore": 0,
"fuelType": "1",
"unit": "l",
"currency": "EUR",
"modified": "2026-09-30T06:05:12.000Z"
}
]
},
{
"id": "276u281z-7c1e3b5d9f2a4c6e8b0d2f4a6c8e1b37",
"modified": "2026-09-30T04:30:00.000Z",
"timeZone": "Europe/Berlin",
"name": "ARAL",
"brand": "Aral",
"brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
"distance": 2410,
"open24x7": true,
"address": {
"label": "Leopoldstr. 110, München, 80802",
"countryCode": "DEU",
"state": "Bayern",
"city": "München",
"district": "Schwabing",
"street": "Leopoldstr.",
"postalCode": "80802",
"houseNumber": "110"
},
"position": {
"lat": 48.158943,
"lng": 11.585721
},
"prices": [
{
"price": 1.659,
"deltaPrice": 0.02,
"indexScore": 9,
"fuelType": "1",
"unit": "l",
"currency": "EUR",
"modified": "2026-09-30T05:41:37.000Z"
}
]
},
{
"id": "276u281z-2b8f4d6a1c3e4b7d9f0a2c5e7b9d1f63",
"modified": "2026-09-30T04:30:00.000Z",
"timeZone": "Europe/Berlin",
"name": "SHELL",
"brand": "Shell",
"brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
"distance": 1980,
"open24x7": false,
"address": {
"label": "Rosenheimer Str. 72, München, 81669",
"countryCode": "DEU",
"state": "Bayern",
"city": "München",
"district": "Au-Haidhausen",
"street": "Rosenheimer Str.",
"postalCode": "81669",
"houseNumber": "72"
},
"position": {
"lat": 48.126315,
"lng": 11.597904
},
"prices": [
{
"price": 1.669,
"deltaPrice": 0.03,
"indexScore": 14,
"fuelType": "1",
"unit": "l",
"currency": "EUR",
"modified": "2026-09-30T06:12:58.000Z"
}
]
}
]
}Sort fuel stations from most expensive to cheapest
To reverse the order, change the sort direction to desc. All other parameters stay the same.
Request
https://fuel.hereapi.com/v3/stations
?in=circle:48.13743,11.57549;r=5000
&fuelTypes=1
&sort=price:desc
&limit=3
&apiKey={YOUR_API_KEY}Response
The response contains the stations in descending order of price. The first station has the highest price, so it has the highest deltaPrice and indexScore values in the search area.
This is an example of the response in JSON format, truncated to one station for readability:
{
"total": 24,
"limit": 3,
"count": 3,
"stations": [
{
"id": "276u281z-9e3a5c7b1d4f4a2e6c8b0d3f5a7e9c12",
"modified": "2026-09-30T04:30:00.000Z",
"timeZone": "Europe/Berlin",
"name": "ESSO",
"brand": "Esso",
"brandIcon": "https://fuel.hereapi.com/static/brand/icon/48/generic.png",
"distance": 640,
"open24x7": true,
"address": {
"label": "Sonnenstr. 24, München, 80331",
"countryCode": "DEU",
"state": "Bayern",
"city": "München",
"district": "Altstadt-Lehel",
"street": "Sonnenstr.",
"postalCode": "80331",
"houseNumber": "24"
},
"position": {
"lat": 48.134071,
"lng": 11.566432
},
"prices": [
{
"price": 1.789,
"deltaPrice": 0.15,
"indexScore": 100,
"fuelType": "1",
"unit": "l",
"currency": "EUR",
"modified": "2026-09-30T05:20:44.000Z"
}
]
}
]
}Load more sorted results
The sort order applies to the complete result set, not only to the current page. To load the next page of sorted stations, keep the same sort value and increase the offset parameter by the value of limit.
Request
This request returns the fourth to sixth cheapest stations:
https://fuel.hereapi.com/v3/stations
?in=circle:48.13743,11.57549;r=5000
&fuelTypes=1
&sort=price:asc
&limit=3
&offset=3
&apiKey={YOUR_API_KEY}Response
The response has the same structure as the previous examples. Use the total value to check whether more pages are available: when offset plus count is less than total, request the next page.
{
"total": 24,
"limit": 3,
"count": 3,
"stations": [
{
"id": "276u281z-5d7f9b1a3c6e4d8f0a2b4c6e8d0f2a45",
"name": "TOTALENERGIES",
"brand": "TotalEnergies",
"distance": 2950,
"address": {
"label": "Ingolstädter Str. 12, München, 80807"
},
"prices": [
{
"price": 1.679,
"deltaPrice": 0.04,
"indexScore": 18,
"fuelType": "1",
"unit": "l",
"currency": "EUR"
}
]
}
]
}Note
The response in this example is truncated to one station and a subset of fields for readability.
Display the sorted results
To let users switch between sort orders in your application:
- Add a control, such as a toggle or drop-down menu, with the options Cheapest first and Most expensive first.
- Map the options to
sort=price:ascandsort=price:desc. - When the user changes the option, send a new request with
offset=0and replace the current list. - Show
prices[].pricetogether withprices[].currencyandprices[].unit, for example1.639 EUR/l. - Optionally, use
prices[].deltaPriceto show how much more a station costs than the cheapest station, for example+0.02 EUR.
For more information about responses to this type of request, see Fuel Stations Response.
Updated 37 minutes ago