Documentation

Availability Simple Transfers logo icon


Availability is the first operation in the booking flow of APItude, it allows to check which available transfer services can be booked in the requested area for a given range of dates and for a given passengers group.

Remenber API can work with following types codes :

  • IATA : Airport standard (recommended).
  • ATLAS : HB custom hotel codes (recommended).
  • GPS : Latitude and longitude coordinates, A minimun of three decimal places is required to ensure adequate positional accuracy (description and complete address must be indicated during confirmation)
  • PORT : HB custom port codes
  • STATION : HB custom stations codes


In case you already have stored the HB Atlas codes you can use them, as they will be the same, if not you must obtain and cache the routes and content (optional) usingTransfers CACHEAPI, as it's designed to return all the static information and routes needed to operate the Transfers BookingAPI as quickly and simple as possible.

GET https://api.test.hotelbeds.com/transfer-api/1.0/availability/ {{language}} /from/ {{fromType}} / {{fromCode}} /to/ {{toType}} / {{toCode}} / {{outbound}} / {{inbound}} / {{adults}} / {{children}} / {{infants}}


Request parameters

Parameter Type Mandatory Description
language String Y Requested language code shared with Experiences, mapping found in language codes
fromType String Y Pickup type code (IATA, ATLAS, GPS...)
fromCode String Y Pickup code (depending on selected type)
toType String Y Drop off type code (IATA, ATLAS, GPS...)
toCode String Y Drop off code (depending on selected type)
outbound String Y Departure dateTime
inbound String N Return dateTime (in case of roundtrip)
adults Int Y Number of adult passengers (13~99)
children Int Y Number of child passengers (3~12)
infants Int Y Number of infant passengers (0~2)



See example of request simple one way:

GET https://api.test.hotelbeds.com/transfer-api/1.0/availability/en/from/ATLAS/265/to/IATA/PMI/2021-08-17T12:15:00/2/0/0

Providing only "outbound" dateTime, will return only one way.



See example of request simple rountrip:

GET https://api.test.hotelbeds.com/transfer-api/1.0/availability/en/from/ATLAS/265/to/IATA/PMI/2021-08-17T12:15:00/2021-08-25T20:00:00/2/0/0

Providing "outbound" and "inbound" dateTime, will return round trip also


NOTE: Additionally if you need to request a full itinerary, or multiple routes at once, you can use Multiple Availability



Availability Response

The transfer availability response contains all information necessary to confirm the reservation or to recheck availability for a particular transfer service.

It is distributed in hotel nodes which contain the information about the hotel and the different rates with their room types and board types.

Response Parameters

Node/Attribute Type Description
RS Element Top Element
RS/search Element Information on the performed search
RS/search/language String Code of the requested language
RS/search/departure Element Departure datetime information
RS/search/departure/date String Departure date
RS/search/departure/time String Departure time
RS/search/comeBack String Return datetime information
RS/search/comeBack/date String Return date
RS/search/comeBack/time String Return time
RS/search/occupancy Element Passenger group information
RS/search/occupancy/adults Int Number of adult passengers
RS/search/occupancy/children Int Number of children passengers
RS/search/occupancy/infants Int Number of infant passengers
RS/search/from Element Departure point information
RS/search/from/code String Departure location code
RS/search/from/description String Departure location description
RS/search/from/type String Departure location code type
RS/search/to Element Destination point information
RS/search/to/code String Destination point code
RS/search/to/description String Destination location description
RS/search/to/type String Destination location code type
RS/services Array of service elements List of available transfer services
RS/services/service Element Information of the transfer service
RS/services/service/id Int Service id code
RS/services/service/direction String

Direction of travel. Possible values:

  • DEPARTURE
  • ARRIVAL
RS/services/service/transferType String

Transfer type. Possible values:

  • SHARED
  • PRIVATE
RS/services/service/vehicle Element Information of the vehicle
RS/services/service/vehicle/code String Vehicle code id
RS/services/service/vehicle/name String Vehicle name
RS/services/service/category Element Service category information
RS/services/service/category/code String Category code
RS/services/service/category/name String Category name
RS/services/service/pickupInformation Element Information regarding the pickUp locations
RS/services/service/pickupInformation/from Element Information regarding the pickUp origin location
RS/services/service/pickupInformation/from/code String Code of the pickUp origin location
RS/services/service/pickupInformation/from/description String Description of the pickUp origin location
RS/services/service/pickupInformation/from/type String

PickUp destination location code type. Possible values:

  • ATLAS
  • IATA
  • PORT
  • STATION
  • GPS
