Fuel Prices API Developer's Guide

Fuel Station Example

This section provides an example of a request for a list of fuel stations within a specified geometry.

Note: This example uses a HERE API key to authenticate your request. For the available authentication options, see the Identity & Access Management Developer Guide

User story

The user wants to obtain a list of fuel stations along a planned travel route.

Request Summary

Resource: stations , note that resource representation is specified via extensions .xml or .json
Parameters: corridor – indicates the area searched for fuel stations; in this case a corridor between Berlin and Hamburg, with a stop at Magdeburg.
  corridorwidth – indicates the corridor width, in this case 10 km.

Request

The code block below demonstrates the complete request, specifying that the response data are to be delivered in JSON.


https://fuel-v2.cc.api.here.com/fuel/stations.json
?corridor=52.516667,13.383333;52.133333,11.616667;53.565278,10.001389
&corridorwidth=10000
&apiKey={YOUR_API_KEY}

Here is the same request indicating that the response data are to be delivered in XML.


https://fuel-v2.cc.api.here.com/fuel/stations.xml
?corridor=52.516667,13.383333;52.133333,11.616667;53.565278,10.001389
&corridorwidth=10000
&apiKey={YOUR_API_KEY}

Response

The response to the request contains:

  • a list of stations that fit the specified criteria with additional details

The example response in JSON format is as follows:


{
   "hasMore":true,
   "fuelStations":{
    "fuelStation":[
     {
      "brand":"Shell",
      "brandIcon":"http://origin.stg.cld.vcdn.data.here.com/p/d/autox_stg/dt/icons/2015-05-06/shell.png",
      "fuelPrice":[
         {
          "price":1.379,
          "fuelType":"27",
          "unit":"l",
          "currency":"EUR",
          "lastUpdateTimestamp":"2015-03-08T14:48:52.000Z"
         },
         {
          "price":1.149,
          "fuelType":"1",
          "unit":"l",
          "currency":"EUR",
          "lastUpdateTimestamp":"2015-03-08T14:48:52.000Z"
         }
      ],
      "stationDetails":{
         "openingHours":{
          "regularOpeningHours":[
           {
            "daymask":127,
            "period":[
               {
                "from":"05:00:00",
                "to":"23:00:00"
               }
            ]
           }
          ]
         }
      },
      "address":{
         "city":"Hamburg",
         "country":"DEU",
         "region":"Hamburg",
         "street":"Alter Teichweg",
         "streetNumber":"71",
         "postalCode":"22049"
      },
      "position":{
         "latitude":53.5845718,
         "longitude":10.0596704
      },
      "name":"Hamburg, Alter Teichweg.",
      "id":"276u1x0u-749a20a72c684f898d045f54239b962d",
      "lastUpdateTimestamp":"2014-12-14T11:05:53.374Z",
      "timeZone":"Europe/Berlin"
     },
   { ---removed to shorten document }
    ]
   }
}

The example response in XML format is as follows:


<fuel:fuelStationsResult xmlns:fuel="http://www.here.com/2014/02/ACS-Fuel" xmlns:common="http://www.here.com/2014/02/ACS-Common">
  <hasMore>true</hasMore>
  <fuelStations>
    <fuelStation id="276u1x0u-749a20a72c684f898d045f54239b962d" lastUpdateTimestamp="2014-12-14T11:05:53.374Z" timeZone="Europe/Berlin">
      <address>
    <city>Hamburg</city>
    <country>DEU</country>
    <region>Hamburg</region>
    <street>Alter Teichweg</street>
    <streetNumber>71</streetNumber>
    <postalCode>22049</postalCode>
  </address>
      <position>
        <latitude>53.5845718</latitude>
        <longitude>10.0596704</longitude>
      </position>
      <name>Hamburg, Alter Teichweg.</name>
      <brand>Shell</brand>
      <brandIcon>http://origin.stg.cld.vcdn.data.here.com/p/d/autox_stg/dt/icons/2015-05-06/shell.png</brandIcon>
      <fuelPrice fuelType="27" unit="l" currency="EUR" lastUpdateTimestamp="2015-03-08T14:48:52.000Z">
        <price>1.379</price>
      </fuelPrice>
      <fuelPrice fuelType="1" unit="l" currency="EUR" lastUpdateTimestamp="2015-03-08T14:48:52.000Z">
        <price>1.149</price>
      </fuelPrice>
      <stationDetails>
        <openingHours>
          <regularOpeningHours>
            <daymask>127</daymask>
            <period>
              <from>05:00:00</from>
              <to>23:00:00</to>
            </period>
          </regularOpeningHours>
        </openingHours>
      </stationDetails>
    </fuelStation>
    <fuelStation lastUpdateTimestamp="2013-10-30T04:24:17.518Z" id="276u33d8-099ccdf310fa4d3b9cca7e55073a1a07" timeZone="Europe/Berlin">
      ---removed to shorten document
    </fuelStation>
  </fuelStations>
</fuel:fuelStationsResult>

For more details about responses to this type of request refer to Fuel Stations Response.