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 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.
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-
- Method: POST
- Authorization Type: OAuth 2.0
- Auth URI: https://sso-uat.shell.com/as/token.oauth2
- Client_Id: **** (OAuth Client ID)
- Client Secret: **** (OAuth Client Secret)
- Grant Type: client_credentials
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.
-
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)
-
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
- Headers :
- client_id :
API Client ID to be passed here - client_secret :
API Client Secret to be passed here - Authorization : Bearer
access_token(Access Token generated from the OAuth end point)
- client_id :
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.
-
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)
-
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/{uid}
- Headers :
- client_id :
API Client ID to be passed here - client_secret :
API Client Secret to be passed here - Authorization : Bearer
access_token(Access Token generated from the OAuth end point)
- client_id :
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.
-
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)
-
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)
- client_id : <
- 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.
-
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)
-
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)
- client_id : <
- 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.
-
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.
-
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"
]
}
]