Developer

Fuel Prices

Request Access
Service version: 2
Last edit: 2024.02.27
Automotive only

Important note
This API is unavailable on a Freemium or Pay As You Grow (PAYG) basis.
Click the Request Access button above to contact our Sales team.

Purpose

The Fuel Prices service provides information about the current fuel prices of fuel stations.

Request data

HTTPS method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL format

get
Request URL format
https://{baseURL}/search/{versionNumber}/fuelPrice.{ext}?key={Your_API_Key}&fuelPrice={fuelPriceId}

URL example

get
Request URL format
https://api.tomtom.com/search/2/fuelPrice.json?key={Your_API_Key}&fuelPrice=1:2622f89a-6300-11ec-8d12-a0423f39b5a2

curl command example

get
Request curl command example
curl 'https://api.tomtom.com/search/2/fuelPrice.json?key={Your_API_Key}&fuelPrice=1:2622f89a-6300-11ec-8d12-a0423f39b5a2'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters may be used.

Required parameters

Description

baseURL


string

The base URL for calling the API.


Value: api.tomtom.com

versionNumber


string

The service version.


Value: The current value is 2.

ext


string

The response format of the API request. The valid response format is JSON or XML.


Value: json or xml

key


string

An API Key valid for the requested service.


Value: Your valid API Key.

fuelPrice


string

The fuelPrice ID, previously retrieved from the dataSources section at the bottom of the Search response.
Value: Example: 1:2622f89a-6300-11ec-8d12-a0423f39b5a2

Request headers

The following table describes HTTP request headers.

Optional headers

Description

Tracking-ID

Specifies an identifier for the request.

  • It can be used to trace a call.

  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.

  • An example of the format that matches this regular expression is UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ).For details check RFC 4122.

  • If specified, it is replicated in the Tracking-ID response header.

  • It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: An identifier for the request.

Response data

Response body

If the <ext> parameter value is set to .json, the response will be a JSON object with the following structure:

Response body with the request URL <ext> parameter value set to ".json"
1{
2  "fuels": [
3    {
4      "type": "diesel",
5      "price": [
6        {
7          "value": 1.469,
8          "currency": "EUR",
9          "currencySymbol": "€",
10          "volumeUnit": "liter"
11        }
12      ],
13      "updatedAt": "2021-12-12T11:29:14Z"
14    },
15    {
16      "type": "dieselPlus",
17      "price": [
18        {
19          "value": 1.539,
20          "currency": "EUR",
21          "currencySymbol": "€",
22          "volumeUnit": "liter"
23        }
24      ],
25      "updatedAt": "2021-12-12T11:29:14Z"
26    },
27    {
28      "type": "sp95_e10",
29      "price": [
30        {
31          "value": 1.559,
32          "currency": "EUR",
33          "currencySymbol": "€",
34          "volumeUnit": "liter"
35        }
36      ],
37      "updatedAt": "2021-12-12T11:29:15Z"
38    },
39    {
40      "type": "sp95",
41      "price": [
42        {
43          "value": 1.619,
44          "currency": "EUR",
45          "currencySymbol": "€",
46          "volumeUnit": "liter"
47        }
48      ],
49      "updatedAt": "2021-12-12T11:29:14Z"
50    }
51  ],
52  "fuelPrice": "1:2622f89a-6300-11ec-8d12-a0423f39b5a2"
53}

If the <ext> parameter value is set to .xml, the response will be an XML format with the following structure:

Response body with the request URL <ext> parameter value set to ".xml"
1<?xml version="1.0" encoding="UTF-8"?>
2<response>
3  <fuelPrice>1:2622f89a-6300-11ec-8d12-a0423f39b5a2</fuelPrice>
4  <fuels>
5    <item>
6      <type>diesel</type>
7      <updatedAt>2021-12-12T11:29:14Z</updatedAt>
8      <price>
9        <item>
10          <value>1.469</value>
11          <currency>EUR</currency>
12          <currencySymbol>€</currencySymbol>
13          <volumeUnit>liter</volumeUnit>
14        </item>
15      </price>
16    </item>
17    <item>
18      <type>dieselPlus</type>
19      <updatedAt>2021-12-12T11:29:14Z</updatedAt>
20      <price>
21        <item>
22          <value>1.539</value>
23          <currency>EUR</currency>
24          <currencySymbol>€</currencySymbol>
25          <volumeUnit>liter</volumeUnit>
26        </item>
27      </price>
28    </item>
29    <item>
30      <type>sp95_e10</type>
31      <updatedAt>2021-12-12T11:29:15Z</updatedAt>
32      <price>
33        <item>
34          <value>1.559</value>
35          <currency>EUR</currency>
36          <currencySymbol>€</currencySymbol>
37          <volumeUnit>liter</volumeUnit>
38        </item>
39      </price>
40    </item>
41    <item>
42      <type>sp95</type>
43      <updatedAt>2021-12-12T11:29:14Z</updatedAt>
44      <price>
45        <item>
46          <value>1.619</value>
47          <currency>EUR</currency>
48          <currencySymbol>€</currencySymbol>
49          <volumeUnit>liter</volumeUnit>
50        </item>
51      </price>
52    </item>
53  </fuels>
54</response>