RS/services/service/pickupInformation/to Element Information regarding the pickUp destination location
RS/services/service/pickupInformation/to/code String Code of the pickUp destination location
RS/services/service/pickupInformation/to/description String Description of the pickUp destination location
RS/services/service/pickupInformation/to/type String

PickUp destination location code type. Possible values:

  • ATLAS
  • IATA
  • PORT
  • STATION
  • GPS
RS/services/service/pickupInformation/date String Pickup date
RS/services/service/pickupInformation/time String Pickup time
RS/services/service/pickupInformation/pickup Element Information of the pickup
RS/services/service/pickupInformation/pickup/address String Physical address of the pickup
RS/services/service/pickupInformation/pickup/number String Number of the address of the pickup
RS/services/service/pickupInformation/pickup/town String City name of the address of the pickup
RS/services/service/pickupInformation/pickup/zip String Postal code of the address of the pickup
RS/services/service/pickupInformation/pickup/description String Pickup description an instructions to reach the place
RS/services/service/pickupInformation/pickup/altitude String Elevation from sea level
RS/services/service/pickupInformation/pickup/latitude String Latitude data for geolocation
RS/services/service/pickupInformation/pickup/longitude String Longitude data for geolocation
RS/services/service/pickupInformation/pickup/checkPickup Int Indicates if the provider offers website for checkin
RS/services/service/pickupInformation/pickup/checkPickup/mustCheckPickupTime Boolean false means that it is not necessary to show this field, true means that the pick-up details time will be provided by supplier under the next conditions
RS/services/service/pickupInformation/pickup/checkPickup/url Int Show the website where the supplier will load the pick-up time
RS/services/service/pickupInformation/pickup/checkPickup/hoursBeforeConsulting Int Indicate with how many hours in advance will the supplier load the pick-up time on the website
RS/services/service/pickupInformation/pickup/pickupId Int The information of this tag has been deprecated in the current API, the response will always be null
RS/services/service/pickupInformation/pickup/stopName String The information of this tag has been deprecated in the current API, the response will always be null
RS/services/service/pickupInformation/pickup/image String Image/map to help locate the pickup
RS/services/service/minPaxCapacity Int Mininum number of passengers needed to book the transfer service
RS/services/service/maxPaxCapacity Int Passenger limit of the transfer service
RS/services/service/content Element Static information of the transfer service
RS/services/service/content/vehicle Element Information of the vehicle used in the transfer service
RS/services/service/content/vehicle/code String Vehicle code used in the transfer service
RS/services/service/content/vehicle/name String Name of the type of the vehicle used in the transfer service
RS/services/service/content/category Element Information of the category of the transfer service
RS/services/service/content/category/code String Category code of the transfer service
RS/services/service/content/category/name String Category name of the transfer service category
RS/services/service/content/images Array of image elements List of transfer pictures
RS/services/service/content/images/image Element Image information
RS/services/service/content/images/image/url String Path of the picture file
RS/services/service/content/images/image/type String The image size will be unique regardless the value selected.:

  • SMALL
  • MEDIUM
  • LARGE
  • EXTRALARGE
RS/services/service/transferDetailInfo Array of Objects
  • (NEW) A collection of objects providing detailed transfer information such as estimated journey time, passenger limits, and luggage allowance.
RS/services/service/transferDetailInfo/id String
  • (NEW) Unique identifier for the detail type (e.g., TRFTIME, MINPAX, MAXPAX, LUGGAGE).
RS/services/service/transferDetailInfo/name String
  • (NEW) Display name for the detail (e.g., “Transfer time”, “Minimum pax”).
RS/services/service/transferDetailInfo/description String
  • (NEW) Description of the detail (e.g., “min. Estimated journey time”, “passenger(s) minimum”).
RS/services/service/transferDetailInfo/type String
  • (NEW) Indicates the category of the detail (e.g., GENERAL_INFO).
RS/services/service/transferDetailInfo/order Null
  • (NEW) Field reserved for ordering; always returned as null.
RS/services/service/transferDetailInfo/metric Null
  • (NEW) Unit of measurement; always returned as null.
RS/services/service/transferDetailInfo/value String
  • (NEW) Value associated with the detail (e.g., “35”, “1”, “3”).
RS/services/service/transferDetailInfo/format Null
  • (NEW) Field reserved for format specification; always returned as null.
