B2B EV Locations 1.0.1

This API Product provides the list of all the Shell Recharge location. The list includes all Shell Recharge network and all locations available through our roaming partners.

Getting Started with EV Location API

EMobility Locations API Product provides the list of all Shell Recharge locations. The list includes all Shell Recharge network and all locations available through our roaming partners.

This API product consist of 4 end points which can be used in order to develop different user journeys.

API End Point API Functionality
/ev Get the list of all the locations and its details.
/ev/id Get the details of a particular location.
/ev/nearby Get the list of locations nearby using the latitude and longitude.
/ev/markers Get the list of locations for a given set of bounds with different zoom levels in the map.

All the APIs are authenticated with standard OAuth2.0

Authentication

Obtain an API gatewway access token by making a POST request to the Shell Authentication OAuth endpoint. The end to end process is illustrated in the sequence diagram below.

sequenceDiagram participant PartnerApplication participant Shell autonumber alt Manual Process rect rgb(200, 150, 255) PartnerApplication ->>Shell: Request Client ID and Client Secret activate Shell Shell ->> PartnerApplication : Generate and provide Client ID and Client Secret deactivate Shell end end alt Authentication/Authorization rect rgb(191, 223, 255) PartnerApplication ->>Shell: Inititate request to OAuth end point with credentials activate Shell Shell ->> PartnerApplication : (200-OK) Returns Bearer Token deactivate Shell end end alt Call Functional Endpoint rect rgb(200, 150, 255) PartnerApplication ->>Shell: Initiate request to functional endpoint along with bearer token received from previous step activate Shell Shell ->> PartnerApplication : Returns a response on validation of the bearer token deactivate Shell end end

This step is to generate the API Access Token using the unique Client ID and Client Secret provided by Shell. (Please note that this credentials is to validate the API request between Shell and its partner so its system to system access token)

Key Request Parameters

Element Value
Method POST
Endpoint /oauth/token
Headers Content-Type: application/x-www-form-urlencoded
data-url-encode client_id=*******************
data-url-encode client_secret=***********
data-url-encode grant_type=client_credentials


Sample cURL Request

curl --location --request POST 'https://api-test.shell.com/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=***********' \
--data-urlencode 'client_secret=**********' \
--data-urlencode 'grant_type=client_credentials'

On receiving the request Shell Authorization system will verify all the parameters in the request and, if everything checks out, it will generate your access token and return it in the response.

Sample Response

{
    "access_token": "***********",
    "expires_in(seconds)": "899",
    "token_type": "BearerToken"
}

The response will contain the following parameters:

  • access_token: The token to be used to call the functional APIs
  • expires_in: The amount of seconds until the access token expires.
  • token_type: Bearer

Exception Handling

All error scenarios are returned with a response body and identifier.

{
      "error_descrription": "invalid client or client credentials",
      "error": "invalid_client"
}
HTTP Code Description Scenarios
400 Bad Request If Invalid scope passed to Token url
Invalid grant type passed to Token url
401 Unauthorized If Invalid id/secret passed to Token url
If Invalid or expired token passed to destination system’s API

Get all Locations

Introduction

This API, when given a set of bounds on the geographical front (East,West, North, South) will return a set of Markers that fall within the requested bounds. The API will automatically group locations at the same position on the map into one Marker.

The API also provide further search options to filter the result set.

  • Based on status of the Charging units. Eg : Available or Occupied
  • Based on available connector types.
  • Based on minimum Power output (in kW) available

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Key Request Parameters

  • Method : POST
  • URI : https://api-test.shell.com/locations/v1/ev
  • Headers :
    • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
    • RequestId : Must be unique identifier value that can be used by the consumer to correlate each request /response. Request ID needs to be in UUID format.

Sample CURL Request

curl --location --request GET 'https://api-test.shell.com/locations/v1/ev' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ************'

Sample Response

