Transfers
This solution lets you add transfer options from hotels and nearby airports to your hotel shopping flow with minimum effort.
What does it do?
We use the Hotel geolocation to identify nearby airports, look for available transfers with our connected providers and return them in the Quote response, within the GraphQL Extensions section.
How to implement it?
As a Buyer, you’ll need to be connected to our latest API, Hotel-X. From there, in just a few steps you can start booking one-way or round-trip transfers as an added value to your hotel offering.
- Obtain your development and/or production API Key from Servantrip and share it with us.
- Start a Hotel Search as you normally would.
- Without changes in the Hotel Quote request, you will receive a list of available transfers back and forth to the selected hotel from nearby airports.
- In Hotel Book we need the Transfer Option Identifier, returned in step (3), plus the flight number and contact details (email and phone) to successfully complete the booking process.
The reason the final client’s contact details are mandatory is so that the transfer company can be aware of any changes to the booking.
Workflow example
This workflow assumes that you have previously activated the Hotel+Transfer feature.
Search
No changes are required in this step.
Quote
You don’t have to add anything to your current structure as we will use the hotel geolocation to identify nearby airports as well as the check-in and check-out dates for arrival and departure respectively, and also the number of guests will determine the passengers to transfer.
Within the current hotel information, you will find a list of transfer options which includes information about the pick-up and drop-off locations, images, vehicle types, price, cancellation policies, paxes and baggage limits. This information is in the GraphQL Extensions section of the response.
Every transfer option comes with an OptionId that uniquely identifies the product. This identifier will be required to book a transfer in the book step.
This is the response structure (removed data information for brevity):
{
"data": {},
"extensions": {
"appStore": {
"apps": [{
"code": "ProviderTransfersApp",
"schema": "AppSchemaTransferSearch",
"data": {
"language": "en",
"country": "GB",
"locations": [{
"code": "ChIJAQAAANAxQg0R786FD-old24",
"name": "(MAD) Madrid-Barajas Adolfo Suárez Airport (MAD), Avenida de la Hispanidad, Madrid, Spain"
}, {
"code": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"name": "Claridge Madrid"
}
],
"transfers": [{
"pickupCode": "ChIJAQAAANAxQg0R786FD-old24",
"dropoffCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"name": "Shared Shuttle Transfer",
"image": "https://media.imagebank.com/resources/img/shared.png",
"vehicle": "Mercedes Sprinter, Volkswagen Transporter or similar",
"options": [{
"optionId": "VkZVNE5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UVhSUk1FVXhVa1ZaZWsxRVRrVlBWRWt3V0hwRmQwMUVSVDA9fDQyLjY4fDIwMjItMDctMTVUMDA6MDA6MDAuMDAwMDAwMCswMjowMA==",
"price": {
"currency": "EUR",
"net": 42.68
},
"tags": ["shared", "meet_point", "stops_in_between", "refundable", "no_weelchair_adapted", "no_green_friendly"],
"paxLimit": 99,
"baggage": [{
"type": "standard_suitcase",
"quantity": 3
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-14T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}, {
"optionId": "VkZVNE5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UVhSVFJVcElWV3BSTUZGVVFrVlNhazE0V0hwRmQwMUVSVDA9fDQ3Ljc0fDIwMjItMDctMTVUMDA6MDA6MDAuMDAwMDAwMCswMjowMA==",
"price": {
"currency": "EUR",
"net": 47.74
},
"tags": ["meet_point", "direct_ride", "refundable", "no_weelchair_adapted", "shared", "green_friendly"],
"paxLimit": 99,
"baggage": [{
"type": "standard_suitcase",
"quantity": 3
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-14T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
]
}, {
"pickupCode": "ChIJAQAAANAxQg0R786FD-old24",
"dropoffCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"name": "Private Standard SUV",
"image": "https://media.imagebank.com/resources/img/SUV_Standard.png",
"vehicle": "Ford Eco Sport or similar",
"options": [{
"optionId": "VkZVNE5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UVhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVTVDA9fDIxOS43OHwyMDIyLTA3LTE1VDAwOjAwOjAwLjAwMDAwMDArMDI6MDA=",
"price": {
"currency": "EUR",
"net": 219.78
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 4,
"baggage": [{
"type": "standard_suitcase",
"quantity": 4
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-14T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
]
}, {
"pickupCode": "ChIJAQAAANAxQg0R786FD-old24",
"dropoffCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"name": "Private Business SUV ",
"image": "https://media.imagebank.com/resources/img/SUV_business.png",
"vehicle": "Toyota RAV4 or similar",
"options": [{
"optionId": "VkZVNE5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UVhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVXVDA9fDI2Ny40OXwyMDIyLTA3LTE1VDAwOjAwOjAwLjAwMDAwMDArMDI6MDA=",
"price": {
"currency": "EUR",
"net": 267.49
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 4,
"baggage": [{
"type": "standard_suitcase",
"quantity": 4
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-14T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
]
}, {
"pickupCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"dropoffCode": "ChIJAQAAANAxQg0R786FD-old24",
"name": "Private Standard SUV",
"image": "https://media.imagebank.com/resources/img/SUV_Standard.png",
"vehicle": "Ford Eco Sport or similar",
"options": [{
"optionId": "VkZWTk5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UlhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVTVDA9fDE3NC40OXwyMDIyLTA3LTE5VDIxOjAwOjAwLjAwMDAwMDArMDI6MDA=",
"price": {
"currency": "EUR",
"net": 174.49
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 4,
"baggage": [{
"type": "standard_suitcase",
"quantity": 4
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-18T21:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
]
}, {
"pickupCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"dropoffCode": "ChIJAQAAANAxQg0R786FD-old24",
"name": "Private Minibus",
"image": "https://media.imagebank.com/resources/img/Minibus.png",
"vehicle": "Medium size bus",
"options": [{
"optionId": "VkZWTk5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UlhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVVVDA9fDE3NC40OXwyMDIyLTA3LTE5VDIxOjAwOjAwLjAwMDAwMDArMDI6MDA=",
"price": {
"currency": "EUR",
"net": 174.49
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 16,
"baggage": [{
"type": "standard_suitcase",
"quantity": 16
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-18T21:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}, {
"optionId": "VkZWTk5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UlhSUk1FVXhVa1ZaZWsxRVRrVlBWRWt3V0hwRmQwMUVZejA9fDE2NC42MXwyMDIyLTA3LTE5VDIxOjAwOjAwLjAwMDAwMDArMDI6MDA=",
"price": {
"currency": "EUR",
"net": 164.61
},
"tags": ["private", "meet_greet", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly"],
"paxLimit": 16,
"baggage": [{
"type": "standard_suitcase",
"quantity": 16
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-18T21:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
]
}, {
"pickupCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"dropoffCode": "ChIJW4P2yGM2Qg0RzCE_hCcBIKg",
"name": "Private Premium Sedan",
"image": "https://media.imagebank.com/resources/img/Transfer-Premium.png",
"vehicle": "Mercedes S class, Audi A8 or similar",
"options": [{
"optionId": "VkZWTk5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2VFhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVaejA9fDE5LjQ1fDIwMjItMDctMjBUMDA6MDA6MDAuMDAwMDAwMCswMjowMA==",
"price": {
"currency": "EUR",
"net": 19.45
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 6,
"baggage": [{
"type": "standard_suitcase",
"quantity": 5
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-19T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
]
}
]
}
}
]
}
}
}
Book
Once you have selected the required transfer options you need to include the corresponding option identifiers in the Book Mutation.
Within the HotelXMutation.Book there is a property called AppsInput which lets you add information required to confirm the service.
For example, to book a round-trip transfer you must specify two appsInput, one for arrival and another one for departure.
This is an example of the variable structure:
{
"appsInput": [{
"where": {
"code": "TransfersApp"
},
"data": {
"parameters": [{
"key": "OptionId",
"value": "VkZVNE5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UVhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVTVDA9fDIxOS43OHwyMDIyLTA3LTE1VDAwOjAwOjAwLjAwMDAwMDArMDI6MDA="
}, {
"key": "FlightNumber",
"value": "IB475"
}
]
}
}, {
"where": {
"code": "TransfersApp"
},
"data": {
"parameters": [{
"key": "OptionId",
"value": "VkZWTk5rNXRTVEJhYWxGNVdsUkZkRTVVWXpGYWFUQXdUbXBuZDB4VWF6UlBWMVYwV1dwQmVWbDZWbTFQUjBVeldWZE5lRmg2UlhSTlZGWkhUMFZaTkU5VlVrSlNhMDB6V0hwRmQwMUVTVDA9fDE3NC40OXwyMDIyLTA3LTE5VDIxOjAwOjAwLjAwMDAwMDArMDI6MDA="
}, {
"key": "FlightNumber",
"value": "IB473"
}
]
}
}
]
}
Additionally, in order to book Hotel + transfer, it is necessary to include all the holder’s information:
{
"holder": {
"name": "John",
"surname": "Doe",
"contactInfo": {
"phone": {
"countryCode": "+34",
"number": "123456789"
},
"email": "john@doe.com"
}
}
}
A successful response looks like this:
{
"data": {},
"extensions": {
"appStore": {
"apps": [{
"code": "ProviderTransfersApp",
"schema": "AppSchemaTransferBook",
"data": {
"status": "ok",
"reference": {
"bookingId": "EAFF6E46"
},
"holder": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"phone": {
"countryCode": "+34",
"number": "123456789"
}
},
"transfers": [{
"pickupWhen": "2022-07-15T00:00:00",
"pickupLocation": "(MAD) Madrid-Barajas Adolfo Suárez Airport (MAD), Avenida de la Hispanidad, Madrid, Spain",
"dropoffLocation": "Claridge Madrid",
"options": [{
"contact": {
"Emergency Phone": "+34 911 23 34 92"
},
"instructions": "After collecting your luggage, please make your way to the arrival hall using any of the available exits. Your name will be displayed on a TransferProvider sign. In case you cannot find your driver please contact him directly using the mobile number sent to you via SMS or use our Self Service Centre. Your driver will start waiting for you 550 minutes after flight arrival. The included free waiting time from then onward is 45 minutes.",
"optionId": null,
"provider": {
"name": "TransferProvider",
"image": "https://media.imagebank.com/resources/img/providers/logos/providerlogo_15F8F89DAFC7.png"
},
"price": {
"currency": "EUR",
"net": 219.78
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 0,
"baggage": [{
"type": "standard_suitcase",
"quantity": 4
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-14T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
],
"pickupCode": "ChIJAQAAANAxQg0R786FD-old24",
"dropoffCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"name": "Private Standard SUV",
"image": "https://media.imagebank.com/resources/img/SUV_Standard.png",
"vehicle": "Ford Eco Sport or similar"
}, {
"pickupWhen": "2022-07-19T00:00:00",
"pickupLocation": "Claridge Madrid",
"dropoffLocation": "(MAD) Madrid-Barajas Adolfo Suárez Airport (MAD), Avenida de la Hispanidad, Madrid, Spain",
"options": [{
"contact": {
"Emergency Phone": "+34 911 23 34 92"
},
"instructions": "The driver will wait for you in front of the building that you have indicated as your pick-up point. In case you cannot find your driver, please contact him directly using the mobile number sent to you via SMS or use our Self Service Centre.",
"optionId": null,
"provider": {
"name": "TransferProvider",
"image": "https://media.imagebank.com/resources/img/providers/logos/providerlogo_15F8F89DAFC7.png"
},
"price": {
"currency": "EUR",
"net": 174.49
},
"tags": ["private", "direct_ride", "refundable", "no_weelchair_adapted", "no_green_friendly", "meet_greet"],
"paxLimit": 0,
"baggage": [{
"type": "standard_suitcase",
"quantity": 4
}
],
"cancelPolicy": {
"refundable": true,
"cancelPenalties": [{
"deadline": "2022-07-18T00:00:00+02:00",
"penaltyType": "percentage",
"amount": 100.0
}
]
}
}
],
"pickupCode": "GhIJzt-EQgQ0REARJAFqatlaDcA",
"dropoffCode": "ChIJAQAAANAxQg0R786FD-old24",
"name": "Private Standard SUV",
"image": "https://media.imagebank.com/resources/img/SUV_Standard.png",
"vehicle": "Ford Eco Sport or similar"
}
]
}
}
]
}
}
}
Booking
If you need to retrieve the booked transfer information you can use the Booking List Query sending the reference of every transfer previously booked.
The AppsInput property lets you include the Transfer Booking Identifiers using variables as follows:
{
"appsInput": [
{
"where": {
"code": "TransfersApp"
},
"data": {
"parameters": [
{
"key": "BookingId",
"value": "EAFF6E46"
}
]
}
}
]
}
The response structure is the same as the book response.
Cancel
To cancel a transfer book use the following structure including BookingId and CancelReason.
{
"appsInput": [
{
"where": {
"code": "TransfersApp"
},
"data": {
"parameters": [
{
"key": "BookingId",
"value": "EAFF6E46"
},
{
"key": "CancelReason",
"value": "I will travel on other dates."
}
]
}
}
]
}
The response structure is the same as the book response.
You can see that status has the value “cancelled”.