Skip to main content

B2B EV Locations 1.0.0

Getting Started with EMobility Location APIs

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 consists of 4 end points which can be used in order to develop different user journeys.

API End Point API Functionality
/locations Get the list of all the locations and its details.
/locations/id Get the details of a particular location.
/locations/nearby Get the list of locations nearby using the latitude and longitude.
/locations/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

Shell API’s are secured by OAuth 2.0. It uses the 'Client Credentials' Grant Type to allow the API consumer to access data. The end to end process is illustrated in the sequence diagram below.

EMobility OAuth Flow

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

Once you receive the client ID & Secret, next step is to call the https://sso-uat.shell.com/as/token.oauth2 endpoint to authenticate. Following are the key parameters-

Sample cURL Request

curl --location --request POST 'https://sso.shell.com/as/token.oauth2' \
--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": "***********",
    "token_type": "Bearer",
    "expires_in": 7199
}

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.

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

  1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

  2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

Sample CURL Request

curl --location --request GET 'https://api01-uat.shell.com/mobility-ev-api/v1/api/locations' \
--header 'client_id: ***********' \
--header 'client_secret: ********' \
--header 'Authorization: Bearer *******' 

Sample Response

[
    {
        "uid": 2,
        "externalId": "01001188",
        "coordinates": {
            "latitude": 52.12352,
            "longitude": 5.042999
        },
        "operatorName": "NewMotion",
        "address": {
            "streetAndNumber": "Maarssenbroeksedijk 33",
            "postalCode": "3542 DM",
            "city": "Utrecht",
            "country": "NLD"
        },
        "accessibility": {
            "status": "Unspecified",
            "remark": ""
        },
        "evses": [
            {
                "uid": 2,
                "externalId": "01001188_1",
                "evseId": "NL*TNM*E01001188*0",
                "status": "Available",
                "connectors": [
                    {
                        "uid": 2,
                        "externalId": "0",
                        "connectorType": "Type2",
                        "electricalProperties": {
                            "powerType": "AC1Phase",
                            "voltage": 230,
                            "amperage": 16,
                            "maxElectricPower": 3.7
                        },
                        "fixedCable": false,
                        "tariff": {
                            "startFee": 0.0000,
                            "perMinute": 0.0000,
                            "perKWh": 0.0000,
                            "currency": "EUR",
                            "updated": "2021-07-06T10:44:24Z",
                            "updatedBy": "TariffService",
                            "structure": "Default"
                        },
                        "updated": "2022-02-15T14:31:19Z",
                        "updatedBy": "Feed"
                    }
                ],
                "authorizationMethods": [
                    "RFIDToken"
                ],
                "physicalReference": "NL*TNM*E01001188*0",
                "updated": "2021-09-28T08:42:35Z"
            }
        ],
        "updated": "2022-02-15T14:31:19Z",
        "operatorComment": "asd",
        "locationType": "UNKNOWN"
    },
    {
        "uid": 3,
        "externalId": "01000957",
        "coordinates": {
            "latitude": 52.362018,
            "longitude": 4.879911
        },
        "operatorName": "NewMotion",
        "address": {
            "streetAndNumber": "Tesselschadestraat 1BI",
            "postalCode": "1054 ET",
            "city": "Amsterdam",
            "country": "NLD"
        },
        "accessibility": {
            "status": "Unspecified",
            "remark": ""
        },
        "evses": [
            {
                "uid": 3,
                "externalId": "01000957_1",
                "evseId": "NL*TNM*E01000957*0",
                "status": "Occupied",
                "connectors": [
                    {
                        "uid": 3,
                        "externalId": "0",
                        "connectorType": "Type2",
                        "electricalProperties": {
                            "powerType": "AC1Phase",
                            "voltage": 230,
                            "amperage": 16,
                            "maxElectricPower": 3.7
                        },
                        "fixedCable": false,
                        "tariff": {
                            "perKWh": 0.0000,
                            "currency": "EUR",
                            "updated": "2021-10-11T12:47:57Z",
                            "updatedBy": "TariffService",
                            "structure": "Default"
                        },
                        "updated": "2022-02-15T14:31:20Z",
                        "updatedBy": "Feed"
                    }
                ],
                "authorizationMethods": [
                    "RFIDToken"
                ],
                "physicalReference": "NL*TNM*E01000957*0",
                "updated": "2021-09-28T08:42:36Z"
            }
        ],
        "updated": "2022-02-15T14:31:20Z",
        "operatorComment": "asd",
        "locationType": "UNKNOWN"
    }
]

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)

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

  1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

  2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

Sample CURL Request