{
  "requestId": "233e4567-e89b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "data": [
    {
      "uid": 2,
      "externalId": "01001188",
      "coordinates": {
        "latitude": 52.104894,
        "longitude": 5.05285
      },
      "operatorName": "Community by Shell Recharge",
      "address": {
        "streetAndNumber": "Middenwetering 1",
        "postalCode": "3543AR",
        "city": "Utrecht",
        "country": "NLD"
      },
      "accessibility": {
        "status": "Unspecified",
        "remark": "",
        "statusV2": "Restricted"
      },
      "accessibilityV2": {
        "status": "Restricted"
      },
      "evses": [
        {
          "uid": 2,
          "externalId": "01001188_1",
          "evseId": "NL*TNM*E01001188*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 1286911,
              "externalId": "1",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC3Phase",
                "voltage": 230,
                "amperage": 5,
                "maxElectricPower": 3.5
              },
              "fixedCable": false,
              "tariff": {
                "startFee": 0,
                "perMinute": 0,
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:19:58Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              },
              "updated": "2022-11-18T11:19:40Z",
              "updatedBy": "Feed",
              "betaTariffV2": {
                "startFee": 0,
                "perMinute": 0,
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:19:58Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              }
            }
          ],
          "authorizationMethods": [
            "RFIDToken"
          ],
          "physicalReference": "NL*TNM*E01001188*0",
          "updated": "2022-11-18T11:19:40Z"
        },
        {
          "uid": 76,
          "externalId": "01001203_1",
          "evseId": "NL*TNM*E01001203*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 1286925,
              "externalId": "1",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC3Phase",
                "voltage": 230,
                "amperage": 5,
                "maxElectricPower": 3.5
              },
              "fixedCable": false,
              "tariff": {
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:20:04Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              },
              "updated": "2022-11-18T11:19:40Z",
              "updatedBy": "Feed",
              "betaTariffV2": {
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:20:04Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              }
            }
          ],
          "authorizationMethods": [
            "RFIDToken"
          ],
          "physicalReference": "NL*TNM*E01001203*0",
          "updated": "2022-11-28T07:49:48Z"
        }
      ],
      "updated": "2022-11-28T07:49:47Z",
      "name": "Warmtebouw linker paal",
      "locationType": "UNKNOWN",
      "supportPhoneNumber": "+(31)-(88)-0109500",
      "facilities": [
        "BUSINESS",
        "CARPOOL_PARKING",
        "HEALTH"
      ],
      "predictedOccupancies": [
        {
          "weekDay": "Mon",
          "occupancy": 5,
          "startTime": "00:00",
          "endTime": "00:59"
        }
      ]
    }
  ]
}

Get details of a particular location

Introduction

This API provides the details on a single Shell Recharge location.The query for a single location is to be made using the Unique Internal identifier used to refer to this Location by Shell Recharge. (Uid from List of locations API)

Key Request Parameters

  • Method : POST
  • URI : https://api-test.shell.com/locations/v1/ev/{uid}
  • Headers :
    • Authorization : Bearer access_token (Access Token generated from the OAuth end point)
    • RequestId : Must be unique identifier value that can be used by the consumer to correlate each request /response. Request ID needs to be in UUID format.

Sample CURL Request

curl --location --request GET 'https://api-test.shell.com/locations/v1/ev/5' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ********'

Sample Response

