Fuel Prices
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
https://{baseURL}/search/{versionNumber}/fuelPrice.{ext}?key={Your_API_Key}&fuelPrice={fuelPriceId}
URL example
https://api.tomtom.com/search/2/fuelPrice.json?key={Your_API_Key}&fuelPrice=1:2622f89a-6300-11ec-8d12-a0423f39b5a2
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 |
---|---|
string | The base URL for calling the API. Value: |
string | The service version. Value: The current value is |
string | The response format of the API request. The valid response format is JSON or XML. Value: |
string | An API Key valid for the requested service. Value: Your valid |
string | The |
Request headers
The following table describes HTTP request headers.
Optional headers | Description |
---|---|
Tracking-ID | Specifies an identifier for the request.
Value: An |
Response data
Response body
If the <ext>
parameter value is set to .json
, the response will be a JSON object with the following structure:
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:
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 |
string | The ID of the returned entity. |
array | A list of fuels present in this station. array of item objects |
item object | |
Field | Description |
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 |
array | A list of fuels present in this station. array of price objects |
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 | |
Field | Description |
float | The price per unit for this fuel type in this station. |
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 |
string | The currency symbol. |
string | The volume unit of fuel price. Value: Examples: liter, usGallon |
Response codes
Code | Meaning & possible causes |
---|---|
| OK : If the given Error response example - JSON
|
| Bad request : One or more parameters (e.g., |
| Forbidden : Possible causes include:
|
| Not Found : The requested resource could not be found, but it may be available again in the future. |
| Method Not Allowed : The client used an HTTP method other than
|
| Too Many Requests : The API Key is over QPS (Queries per second). |
| 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 |
---|---|
The Fuel Prices service allows cross-origin resource sharing. Value: | |
The Fuel Prices service supports HTTP compression if requested by the client. Value: | |
The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain.
Value: | |
Indicates the format of the response as chosen by the client. Format:
Value: | |
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 |
Error response
The error response content type depends on the ext
parameter.
1{2 "message": "Missing parameter 'parameterName'",3 "detailedError": {4 "code": "MissingParameter",5 "message": "Missing required parameter 'parameterName'."6 },7 "httpStatusCode": "400"8}
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 |
---|---|
string | A human-readable description of the error. |
object | Detailed information about the error. detailedError object |
detailedError object | |
Field | Description |
string | One of a server-defined set of error codes. |
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. |