Fuel Prices API Developer's Guide

Stations

This resource retrieves a list of fuel stations that match the specified criteria.

Requests against this resource use the HTTP GET method. The search criteria are specified by means of query parameters, which must include a search geometry.

Search geometry can be one of:

  • prox – a circular area defined by the coordinates of its center and a radius.
  • corridor – a path defined as a set of points (latitude, longitude pairs) and a width.
  • bbox – a square defined by its top left latitude and longitude and its bottom right latitude and longitude.

Request Example

The code block below shows a search request that uses proximity (prox) to define the search area.


https://fuel-v2.cc.api.here.com/fuel/stations.xml
?prox=52.516667,13.383333,5000
&apiKey={YOUR_API_KEY}

Request Parameters

The table below documents both mandatory and optional request parameters supported by the stations resource.

Parameter Required Description
app_id - legacy Yes

A-20 byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request. For more information on authentication, see the Identity & Access Management Developer Guide.

app_code - legacy Yes

A-20 byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request. For more information on authentication, see the Identity & Access Management Developer Guide.

apiKey Yes A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://developer.here.com/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time. You must include an apiKey with every request. For more information on authentication, see the Identity & Access Management Developer Guide.
prox prox, bbox or corridor must be present

A circular search area defined by the latitude and longitude of its center (compliant with WGS 84) and an integer representing the radius of the area in meters, all separated by commas.

For example, prox=52.516667,13.383333,5000 searches for fuel prices 5km of latitude 52.50° N and 13.55 ° E, which is within Berlin.

The maximum radius of the circle is 200 km.

bbox prox, bbox or corridor must be present

Bounding box defined by the latitude and longitude (compliant with WGS 84) of its top left and bottom right corners. The top left and bottom right pairs are separated by a semicolon and the latitude and longitude pairs are separated by commas.

For example, one possible bounding box value is bbox=52.8,11.37309;52.31,13.2.

The bounding box size (width and/or high) must be no larger than 400km.

corridor prox, bbox or corridor must be present
A strip defined as a semicolon-separated list of points (pairs of comma-separated latitude and longitude WGS 84 compliant values) For example,
corridor=52.51666,13.38333;
52.13333,11.61666;53.56527,10.00138
specifies a journey from Berlin to Hamburg via Magdeburg.

Maximum corridor area is 5000 km2

Note that requests to the stations resource can be a maximum of 4 kb in size in total. Since the corridor query parameter is the item that is most likely to contain the most information, a useful guideline is that this parameter can contain approximately 150 points (latitude/longitude pairs with an accuracy of 5 decimal points [for example, 11.37309]). Note that the amount of data you can include depends on the exact formulation of the request.

fueltype No

Comma separated integers identifying the fuel types or categories included in the response. Number of values is unlimited

Stations with unknown price information are excluded from the result set by default. When showallstations parameter set to "true" then all stations within search area will be included in the result.

For more information on available fuel types and categories, see Fuel Types and Categories.

corridorwidth No

The width of the corridor in meters. This parameter takes effect only if corridor are included in the request.

The maximum corridor width is 20 km.

Default: 5000

maxresults No The maximum number of results a response can contain.

This parameter together with the offset parameter in the query and HasMore in the response can be used for pagination.

Default: 50.

sortkey No Criteria for sorting a list of search results.

The possible values are:

  • price (available when fueltype is specified as a query parameter, and its value is mapped to a single fuel type)
  • distance (only available for proximity search) – sorts by distance to fuel station
sortorder No

The sort order of the results.

The possible values are:

  • asc (ascending)
  • desc (descending)

Default: asc

offset No A value specifying the index of the first result.

This parameter together with the maxresults parameter in the query and HasMore in the response can be used for pagination.

Default: 0.

showallstations No Also fuel stations with unknown price or fuel type information will be included in the result set. This parameter works together with fueltype parameter.

The possible values are:

  • true
  • false

Default: false

imagedimensions No Request specific maximum size of brand icon image to match UI and bandwidth requirements

The format is that specifies dimension for a scaled image by providing either the desired width, desired heigh, or both

Valid elements are:

  • w\d+
  • h\d+
  • w\d+-h\d+

Examples:

  • imagedimensions=w32-h32
  • imagedimensions=w300
  • imagedimensions=h200
Note: The provided values are used as upper boundaries for the dimensions of the returned image. The solution will never scale up small image and will maintain the aspect ratio of the original image.
brand No List of brands to filter the stations in the response. The brand names in the list are separated with commas. The result will contain only the stations that have brand field that match to the one of those specified in the list. The matching is caseinsensitive.

Response to this Request

For more information on the responses to queries against the stations resource, see Fuel Stations Response.