Usage and freshness of Fuel Prices data

Updates are provided regularly, typically within minutes.

Response fields

The following table describes all of the fields that can appear in a response. Fields are listed by the response section they belong to and in the order that they appear in the response.

Primary fields

Field

Description

fuelPrice


string

The ID of the returned entity.

fuels


array

A list of fuels present in this station. array of item objects

item object

FieldDescription

type


string

The name of the fuel's type.


Available values:


biodiesel, cng, diesel, dieselPlus, dieselPlusWithoutAdditives, dieselWithoutAdditives, e100, e80, e85, ethanolWithoutAdditives, lpg, regular, sp100, sp91, sp91_e10, sp92, sp92Plus, sp93, sp95, sp95_e10, sp95Plus, sp95WithoutAdditives, sp97, sp98, sp98Plus, sp99

price


array

A list of fuels present in this station. array of price objects

updatedAt


string

The time at which this price was last updated (no guarantee can be given for the price after this time)


Format: YYYY-MM-DDThh:mm:ssZ ISO_8601

price object

FieldDescription

value


float

The price per unit for this fuel type in this station.

currency


string

The currency of the fuel price.


Available values:


ISO codes : ARS, AUD, BAM, BGN, BRL, CAD, CHF, CLP, CZK, DKK, EUR, GBP, HKD, HRK, HUF, MXN, NOK, PLN, RON, RSD, RUB, SEK, TRY, TWD, USD

currencySymbol


string

The currency symbol.

volumeUnit


string

The volume unit of fuel price.


Value: Examples: liter, usGallon

Response codes

Code

Meaning & possible causes

200

OK : If the given fuelPrice was found, the body of the response will contain the data. Otherwise, the response will contain an empty fuels array in the response body. For example:


Error response example - JSON
1{
2  "fuels": [],
3  "fuelPrice": "1"
4}

400

Bad request : One or more parameters (e.g., fuelPrice , ext ) were incorrectly specified or are out of range.

403

Forbidden : Possible causes include:

  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer

404

Not Found : The requested resource could not be found, but it may be available again in the future.

405

Method Not Allowed : The client used an HTTP method other than GET.

429

Too Many Requests : The API Key is over QPS (Queries per second).

5xx

Server Error : The service was unable to process your request. Contact support to resolve the issue.

Response headers

The following table lists HTTP response headers of particular interest to Fuel Prices service clients.

Header

Description

Access-Control-Allow-Origin

The Fuel Prices service allows cross-origin resource sharing.


Value: * This asterisk signifies access to the TomTom API using the Access-Control-Allow-Origin (ACAO) header in its response, indicating which origin sites are allowed.

Content-Encoding

The Fuel Prices service supports HTTP compression if requested by the client.


Value: gzip

Cache-Control

The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain.

  • Supported by HTTP/1.1 clients.
  • May not be supported by HTTP/1.0 clients.

Value: no-cache

Content-Type

Indicates the format of the response as chosen by the client. Format: type/subtype; charset=utf-8


Value: type/subtype: application/json

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: An identifier for the request.

Error response

The error response content type depends on the ext parameter.

Error response example - JSON
1{
2  "message": "Missing parameter 'parameterName'",
3  "detailedError": {
4    "code": "MissingParameter",
5    "message": "Missing required parameter 'parameterName'."
6  },
7  "httpStatusCode": "400"
8}
Error response example - XML
1<ErrorEvResponse>
2  <message>Missing parameter 'parameterName'</message>
3  <detailedError>
4    <code>MissingParameter</code>
5    <message>Missing required parameter 'parameterName'.</message>
6  </detailedError>
7</ErrorEvResponse>

Error response fields

Primary fields

Description

message


string

A human-readable description of the error.

detailedError


object

Detailed information about the error.


detailedError object

detailedError object

FieldDescription

code


string

One of a server-defined set of error codes.

message


string

A human-readable description of the error code.


It is intended as an aid to developers and is not suitable for exposure to end users.