RS/services/service/customerTransferTimeInfo Array of Objects A collection of objects related with the maximum waiting time that a clients had to wait the service. In the current version this value will be always delivered null
RS/services/service/supplierTransferTimeInfo Array of Objects
  • (NEW) A collection of objects related with the maximum waiting time of suppliers in terminals. Can be null if not provided.
RS/services/service/supplierTransferTimeInfo/value String or Null
  • (NEW) Numeric value associated with the time information (e.g., maximum waiting time). Can be null if not provided.
RS/services/service/supplierTransferTimeInfo/type String
  • (NEW) Fix name related with the time-related information provided by the supplier.
RS/services/service/supplierTransferTimeInfo/metric String
  • (NEW) Specifies the unit of measurement for the value (e.g., minutes).
RS/services/service/supplierTransferTimeInfo/remarks String
  • (NEW) Provides detailed remarks or instructions related to the supplier’s time policy.
RS/services/service/content/transferRemarks String Details of the transfer and pick-up would be indicated here for the final clients
RS/services/service/content/transferRemarks/type String Would always come as CONTRACT
RS/services/service/content/transferRemarks/description String Text with the Details of the transfer and pick-up, this very same field would be also provided at the confirmation response too
RS/services/service/content/transferRemarks/mandatory Boolean Indicates if this text is mandatory or not to be shown during the certification
RS/services/service/price Element Price information of the transfer service
RS/services/service/price/totalAmount Double Total amount of the booking
RS/services/service/price/netAmount Double Net amount of the booking
RS/services/service/rateKey String Internal key of the rate, to be used for confirmation
RS/services/service/cancellationPolicies Array of cancellationPolicy elements Information of cancellation policies
RS/services/service/cancellationPolicies/cancellationPolicy Element Cancellation policy details
RS/services/service/cancellationPolicies/cancellationPolicy/amount Double Cancellation cost
RS/services/service/cancellationPolicies/cancellationPolicy/from String Date from which cancellation policy applies. The date and time are always based on the destination's local time
RS/services/service/cancellationPolicies/cancellationPolicy/utcOffset String
  • (NEW) Cancellation policy responses will now include the UTC offset of the destination
RS/services/service/cancellationPolicies/cancellationPolicy/currencyId String Currency information
RS/services/service/links Array of link elements Information on the navigation links available from the current operation
RS/services/service/links/link Element Link information
RS/services/service/links/link/rel String Specifies the relationship between the current document and the linked document/resource
RS/services/service/links/link/href String Specifies the path of the resource the link goes to
RS/services/service/factsheetId Int Content card number associated with the transfer, identifies the relationship between type of vehicle, type of service and type of transfer
RS/services/service/operationTimes Array of Objects
  • (NEW) A collection of objects that define the service’s operational schedule.
  • Optional: Only present for services that are not available 24/7 and require specific operating hours and days.
RS/services/service/operationTimes/open String
  • (NEW) First hour where the service is available..
  • Format defined by the format attribute (default: HH:mm).
RS/services/service/operationTimes/close String
  • (NEW) Last hour where the service is available.
  • Format defined by the format attribute (default: HH:mm).
RS/services/service/operationTimes/format String
  • (NEW) Specifies the time format used (e.g., HH:mm).
RS/services/service/operationTimes/daysOfTheWeek Array of Strings
  • (NEW) List of days when the defined operating schedule applies.
  • Possible values: SUN, MON, TUE, WED, THU, FRI, SAT.

Availability Response