curl --location --request GET 'https://api01-uat.shell.com/mobility-ev-api/v1/api/locations/2' \
--header 'client_id: *********' \
--header 'client_secret: *******' \
--header 'Authorization: Bearer ******' 

Sample Response

{
    "uid": 2,
    "externalId": "01001188",
    "coordinates": {
        "latitude": 52.12352,
        "longitude": 5.042999
    },
    "operatorName": "NewMotion",
    "address": {
        "streetAndNumber": "Maarssenbroeksedijk 33",
        "postalCode": "3542 DM",
        "city": "Utrecht",
        "country": "NLD"
    },
    "accessibility": {
        "status": "Unspecified",
        "remark": ""
    },
    "evses": [
        {
            "uid": 2,
            "externalId": "01001188_1",
            "evseId": "NL*TNM*E01001188*0",
            "status": "Available",
            "connectors": [
                {
                    "uid": 2,
                    "externalId": "0",
                    "connectorType": "Type2",
                    "electricalProperties": {
                        "powerType": "AC1Phase",
                        "voltage": 230,
                        "amperage": 16,
                        "maxElectricPower": 3.7
                    },
                    "fixedCable": false,
                    "tariff": {
                        "startFee": 0.0000,
                        "perMinute": 0.0000,
                        "perKWh": 0.0000,
                        "currency": "EUR",
                        "updated": "2021-07-06T10:44:24Z",
                        "updatedBy": "TariffService",
                        "structure": "Default"
                    },
                    "updated": "2022-02-15T14:31:19Z",
                    "updatedBy": "Feed"
                }
            ],
            "authorizationMethods": [
                "RFIDToken"
            ],
            "physicalReference": "NL*TNM*E01001188*0",
            "updated": "2021-09-28T08:42:35Z"
        }
    ],
    "updated": "2022-02-15T14:31:19Z",
    "operatorComment": "asd",
    "locationType": "UNKNOWN"
}

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.

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

  1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

  2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

  • Method : POST
  • URI : https://api01-uat.shell.com/mobility-ev-api/v1/api/locations/nearby
  • Headers :
    • client_id : <>
    • client_secret : <>
    • Authorization : Bearer <> (Access Token generated from the OAuth end point)
  • 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://api01-uat.shell.com/mobility-ev-api/v1/api/locations/nearby?latitude=52.3642070&longitude=4.8917930' \
--header 'client_id: ********' \
--header 'client_secret: ********' \
--header 'Authorization: Bearer ********

Sample Response