{
  "requestId": "233e4567-e89b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "data": [
    {
      "uid": 5,
      "externalId": "01000401",
      "coordinates": {
        "latitude": 52.3764,
        "longitude": 4.89459
      },
      "operatorName": "Community by Shell Recharge",
      "address": {
        "streetAndNumber": "Nieuwezijds Kolk 18",
        "postalCode": "1012 PV",
        "city": "Amsterdam",
        "country": "NLD"
      },
      "accessibility": {
        "status": "Unspecified",
        "remark": "",
        "statusV2": "Restricted"
      },
      "accessibilityV2": {
        "status": "Restricted"
      },
      "evses": [
        {
          "uid": 1106502,
          "externalId": "84303466-6ba5-11e5-aea2-0025901b2b6c",
          "evseId": "NL*TNM*E01000380*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 1280606,
              "externalId": "1",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC3Phase",
                "voltage": 230,
                "amperage": 5,
                "maxElectricPower": 3.5
              },
              "fixedCable": false,
              "tariff": {
                "startFee": 0,
                "perMinute": 0,
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-11T12:12:15Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              },
              "updated": "2022-11-11T11:01:08Z",
              "updatedBy": "Feed",
              "betaTariffV2": {
                "startFee": 0,
                "perMinute": 0,
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-11T12:12:15Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              }
            }
          ],
          "authorizationMethods": [
            "RFIDToken"
          ],
          "physicalReference": "NL*TNM*E01000380*0",
          "updated": "2022-11-11T11:01:08Z"
        },
        {
          "uid": 1103622,
          "externalId": "84305bf6-6ba5-11e5-aea2-0025901b2b6c",
          "evseId": "NL*TNM*E01000388*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 1277726,
              "externalId": "1",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC3Phase",
                "voltage": 230,
                "amperage": 5,
                "maxElectricPower": 3.5
              },
              "fixedCable": false,
              "tariff": {
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-11T12:07:27Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              },
              "updated": "2022-11-11T11:00:37Z",
              "updatedBy": "Feed",
              "betaTariffV2": {
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-11T12:07:27Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              }
            }
          ],
          "authorizationMethods": [
            "RFIDToken"
          ],
          "physicalReference": "NL*TNM*E01000388*0",
          "updated": "2022-11-11T11:00:37Z"
        }
      ],
      "updated": "2022-11-18T18:19:58Z",
      "locationType": "PARKING_LOT",
      "supportPhoneNumber": "+(31)-(88)-0109500",
      "facilities": [
        "HOTEL"
      ],
      "predictedOccupancies": [
        {
          "weekDay": "Mon",
          "occupancy": 6,
          "startTime": "00:00",
          "endTime": "00:59"
        }
      ]
    }
  ]
}

Get List of NearBy Locations

Introduction

This API provides the list of all near by Shell Recharge locations based on the latitude and longitude provided in the request. The list includes all Shell Recharge network and all sites available through our roaming partners. The end point provides the details such as the exact location/address of the site along with the up-to-date status information of all the charging units in the site.

Supported Search Options

  • Based on latitude and longitude of the location. (Mandatory)
  • Based on status of the Charging units. Eg : Available or Occupied
  • Based on available connector types.
  • Based on minimum Power output (in kW) available

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Key Request Parameters

  • Method : POST
  • URI : https://api-test.shell.com/locations/v1/ev/nearby
  • Headers :
    • Authorization : Bearer <> (Access Token generated from the OAuth end point)
    • RequestId : Must be unique identifier value that can be used by the consumer to correlate each request /response. Request ID needs to be in UUID format.
  • Query Parameters (Mandatory)
    • latitude : Latitude to get Shell Recharge Locations nearby
    • longitude : Longitude to get Shell Recharge Locations nearby

Sample CURL Request

curl --location --request GET 'https://api-test.shell.com/locations/v1/ev/nearby?latitude=53.59141&longitude=10.03813' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer **********'

Sample Response

{
  "requestId": "233e4567-e89b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "data": [
    {
      "uid": 2,
      "externalId": "01001188",
      "coordinates": {
        "latitude": 52.104894,
        "longitude": 5.05285
      },
      "operatorName": "Community by Shell Recharge",
      "address": {
        "streetAndNumber": "Middenwetering 1",
        "postalCode": "3543AR",
        "city": "Utrecht",
        "country": "NLD"
      },
      "accessibility": {
        "status": "Unspecified",
        "remark": "",
        "statusV2": "Restricted"
      },
      "accessibilityV2": {
        "status": "Restricted"
      },
      "evses": [
        {
          "uid": 2,
          "externalId": "01001188_1",
          "evseId": "NL*TNM*E01001188*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 1286911,
              "externalId": "1",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC3Phase",
                "voltage": 230,
                "amperage": 5,
                "maxElectricPower": 3.5
              },
              "fixedCable": false,
              "tariff": {
                "startFee": 0,
                "perMinute": 0,
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:19:58Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              },
              "updated": "2022-11-18T11:19:40Z",
              "updatedBy": "Feed",
              "betaTariffV2": {
                "startFee": 0,
                "perMinute": 0,
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:19:58Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              }
            }
          ],
          "authorizationMethods": [
            "RFIDToken"
          ],
          "physicalReference": "NL*TNM*E01001188*0",
          "updated": "2022-11-18T11:19:40Z"
        },
        {
          "uid": 76,
          "externalId": "01001203_1",
          "evseId": "NL*TNM*E01001203*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 1286925,
              "externalId": "1",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC3Phase",
                "voltage": 230,
                "amperage": 5,
                "maxElectricPower": 3.5
              },
              "fixedCable": false,
              "tariff": {
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:20:04Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              },
              "updated": "2022-11-18T11:19:40Z",
              "updatedBy": "Feed",
              "betaTariffV2": {
                "perKWh": 0,
                "currency": "EUR",
                "updated": "2022-11-18T18:20:04Z",
                "updatedBy": "TariffService",
                "structure": "Default"
              }
            }
          ],
          "authorizationMethods": [
            "RFIDToken"
          ],
          "physicalReference": "NL*TNM*E01001203*0",
          "updated": "2022-11-28T07:49:48Z"
        }
      ],
      "updated": "2022-11-28T07:49:47Z",
      "name": "Warmtebouw linker paal",
      "locationType": "UNKNOWN",
      "supportPhoneNumber": "+(31)-(88)-0109500",
      "facilities": [
        "BUSINESS",
        "CARPOOL_PARKING",
        "HEALTH"
      ],
      "predictedOccupancies": [
        {
          "weekDay": "Mon",
          "occupancy": 5,
          "startTime": "00:00",
          "endTime": "00:59"
        }
      ]
    }
  ]
}