{
    "search": {
        "language": "en",
        "departure": {
            "date": "2024-01-11",
            "time": "11:25:00"
        },
        "comeBack": {
            "date": "-999999999-01-01",
            "time": "00:00:00"
        },
        "occupancy": {
            "adults": 2,
            "children": 0,
            "infants": 0
        },
        "from": {
            "code": "683772",
            "description": "Staycity Aparthotels Venice Mestre",
            "type": "ATLAS"
        },
        "to": {
            "code": "VCE",
            "description": "Venice Marco Polo Airport",
            "type": "IATA"
        }
    },
    "services": [
        {
            "id": 0,
            "direction": "DEPARTURE",
            "transferType": "PRIVATE",
            "vehicle": {
                "code": "CR",
                "name": "Car"
            },
            "category": {
                "code": "STND",
                "name": "Standard"
            },
            "pickupInformation": {
                "from": {
                    "code": "683772",
                    "description": "Staycity Aparthotels Venice Mestre",
                    "type": "ATLAS"
                },
                "to": {
                    "code": "VCE",
                    "description": "Venice Marco Polo Airport",
                    "type": "IATA"
                },
                "date": "2024-01-11",
                "time": "08:35:00",
                "pickup": {
                    "address": null,
                    "number": null,
                    "town": null,
                    "zip": null,
                    "description": "FINDING YOUR DRIVER\n\nThe Supplier will send a letter with your pickup time & place to your hotel the day before departure. Please refer to your hotel's reception desk to pick up your letter and ensure that you are at your pick up point 10/15 minutes before the confirmed time. \n\nIdentify yourself by showing this confirmation to your Supplier, for whom we act as a booking agent.\n\n\nDIFFICULTY IN LOCATING YOUR DRIVER\nContact your supplier for assistance. Do not leave without having contacted your supplier on +39 3490555567 first.\n\nIn the event you are delayed for your departure pick up you must call the supplier.",
                    "altitude": null,
                    "latitude": 45.481012750000005,
                    "longitude": 12.238736574310185,
                    "checkPickup": {
                        "mustCheckPickupTime": false,
                        "url": null,
                        "hoursBeforeConsulting": null
                    },
                    "pickupId": null,
                    "stopName": null,
                    "image": null
                }
            },
            "minPaxCapacity": 1,
            "maxPaxCapacity": 3,
            "content": {
                "vehicle": {
                    "code": "CR",
                    "name": "Car"
                },
                "category": {
                    "code": "STND",
                    "name": "Standard"
                },
                "images": [
                    {
                        "url": "https://assets.htxstaging.com/imgs/default/vehicle_set/private.jpg",
                        "type": "EXTRALARGE"
                    },
                    {
                        "url": "https://assets.htxstaging.com/imgs/default/vehicle_set/private.jpg",
                        "type": "LARGE"
                    },
                    {
                        "url": "https://assets.htxstaging.com/imgs/default/vehicle_set/private.jpg",
                        "type": "MEDIUM"
                    },
                    {
                        "url": "https://assets.htxstaging.com/imgs/default/vehicle_set/private.jpg",
                        "type": "SMALL"
                    }
                ],
                "transferDetailInfo": [
                    {
                        "id": "0",
                        "name": "20 min. Estimated journey time",
                        "description": "20 min. Estimated journey time",
                        "type": "GENERAL_INFO"
                    },
                    {
                        "id": "1",
                        "name": "1 passenger(s) minimum",
                        "description": "1 passenger(s) minimum",
                        "type": "GENERAL_INFO"
                    },
                    {
                        "id": "2",
                        "name": "3 passenger(s) maximum",
                        "description": "3 passenger(s) maximum",
                        "type": "GENERAL_INFO"
                    },
                    {
                        "id": "3",
                        "name": "3 suitcases permitted",
                        "description": "3 suitcases permitted",
                        "type": "GENERAL_INFO"
                    }
                ],
                "customerTransferTimeInfo": [],
                "supplierTransferTimeInfo": [],
                "transferRemarks": [
                    {
                        "type": "CONTRACT",
                        "description": "FINDING YOUR DRIVER\n\nThe Supplier will send a letter with your pickup time & place to your hotel the day before departure. Please refer to your hotel's reception desk to pick up your letter and ensure that you are at your pick up point 10/15 minutes before the confirmed time. \n\nIdentify yourself by showing this confirmation to your Supplier, for whom we act as a booking agent.\n\n\nDIFFICULTY IN LOCATING YOUR DRIVER\nContact your supplier for assistance. Do not leave without having contacted your supplier on +39 3490555567 first.\n\nIn the event you are delayed for your departure pick up you must call the supplier.",
                        "mandatory": true
                    }
                ]
            },
            "price": {
                "totalAmount": 57.81,
                "netAmount": 0.00,
                "currencyId": "EUR"
            },
            "rateKey": "DEPARTURE|ATLAS|683772|IATA|VCE|2024-01-11|08:35|2024-01-11|11:25|2~0~0||3|||||207|PRVT||CR|STND|57.81||||43|VCE|SIMPLE|c3ac92dce02dad3ba3baef7ab71f6673|1255239|T|1b3814dfc98b4495220e3ecb1ff1ee6f",
            "cancellationPolicies": [
                {
                    "amount": 57.81,
                    "from": "2024-01-09T11:25:00",
                    "currencyId": "EUR",
                    "isForceMajeure": null
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "/availability",
                    "method": "GET"
                },
                {
                    "rel": "confirm",
                    "href": "/booking",
                    "method": "POST"
                }
            ],
            "factsheetId": 43
        }
    ]
}