Getting Started with B2B Mobility Sites
B2B Mobility Sites provides the complete list of all Shell location. The list includes all Shell network and all locations available through our roaming partners.
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.
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
Once you receive the client ID & Secret, next step is to call the https://api-test.shell.com/oauth/v1/mobility/token endpoint to authenticate. Following are the key parameters-
- Method: POST
- Authorization Type: OAuth 2.0
- Auth URI: https://api-test.shell.com/oauth/v1/mobility/token
- Client_Id: **** (OAuth Client ID)
- Client Secret: **** (OAuth Client Secret)
- Grant Type: client_credentials
Sample cURL Request
curl --location --request POST 'https://api-test.shell.com/oauth/v1/mobility/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": "***********",
"token_type": "Bearer",
"expires_in": 899
}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
This Endpoint provides the list of all Shell Fuel locations. The list includes all Shell network and all locations available through out our roaming partners. The end point provides flexible search criteria in order to get the list of Shell Network.
Supported Search Options
- With all matches based on country code,network_groups,site_type,fuels,amenities
- Get the list of locations with below filter Options
- Fuel Type
- Amenities
- Network Type
- Truck Services
- Supports pagination
Business Case - 1
Customer wants to download the complete list of Shell Locations globally.
Introduction
- Note that API has pagination, so default number of records per page is 20.
- So if you want to get the complete list of locations globally, then you need to use 2 query parameters
- pageSize : You need to set the number of records you want to receive per page. Max value is 250. (Default value is 20)
- page : You need to provide the page number you want to access the data. You need to run iterations from 1 to n in order to get the complete list of locations.
Key Request Parameters
- Method : GET
- URI : https://api-test.shell.com/locations/v1/fuel
- Headers :
- Authorization : Bearer
access_token(Access Token generated from the OAuth end point) - RequestId : GUID in order to track and trace the request
- pageSize : Number of records per page (Eg: 200)
- page : Page number
- Authorization : Bearer
Sample cURL Request
curl --location --request GET 'https://api-test.shell.com/locations/v1/fuel?page=1&pageSize=250' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ************'Sample Response
{
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": {
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": [
{
"next_forecourt_open_status_change": null,
"forecourt_open_status": "twenty_four_hour",
"next_shop_open_status_change": null,
"shop_open_status": "unknown",
"next_open_status_change": null,
"open_status": "twenty_four_hour",
"lat": 33.6157,
"lng": 72.9905,
"country_code": "PK",
"address": "DHOKE SYEDAN",
"city": "RAWALPINDI",
"state": "Punjab",
"postcode": "46120",
"country": "Pakistan",
"distance": null,
"driving_distance": null,
"driving_duration": null,
"tz_offset": 18000,
"id": "10041379",
"name": "FAUJI SERVICE STATION",
"telephone": "+92 51 5684384",
"amenities": [
"carwash",
"air_and_water",
"full_service",
"twenty_four_hour",
"manual",
"manned"
],
"fuels": [
"midgrade_gasoline",
"shell_regular_diesel"
],
"truck_services": [],
"partner": false,
"network_group": "non_core",
"brand": "shell",
"inactive": false,
"links": {
"self": "https://scolapi2prod.geotest.me:/v1/locations/10041379?locale=en_GB&translations=true",
"related": {
"shell_station_pages_href": "https://find.shell.com/pk/fuel/10041379-fauji-service-station",
"locator_href": "https://scol.com?id=10041379"
}
},
"translations": {},
"ev_charging": null,
"third_party_ev_location": false,
"esi_code": "9321",
"manned": true,
"manning_status": "manned",
"opening_hours": [
{
"days": [
"Mon",
"Sun"
],
"hours": [
[
"00:00",
"23:59"
]
]
}
],
"forecourt_opening_hours": [
{
"days": [
"Mon",
"Sun"
],
"hours": [
[
"00:00",
"23:59"
]
]
}
],
"shop_opening_hours": []
}
]
}
}Business Case - 2
Customer wants to download list of locations from 2 specific countries. Lets take example with GB and DE
Introduction
- Note that API has pagination, so default number of records per page is 20.
- So if you want to get the complete list of locations from 2 specific countries, then you need to use 4 query parameters
- pageSize : You need to set the number of records you want to receive per page. Max value is 250. (Default value is 20)
- page : You need to provide the page number you want to access the data. You need to run iterations from 1 to n in order to get the complete list of locations.
- countryCode : You need to provide the 1st country code in ISO 3166-1 alpha-2 format.
- countryCode : You need to provide the 2nd country code in ISO 3166-1 alpha-2 format.
- Please note that you need to repeat the query parameter (countryCode) in the request if you want to have more countries. Eg: N number of times query param needs to be passed to get N number of countries.
Key Request Parameters
- Method : GET
- URI : https://api-test.shell.com/locations/v1/fuel
- Headers :
- Authorization : Bearer
access_token(Access Token generated from the OAuth end point) - RequestId : GUID in order to track and trace the request
- pageSize : Number of records per page (Eg: 200)
- page : Page number
- countryCode : ISO 3166-1 alpha-2 format
- countryCode : ISO 3166-1 alpha-2 format
- Authorization : Bearer
Sample cURL Request
curl --location --request GET 'https://api-test.shell.com/locations/v1/fuel?page=1&pageSize=1&countryCode=GB&countryCode=DE' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ************'Sample Response
{
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": {
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": [
{
"next_forecourt_open_status_change": null,
"forecourt_open_status": "twenty_four_hour",
"next_shop_open_status_change": null,
"shop_open_status": "unknown",
"next_open_status_change": null,
"open_status": "twenty_four_hour",
"lat": 52.607296,
"lng": 0.057126,
"country_code": "GB",
"address": "A47 THORNEY ROAD",
"city": "Wisbech",
"state": "Cambridgeshire",
"postcode": "PE13 4AA",
"country": "United Kingdom",
"distance": null,
"driving_distance": null,
"driving_duration": null,
"tz_offset": 3600,
"id": "10019755",
"name": "AUTO PITSTOP",
"telephone": "+44 1945 450222",
"amenities": [
"mobile_payment",
"loyalty_cards",
"full_service",
"twenty_four_hour",
"shop",
"adblue_pack",
"go_plus",
"paypal",
"manned"
],
"fuels": [
"premium_gasoline",
"fuelsave_midgrade_gasoline",
"fuelsave_regular_diesel"
],
"truck_services": [
"adblue_truck"
],
"partner": false,
"network_group": "coverage",
"brand": "shell",
"inactive": false,
"links": {
"self": "https://scolapi2prod.geotest.me:/v1/locations/10019755?locale=en_GB&translations=true",
"related": {
"shell_station_pages_href": "https://find.shell.com/gb/fuel/10019755-auto-pitstop",
"locator_href": "https://scol.com?id=10019755"
}
},
"translations": {},
"ev_charging": null,
"third_party_ev_location": false,
"esi_code": "2010",
"manned": true,
"manning_status": "manned",
"opening_hours": [
{
"days": [
"Mon",
"Sun"
],
"hours": [
[
"00:00",
"23:59"
]
]
}
],
"forecourt_opening_hours": [
{
"days": [
"Mon",
"Sun"
],
"hours": [
[
"00:00",
"23:59"
]
]
}
],
"shop_opening_hours": []
},
{
"next_forecourt_open_status_change": "2022-07-20T20:00:00.010Z",
"forecourt_open_status": "open",
"next_shop_open_status_change": null,
"shop_open_status": "unknown",
"next_open_status_change": "2022-07-20T20:00:00.011Z",
"open_status": "open",
"lat": 50.966658,
"lng": 6.110871,
"country_code": "DE",
"address": "SITTARDER STR. 24",
"city": "GEILENKIRCHEN",
"state": "Nordrhein-Westfalen",
"postcode": "52511",
"country": "Germany",
"distance": null,
"driving_distance": null,
"driving_duration": null,
"tz_offset": 7200,
"id": "10025809",
"name": "GEILENKIRCHEN, SITTARDER STR.",
"telephone": "+49 2451 69160",
"amenities": [
"atm",
"standard_toilet",
"carwash",
"mobile_payment",
"air_and_water",
"loyalty_cards",
"credit_card",
"fuel_card",
"credit_card_general",
"self_service",
"fleet_card_general",
"shop",
"paypal",
"other_loyalty_cards",
"tbd",
"manned"
],
"fuels": [
"fuelsave_midgrade_gasoline",
"fuelsave_regular_diesel",
"midgrade_gasoline",
"fuelsave_98"
],
"truck_services": [],
"partner": true,
"network_group": "non_core",
"brand": null,
"inactive": false,
"links": {
"self": "https://scolapi2prod.geotest.me:/v1/locations/10025809?locale=en_GB&translations=true",
"related": {
"shell_station_pages_href": null,
"locator_href": "https://scol.com?id=10025809"
}
},
"translations": {},
"ev_charging": null,
"third_party_ev_location": false,
"esi_code": "3624",
"manned": true,
"manning_status": "manned",
"opening_hours": [
{
"days": [
"Mon",
"Fri"
],
"hours": [
[
"06:00",
"22:00"
]
]
},
{
"days": [
"Sat"
],
"hours": [
[
"07:00",
"22:00"
]
]
},
{
"days": [
"Sun"
],
"hours": [
[
"08:00",
"22:00"
]
]
}
],
"forecourt_opening_hours": [
{
"days": [
"Mon",
"Fri"
],
"hours": [
[
"06:00",
"22:00"
]
]
},
{
"days": [
"Sat"
],
"hours": [
[
"07:00",
"22:00"
]
]
},
{
"days": [
"Sun"
],
"hours": [
[
"08:00",
"22:00"
]
]
}
],
"shop_opening_hours": []
}
]
}
}
Business Case - 3
Customer wants to download list of locations in a specific country where Hydrogen fuel type is available.
Introduction
-
Note that API has pagination, so default number of records per page is 20.
-
So if you want to get the complete list of locations from a specific country where hydrogen fuel type is available, then you need to use 4 query parameters
- pageSize : You need to set the number of records you want to receive per page. Max value is 250. (Default value is 20)
- page : You need to provide the page number you want to access the data. You need to run iterations from 1 to n in order to get the complete list of locations.
- countryCode : You need to provide the 1st country code in ISO 3166-1 alpha-2 format.
- fuelType : Fuel type you would want to search. List of available Shell fuel type can be found in the OAS specs.
-
Please note that only a single fuel type can be searched at single API request.
Key Request Parameters
- Method : GET
- URI : https://api-test.shell.com/locations/v1/fuel
- Headers :
- Authorization : Bearer
access_token(Access Token generated from the OAuth end point) - RequestId : GUID in order to track and trace the request
- pageSize : Number of records per page (Eg: 200)
- page : Page number
- countryCode : ISO 3166-1 alpha-2 format
- fuelType : Fuel type
- Authorization : Bearer
Sample cURL Request
curl --location --request GET 'https://api-dev.shell.com/locations/v1/fuel?page=1&pageSize=250&countryCode=DE&fuelType=hydrogen' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer ************'Sample Response
{
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": {
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": [
{
"next_forecourt_open_status_change": "2022-07-20T20:00:00.084Z",
"forecourt_open_status": "open",
"next_shop_open_status_change": null,
"shop_open_status": "unknown",
"next_open_status_change": "2022-07-20T20:00:00.085Z",
"open_status": "open",
"lat": 51.02336,
"lng": 7.000968,
"country_code": "DE",
"address": "KARL-KREKELER STR. 2",
"city": "LEVERKUSEN",
"state": "Nordrhein-Westfalen",
"postcode": "51373",
"country": "Germany",
"distance": null,
"driving_distance": null,
"driving_duration": null,
"tz_offset": 7200,
"id": "10024589",
"name": "LEVERKUSEN, KARL-KREKELER ST.",
"telephone": "+49 214 45743",
"amenities": [
"atm",
"atm_in",
"standard_toilet",
"carwash",
"mobile_payment",
"high_speed_diesel_pump",
"food_offerings",
"bakery_shop",
"air_and_water",
"loyalty_cards",
"cafe",
"credit_card",
"fuel_card",
"credit_card_general",
"wifi",
"vacuum",
"quick_lubes",
"self_service",
"fleet_card_dkv",
"fleet_card_uta",
"deli2go",
"shell_card",
"rollover",
"shop",
"amazon_locker",
"adblue_pack",
"loyalty_program",
"paypal",
"other_loyalty_cards",
"shell_energy_rebate",
"smart_deal",
"price_guarantee",
"manned"
],
"fuels": [
"premium_diesel",
"fuelsave_midgrade_gasoline",
"fuelsave_regular_diesel",
"midgrade_gasoline",
"hydrogen",
"super_premium_gasoline",
"truck_diesel"
],
"truck_services": [
"hgv_lane",
"adblue_truck"
],
"partner": false,
"network_group": "coverage",
"brand": "shell",
"inactive": false,
"links": {
"self": "https://scolapi2prod.geotest.me:/v1/locations/10024589?locale=en_GB&translations=true",
"related": {
"shell_station_pages_href": "https://find.shell.com/de/fuel/10024589-leverkusen-karl-krekeler-st",
"locator_href": "https://scol.com?id=10024589"
}
},
"translations": {},
"ev_charging": null,
"third_party_ev_location": false,
"esi_code": "0715",
"manned": true,
"manning_status": "manned",
"opening_hours": [
{
"days": [
"Mon",
"Fri"
],
"hours": [
[
"06:00",
"22:00"
]
]
},
{
"days": [
"Sat"
],
"hours": [
[
"07:00",
"22:00"
]
]
},
{
"days": [
"Sun"
],
"hours": [
[
"08:00",
"22:00"
]
]
}
],
"forecourt_opening_hours": [
{
"days": [
"Mon",
"Fri"
],
"hours": [
[
"06:00",
"22:00"
]
]
},
{
"days": [
"Sat"
],
"hours": [
[
"07:00",
"22:00"
]
]
},
{
"days": [
"Sun"
],
"hours": [
[
"08:00",
"22:00"
]
]
}
],
"shop_opening_hours": []
}
]
}
}
Business Case - 4
Customer wants to download list of locations in a specific country where both Hydrogen fuel type and carwash facility are available together.
Introduction
-
Note that API has pagination, so default number of records per page is 20.
-
So if you want to get the complete list of locations from a specific country, where both Hydrogen fuel type and carwash facility are available, then you need to use 6 query parameters
- pageSize : You need to set the number of records you want to receive per page. Max value is 250. (Default value is 20)
- page : You need to provide the page number you want to access the data. You need to run iterations from 1 to n in order to get the complete list of locations.
- countryCode : You need to provide the 1st country code in ISO 3166-1 alpha-2 format.
- fuelType : Fuel type you would want to search. List of available Shell fuel type can be found in the OAS specification.
- amenities : Need to provide the amenity that you need to search from the list provided by Shell in the OAS specification.
- isSearchAll : To be set as TRUE in order to search for condition where locations are available with both Hydrogen fuel and car wash facility.
-
isSearchAll parameter to be set as true when you want to execute all the filters strictly. When it is set as true, then AND clause is used to search with all the filter parameters. When is set to false, then OR condition is executed.
-
Please note that only a single fuel type/amenity can be searched at single API request.
Key Request Parameters
- Method : GET
- URI : https://api-test.shell.com/locations/v1/fuel
- Headers :
- Authorization : Bearer
access_token(Access Token generated from the OAuth end point) - RequestId : GUID in order to track and trace the request
- pageSize : Number of records per page (Eg: 200)
- page : Page number
- countryCode : ISO 3166-1 alpha-2 format
- fuelType : Fuel type
- amenities : Amenities like carwash
- isSearchAll : true
- Authorization : Bearer
Sample cURL Request
curl --location --request GET 'https://api-test.shell.com/locations/v1/fuel?page=1&pageSize=1&isSearchAll=true&countryCode=DE&fuelType=hydrogen&amenities=carwash' \
--header 'RequestId: 233e4567-e89b-12d3-a456-426614174000' \
--header 'Authorization: Bearer IrlwBq2ixIV5QeBKf6EhTEeVeQXO'Sample Response
{
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": {
"requestId": "233e4567-e89b-12d3-a456-426614174000",
"status": "SUCCESS",
"data": [
{
"next_forecourt_open_status_change": "2022-07-20T20:00:00.903Z",
"forecourt_open_status": "open",
"next_shop_open_status_change": null,
"shop_open_status": "unknown",
"next_open_status_change": "2022-07-20T20:00:00.904Z",
"open_status": "open",
"lat": 51.02336,
"lng": 7.000968,
"country_code": "DE",
"address": "KARL-KREKELER STR. 2",
"city": "LEVERKUSEN",
"state": "Nordrhein-Westfalen",
"postcode": "51373",
"country": "Germany",
"distance": null,
"driving_distance": null,
"driving_duration": null,
"tz_offset": 7200,
"id": "10024589",
"name": "LEVERKUSEN, KARL-KREKELER ST.",
"telephone": "+49 214 45743",
"amenities": [
"atm",
"atm_in",
"standard_toilet",
"carwash",
"mobile_payment",
"high_speed_diesel_pump",
"food_offerings",
"bakery_shop",
"air_and_water",
"loyalty_cards",
"cafe",
"credit_card",
"fuel_card",
"credit_card_general",
"wifi",
"vacuum",
"quick_lubes",
"self_service",
"fleet_card_dkv",
"fleet_card_uta",
"deli2go",
"shell_card",
"rollover",
"shop",
"amazon_locker",
"adblue_pack",
"loyalty_program",
"paypal",
"other_loyalty_cards",
"shell_energy_rebate",
"smart_deal",
"price_guarantee",
"manned"
],
"fuels": [
"premium_diesel",
"fuelsave_midgrade_gasoline",
"fuelsave_regular_diesel",
"midgrade_gasoline",
"hydrogen",
"super_premium_gasoline",
"truck_diesel"
],
"truck_services": [
"hgv_lane",
"adblue_truck"
],
"partner": false,
"network_group": "coverage",
"brand": "shell",
"inactive": false,
"links": {
"self": "https://scolapi2prod.geotest.me:/v1/locations/10024589?locale=en_GB&translations=true",
"related": {
"shell_station_pages_href": "https://find.shell.com/de/fuel/10024589-leverkusen-karl-krekeler-st",
"locator_href": "https://scol.com?id=10024589"
}
},
"translations": {},
"ev_charging": null,
"third_party_ev_location": false,
"esi_code": "0715",
"manned": true,
"manning_status": "manned",
"opening_hours": [
{
"days": [
"Mon",
"Fri"
],
"hours": [
[
"06:00",
"22:00"
]
]
},
{
"days": [
"Sat"
],
"hours": [
[
"07:00",
"22:00"
]
]
},
{
"days": [
"Sun"
],
"hours": [
[
"08:00",
"22:00"
]
]
}
],
"forecourt_opening_hours": [
{
"days": [
"Mon",
"Fri"
],
"hours": [
[
"06:00",
"22:00"
]
]
},
{
"days": [
"Sat"
],
"hours": [
[
"07:00",
"22:00"
]
]
},
{
"days": [
"Sun"
],
"hours": [
[
"08:00",
"22:00"
]
]
}
],
"shop_opening_hours": []
}
]
}
}