Get List of Markers

Introduction

This API, when given a set of bounds on the geographical front (East,West, North, South) will return a set of Markers that fall within the requested bounds. The API will automatically group locations at the same position on the map into one Marker.

The API also provide further search options to filter the result set.

  • Based on status of the Charging units. Eg : Available or Occupied
  • Based on available connector types.
  • Based on minimum Power output (in kW) available

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Key Request Parameters

  • Method : POST
  • URI : https://api-test.shell.com/locations/v1/ev/markers
  • Headers :
    • Authorization : Bearer <> (Access Token generated from the OAuth end point)
    • RequestId : Must be unique identifier value that can be used by the consumer to correlate each request /response. Request ID needs to be in UUID format.
  • Query Parameters (Mandatory)
    • west : Longitude of the western bound to get the Shell Recharge Locations
    • east : Longitude of the eastern bound to get the Shell Recharge Locations
    • north : Latitude of the northern bound to get the Shell Recharge Locations
    • south : Latitude of the southern bound to get the Shell Recharge Locations
    • zoom : Zoom level to show (1: World, 5: Landmass/continent, 10: City, 15: Streets, 20: Buildings)

Sample CURL Request

curl --location --request GET 'https://api-test.shell.com/locations/v1/ev/markers?west=52.320513814822&south=4.87335773540221&east=4.87335773540221&north=4.87335773540221&zoom=10' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ********'

Sample Response

In the response, you would have the possibility of having 2 different markerType JSON objects.

  1. SingleLocation - In this JSON object you will find when the marker shows only a single location in the given boundary range in the query parameter.

  2. MultiLocation - In this JSON object, you will find when the marker shows multiple locations in the given boundary range in the query parameter. 

{
    "requestId": "233e4567-e89b-12d3-a456-426614174000",
    "status": "SUCCESS",
    "data": [
        {
            "markerType": "SingleLocation",
            "uniqueKey": "2115297_1",
            "status": "Available",
            "coordinates": {
                "latitude": 3.130126,
                "longitude": 101.641955
            },
            "evseCount": 1,
            "maxPower": 22.1,
            "operatorName": "Community by Shell Recharge",
            "geoHash": "w2",
            "locationUid": 2115297,
            "authorizationMethods": [
                "NewMotionApp",
                "RFIDToken"
            ],
            "accessibilityV2": {
                "status": "Unknown"
            }
        },
        {
            "markerType": "SingleLocation",
            "uniqueKey": "2116002_1",
            "status": "Available",
            "coordinates": {
                "latitude": 3.017309,
                "longitude": 101.583742
            },
            "evseCount": 1,
            "maxPower": 22.1,
            "operatorName": "Community by Shell Recharge",
            "geoHash": "w2",
            "locationUid": 2116002,
            "authorizationMethods": [
                "NewMotionApp",
                "RFIDToken"
            ],
            "accessibilityV2": {
                "status": "Unknown"
            }
        }
    ]
}

About us

The Shell Developer Portal is here to support partners to onboard to Shell APIs, the portal is here to take ideas to production

 

Shell logo

Contact

Get in touch
api@shell.com

 

Login to your account