[
    {
        "location": {
            "uid": 1471335,
            "externalId": "090001234",
            "coordinates": {
                "latitude": 52.364207,
                "longitude": 4.891793
            },
            "operatorName": "NewMotion",
            "address": {
                "streetAndNumber": "Keizersgracht 585",
                "postalCode": "1017 DR",
                "city": "Amsterdam",
                "country": "NLD"
            },
            "accessibility": {
                "status": "Unspecified",
                "remark": ""
            },
            "evses": [
                {
                    "uid": 134954,
                    "externalId": "090001234_1",
                    "evseId": "NL*TNM*E090001234*0",
                    "status": "Unknown",
                    "connectors": [
                        {
                            "uid": 539476,
                            "externalId": "0",
                            "connectorType": "Type2",
                            "electricalProperties": {
                                "powerType": "AC3Phase",
                                "voltage": 230,
                                "amperage": 32,
                                "maxElectricPower": 22.1
                            },
                            "fixedCable": false,
                            "tariff": {
                                "perKWh": 0.0000,
                                "currency": "EUR",
                                "updated": "2021-10-11T12:50:34Z",
                                "updatedBy": "TariffService",
                                "structure": "Default"
                            },
                            "updated": "2022-02-15T14:30:48Z",
                            "updatedBy": "Feed"
                        }
                    ],
                    "authorizationMethods": [
                        "NewMotionApp",
                        "RFIDToken"
                    ],
                    "physicalReference": "NL*TNM*E090001234*0",
                    "updated": "2021-09-28T08:42:10Z"
                }
            ],
            "updated": "2022-02-15T14:30:48Z",
            "operatorComment": "asd",
            "locationType": "UNKNOWN"
        },
        "distance": 0.0
    },
    {
        "location": {
            "uid": 1471341,
            "externalId": "ICUEVE000297",
            "coordinates": {
                "latitude": 52.364207,
                "longitude": 4.891793
            },
            "operatorName": "NewMotion",
            "address": {
                "streetAndNumber": "Keizersgracht 585",
                "postalCode": "1017 DR",
                "city": "Amsterdam",
                "country": "NLD"
            },
            "accessibility": {
                "status": "Unspecified",
                "remark": ""
            },
            "evses": [
                {
                    "uid": 134960,
                    "externalId": "ICUEVE000297_1",
                    "evseId": "NL*TNM*EICUEVE000297*0",
                    "status": "Available",
                    "connectors": [
                        {
                            "uid": 539482,
                            "externalId": "0",
                            "connectorType": "Type2",
                            "electricalProperties": {
                                "powerType": "AC3Phase",
                                "voltage": 230,
                                "amperage": 32,
                                "maxElectricPower": 22.1
                            },
                            "fixedCable": false,
                            "tariff": {
                                "perKWh": 0.0000,
                                "currency": "EUR",
                                "updated": "2021-10-11T12:50:35Z",
                                "updatedBy": "TariffService",
                                "structure": "Default"
                            },
                            "updated": "2022-02-15T14:31:16Z",
                            "updatedBy": "Feed"
                        }
                    ],
                    "authorizationMethods": [
                        "NewMotionApp",
                        "RFIDToken"
                    ],
                    "physicalReference": "NL*TNM*EICUEVE000297*0",
                    "updated": "2021-11-18T09:27:06Z"
                },
                {
                    "uid": 134961,
                    "externalId": "ICUEVE000297_2",
                    "evseId": "NL*TNM*EICUEVE000297*1",
                    "status": "Available",
                    "connectors": [
                        {
                            "uid": 539483,
                            "externalId": "0",
                            "connectorType": "Type2",
                            "electricalProperties": {
                                "powerType": "AC3Phase",
                                "voltage": 230,
                                "amperage": 32,
                                "maxElectricPower": 22.1
                            },
                            "fixedCable": false,
                            "tariff": {
                                "perKWh": 0.0000,
                                "currency": "EUR",
                                "updated": "2021-10-11T12:50:35Z",
                                "updatedBy": "TariffService",
                                "structure": "Default"
                            },
                            "updated": "2022-02-15T14:31:17Z",
                            "updatedBy": "Feed"
                        }
                    ],
                    "authorizationMethods": [
                        "NewMotionApp",
                        "RFIDToken"
                    ],
                    "physicalReference": "NL*TNM*EICUEVE000297*1",
                    "updated": "2021-11-18T09:27:08Z"
                }
            ],
            "updated": "2022-02-15T14:31:17Z",
            "operatorComment": "asd",
            "locationType": "UNKNOWN"
        },
        "distance": 0.0
    }
]

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.

WARNING

Please note that there will 2 set of credentials provided by Shell to access the EMobility APIs.

  1. One set of credentials (Client ID and Client Secret) is for the OAuth end point using which accessToken will be generated that needs to be passed on all the other APIs in the header. (We will refer to them as OAuth Client Credentials)

  2. Second set of credentials (Client ID and Client Secret) needs to be passed on all the locations and charging end points in the header along with the access token which was generated using the above step. (We will refer to them as API Client Credentials)

Key Request Parameters

  • Method : POST
  • URI : https://api01-uat.shell.com/mobility-ev-api/v1/api/locations/markers
  • Headers :
    • client_id : <>
    • client_secret : <>
    • Authorization : Bearer <> (Access Token generated from the OAuth end point)
  • 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://api01-uat.shell.com/mobility-ev-api/v1/api/locations/markers?west=52.320513814822&south=4.87335773540221&east=4.87335773540221&north=4.87335773540221&zoom=10' \
--header 'client_id: *********' \
--header 'client_secret: *********' \
--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.


[
    {
        "markerType": "SingleLocation",
        "uniqueKey": "2057049_1",
        "status": "Unknown",
        "coordinates": {
            "latitude": 1.285604,
            "longitude": 103.861106
        },
        "evseCount": 2,
        "geoHash": "w21z76j3",
        "locationUid": 2057049,
        "authorizationMethods": [
            "NewMotionApp",
            "RFIDToken"
        ]
    },
    {
        "markerType": "SingleLocation",
        "uniqueKey": "2057046_1",
        "status": "Unknown",
        "coordinates": {
            "latitude": 1.281098,
            "longitude": 103.852079
        },
        "evseCount": 1,
        "geoHash": "w21z71ny",
        "locationUid": 2057046,
        "authorizationMethods": [
            "NewMotionApp",
            "RFIDToken"
        ]
    },
    {
        "markerType": "SingleLocation",
        "uniqueKey": "2057079_1",
        "status": "Unknown",
        "coordinates": {
            "latitude": 1.27957,
            "longitude": 103.85521
        },
        "evseCount": 1,
        "geoHash": "w21z72cn",
        "locationUid": 2057079,
        "authorizationMethods": [
            "NewMotionApp",
            "RFIDToken"
        ]
    }
]

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