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.
- Authorization : Bearer
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.
- Authorization : Bearer
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.
- Authorization : Bearer <
- 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.
- Authorization : Bearer <
- 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.
-
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.
{
"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"
}
}
]
}