EV Public Locations 2.1.2

Getting Started with EV Location API

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

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

Environment Details

Note: The endpoints shown in the examples throughout this documentation use the test environment hostname https://api-test.shell.com.

For production environment hostnames and complete API specifications, please refer to the OpenAPI reference documentation.

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.

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

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"
}

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 : GET
• URI : https://api-test.shell.com/ev/v2/locations
• 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/ev/v2/locations' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ************'

Sample Response

{
  "requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "status": "SUCCESS",
  "data": [
    {
      "uid": "NL*MKS*E0000001*0",
      "externalId": "01001188",
      "coordinates": {
        "latitude": 52.143814,
        "longitude": 52.143814
      },
      "operatorName": "TheNewMotion",
      "address": {
        "streetAndNumber": "Maarssenbroeksedijk 33",
        "postalCode": "3542 DM",
        "city": "Utrecht",
        "country": "NLD"
      },
      "accessibility": {
        "status": "FreePublic"
      },
      "evses": [
        {
          "uid": "NL*MKS*E0000001*0_1",
          "externalId": "01001188_1",
          "evseId": "NL*TNM*E01000401*0",
          "status": "Available",
          "updated": "2021-10-06T10:44:24Z",
          "physicalReference": "Green",
          "connectors": [
            {
              "uid": "2",
              "externalId": "01000861_1_21",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC1Phase",
                "voltage": 230,
                "amperage": 16,
                "maxElectricPower": 3.7
              }
            }
          ],
          "authorizationMethods": [
            "NewMotionApp"
          ]
        }
      ],
      "openingHours": [
        {
          "weekDay": "Mon",
          "startTime": "08:00",
          "endTime": "23:00"
        }
      ],
      "updated": "2021-10-06T10:44:24Z",
      "locationType": "Unknown",
      "operatorId": "AT-HTB"
    }
  ]
}

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 : GET
• URI : https://api-test.shell.com/ev/v2/locations/{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/ev/v2/locations/{id}' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ********'

Sample Response

{
  "requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "status": "SUCCESS",
  "data": [
    {
      "uid": "NL*MKS*E0000001*0",
      "externalId": "01001188",
      "coordinates": {
        "latitude": 52.143814,
        "longitude": 52.143814
      },
      "operatorName": "TheNewMotion",
      "address": {
        "streetAndNumber": "Maarssenbroeksedijk 33",
        "postalCode": "3542 DM",
        "city": "Utrecht",
        "country": "NLD"
      },
      "accessibility": {
        "status": "FreePublic"
      },
      "evses": [
        {
          "uid": "NL*MKS*E0000001*0_1",
          "externalId": "01001188_1",
          "evseId": "NL*TNM*E01000401*0",
          "status": "Available",
          "updated": "2021-10-06T10:44:24Z",
          "physicalReference": "Green",
          "connectors": [
            {
              "uid": "2",
              "externalId": "01000861_1_21",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC1Phase",
                "voltage": 230,
                "amperage": 16,
                "maxElectricPower": 3.7
              }
            }
          ],
          "authorizationMethods": [
            "NewMotionApp"
          ]
        }
      ],
      "openingHours": [
        {
          "weekDay": "Mon",
          "startTime": "08:00",
          "endTime": "23:00"
        }
      ],
      "updated": "2021-10-06T10:44:24Z",
      "locationType": "Unknown",
      "operatorId": "AT-HTB"
    }
  ]
}

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 : GET
• URI : https://api-test.shell.com/ev/v2/locations/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/ev/v2/locations/nearby?latitude=53.59141&longitude=10.03813' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer **********'

Sample Response

{
  "requestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "status": "SUCCESS",
  "data": [
    {
      "uid": 12,
      "externalId": "01001188",
      "coordinates": {
        "latitude": 52.143814,
        "longitude": 52.143814
      },
      "operatorName": "TheNewMotion",
      "address": {
        "streetAndNumber": "Maarssenbroeksedijk 33",
        "postalCode": "3542 DM",
        "city": "Utrecht",
        "country": "NLD"
      },
      "accessibility": {
        "status": "FreePublic",
        "remark": "optional comment"
      },
      "evses": [
        {
          "uid": 4,
          "externalId": "01001188_1",
          "evseId": "NL*TNM*E01000401*0",
          "status": "Available",
          "connectors": [
            {
              "uid": 2,
              "externalId": "01000861_1_21",
              "connectorType": "Type2",
              "electricalProperties": {
                "powerType": "AC1Phase",
                "voltage": 230,
                "amperage": 16,
                "maxElectricPower": 3.7
              },
              "fixedCable": true,
              "tariff": {
                "startFee": 0,
                "perMinute": 0.12,
                "perKWh": 0.89,
                "currency": "EUR",
                "updated": "2021-07-06T10:44:24Z",
                "updatedBy": "TariffService",
                "structure": "default"
              },
              "updated": "2021-10-06T10:44:24Z",
              "updatedBy": "TariffService",
              "deleted": "2021-12-06T10:44:24Z"
            }
          ],
          "authorizationMethods": "NewMotionApp",
          "updated": "2021-10-06T10:44:24Z",
          "deleted": "2021-10-06T10:44:24Z",
          "physicalReference": "Green"
        }
      ],
      "openingHours": [
        {
          "weekDay": "Mon",
          "startTime": "08:00",
          "endTime": "23:00"
        }
      ],
      "updated": "2021-10-06T10:44:24Z",
      "operatorComment": "promotional",
      "locationType": "Unknown"
    }
  ]
}

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 : GET
• URI : https://api-test.shell.com/ev/v2/locations/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/ev/v2/locations/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": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "status": "SUCCESS",
  "data": [
    {
      "status": "Available",
      "coordinates": {
        "latitude": 52.143814,
        "longitude": 52.143814
      },
      "evseCount": 12,
      "maxPower": 0,
      "locationCount": 6,
      "locationUid": "2057411",
      "authorizationMethods": [
        "RFIDToken"
      ]
    },
    {
      "coordinates": {
        "latitude": 52.143814,
        "longitude": 52.143814
      },
      "locationCount": 6,
      "evseCount": 10,
      "maxPower": 42
    }
  ]
}