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 (description and complete address needed)
  • 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, 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
  • NEW: 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
  • NEW: 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

Type name of the picture.

  • NEW: The image size will be unique regardless the value selected.:

    • SMALL
    • MEDIUM
    • LARGE
    • EXTRALARGE
  • RS/services/service/content/transferDetailInfo Array of transferDetailInfo elements Collection of detailed information about the transfer
    RS/services/service/content/transferDetailInfo/id String Information id
    RS/services/service/content/transferDetailInfo/name String Information name
    RS/services/service/content/transferDetailInfo/description String Details and information on the transfer
    RS/services/service/content/transferDetailInfo/type String

    Transfer detail info type. Possible values:

    • GENERAL_INFO
    RS/services/service/content/transferDetailInfo/value String This value will be usually null can be ignored
    RS/services/service/content/customerTransferTimeInfo String
    • NEW: The information of this tag has been deprecated in the current API, the response will always be null
    RS/services/service/content/supplierTransferTimeInfo String
    • NEW: The information of this tag has been deprecated in the current API, the response will always be null
    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
    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

    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
            }
        ]
    }