Documentation

Availability Transfers logo icon

The calendar API request returns the content for all the activities requested, depending on the filters being used, in the response you’ll also see the operational dates, so you can create your calendar according to the information being returned.

POST https://api.hotelbeds.com/activity-api/3.0/activities/availability

The availability search requires to include the pax distribution.

You can use any filters (see filters section) the results will be according to the filters selected.

{
	"filters": [{
			"searchFilterItems": [{
					"type": "destination",
					"value": "BCN"
				}
			]
		}
	],
	"from": "2022-05-11",
	"to": "2022-06-22",
	"paxes": [{
			"age": 30
		}
	],
	"language": "en",
	"pagination": {
		"itemsPerPage": 100,
		"page": 1
	},
	"order": "DEFAULT"
}

From a business perspective, the response returned by the API contains:

Service information: code, name, picture and description.
Modalities available including code and name
Contents factsheet code.
Lowest price for each service’s modality and considering it by pax type for the given request dates. Also the Box office price (price at the gate or counter of the activity) is returned in the response of the call. The box office price it is not the selling price but can be compared against it.
Cancellation policies, including a date from and to in which the cancellation policy applies and the amount.

NODE/ATTRIBUTE	DATA TYPE	DESCRIPTION
operationId	String	Factsheet Operational ID, informative only.
Errors	List	Contains a list of errors (error code and error description). Here you can find a list of errors and their meaning
errors/@code	String	Error code
errors/@text	String	Error description
pagination	Element	This element indicates the values for pagination
pagination/@itemsPerPage	Integer	Number of items per page
pagination/@page	Integer	Number of page
pagination/@totalItems	Integer	Total items returned in the search including the ones in the current page.
auditData	Element	This element contains internal information. You can provide it in the event of needing specific support.
activities	List	List of activities available
activities/@code	String	Service code
activities/@order	Integer	Activity order in the list of activities returned
activities/@type	String	Type of activity being returned: TICKET: Standard ticket.
activities@country	Object	Provides the country information together with the destinations that are included in the particular country.
activities/country/@code	String	Country code where the activity takes place. See Country codes in the Contents API.
activities/country/@name	String	Country name where the activity takes place. It will be provided in the same language as the request indicated
activities/country/@destinations	List	A list of destinations. In the response we will always return one and only one destination for the particular product.
activities/country/destinations/@node	String	Destination code where the activity takes place. See Destination codes in the Contents API.
activities/country/destinations/@name	String	Destination name where the activity takes place. . See Destination codes in the Contents API.
activities/@name	String	Name of the activity. It will be returned in the same language as the request indicated.
activities/amountsFrom	Object	Lowest price for the activity in the given dates. A detail of the pax type, amount for that pax type and box office price is provided in a deeper level.
activities/amountsFrom/@paxType	String	Type of Passenger (ADULT, CHILD)
activities/amountsFrom/@amount	BigDecimal	Price from for the pax type.
activities/amountsFrom/@boxOfficeAmount	BigDecimal	Box office Price from for the pax type The Box office price is the price value at the gate or counter. It is not the selling price of the activity but it can be taken into consideration for the comparison of the price if not booked in advance.
activities/@currency	String	Currency in which the prices are returned. See Contents API for more details.
activities/@currencyName	String	Activity currency name. It will be provided in the same language as the request indicated
activities/@content	Object	This object contains all content factsheet information that is relevant for that particular product. The infromation is the same as the one detailed in the detail response. Its structure is exactly the same as in the detail. Please refer to it. Nevertheless a brief summary of all attributes is provided here.
activities/content/@contentId	String	Content Factsheet code.
activities/content/@Name	String	Name of the activity. It will be returned in the same language as the request indicated.
activities/content/@geolocation	Coordinate	Activity geolocation in GPS coordinates. Contains Latitude and Longitude (please refer to activitiesContent in detail response.
activities/content/@description	String	Activity full description. It will be provided in the same language as the request indicated
activities/content/@media	List More attributes are included as part of this list. These are not detailed here but in the Detail Response.	This list is detailed in detail response. In this operation of Search only one media image will be returned with the full information as detailed in the Detail Response.
activities/content/@location	List More attributes are included as part of this list. These are not detailed here but in the Detail Response.	This list is detailed in detail response. In this operation of Search will return the relevant location as detailed in the Detail Response.
activities/content/@segmentationGroups	List More attributes are included as part of this list. These are not detailed here but in the Detail Response.	This list is detailed in detail response. In this operation of Search will return the relevant segmentation group as detailed in the Detail Response.
activities/content/@featureGroups	List More attributes are included as part of this list. These are not detailed here but in the Detail Response.	This list is detailed in detail response. In this operation of Search will return the relevant segmentation group as detailed in the Detail Response.
activities/Content/@guidingOptions	GuidingOptions More attributes are included as part of this list. These are not detailed here but in the Detail Response.	If the activity is a guided activity, the following attributes provide details of the attributes of the guiding.
activities/Content/@redeeminfo	String	The type can have the following values: - "EVOUCHER" - The voucher is required to be presented however, this can be provided in digital. No need to printed but it is still mandatory to show it. - "PRINTED" -The voucher must be printed in paper and shown at the entrance to enjoy the activity. - "VOUCHERLESS" - There’s no need to show a voucher, but a valid information such as a supplier confirmation number and an ID (i.e. passport) shall be provided before enjoying the activity. An example of this is Disney Orlando where a Disney Ticket Confirmation Number is given to the customer. The client can take this written out or save as a note in the phone but no voucher is required to be presented. - NONE - No voucher is required.
activities/@url	String	Optionally, a URL that points to a landing site to purchase the product can be returned. Depending on how you are planning to sell your product different solutions can be provided for example whitelabels, B2C sites… Please, ask integrations.btb@hotelbeds.com for more details.
activities/promotions	List	List of promotions for a specific activity. A promotion includes a badge (see promotions/@imagePath below) and application dates. Examples of promotions are: “Free Drink”, “Free children” or not related to price elements such as “Top Seller” Integrated clients can use promotions to enhance the activities presented in their websites or apps.
activities/promotions@order	Integer	Promotion order for the list of promotions retrieved
activities/promotions@code	String	Promotion code
activities/promotions@imagePath	String	Promotion image path
activities/promotions@description	String	Promotion description. It will be provided in the same language as the request indicated
activities/promotions@name	String	Promotion name. It will be provided in the same language as the request indicated
activities/promotions@dateFrom	Date	Promotion is applicable from: dateFrom
activities/promotions@dateTo	Date	Promotion is applicable until: dateTo
activities/modalities	List	List of modalities for a specific activity.
activities/modalities@code	String	Modality code
activities/modalities@duration	Double	The duration is given in Dates, Hours or Minutes depending on the activity that is returned. Some activities duration is higher than one day. If that’s the case, please calculate the desired dates to be passed to the “detail” operation.
activities/modalities@name	String	Modality name. It will be provided in the same language as the request indicated
activities/modalities/amountsFrom	Object	Amounts object type. Cheapest price for this modality
activities/modalities/amountsFrom/@paxType	String	Type of Passenger (ADULT, CHILD)
activities/modalities/amountsFrom/@amount	BigDecimal	Total amount for the modality
activities/modalities/amountsFrom/@boxOfficeAmount	BigDecimal	Modality amount from the box office
activities/modalities/amountsFrom/@ageFrom	Integer	Is the age from that is linked to the specific amount provided in the @amount attribute.
activities/modalities/amountsFrom/@ageTo	Integer	Is the age To (together with the age from represent the ages in between the amount is valid) for a particular amount.
activities/modalities/cancellationPolicies	Object	CancellationPolicies object type. Modality cancellation price. Please, see an example of returned cancellation policies below to understand how the cancellation costs are calculated.
activities/modalities/cancellationPolicies/@dateFrom	Date	Starting from the specified date, cancellation costs are applied. Each cancellation policy includes a date and an amount. That means, starting from the date, the amount is applied, please also be aware that the date and time are calculated based on local time in the destination. Please, see an example of returned cancellation policies below to understand how the cancellation costs are calculated.
activities/modalities/cancellationPolicies/@amount	BigDecimal	Cancellation cost starting on the specified dateFrom in the specified at activity level under activities/@currency

Specific details to identify the cancellation costs

Cancellation costs are returned as a list of objects containing a date and an amount.

The following example shows a cancellation cost with a single entry for an availability between 29 and 20 March 2016 and a product price 58 eur:

"cancellationPolicies": [ { "dateFrom": "2016-03-28T00:00:00.000Z", "amount": 58 } ]

That means if the booking is cancelled starting from 28 March and after, then 100% (58 eur) are charged and no cancellation fees are applied if the booking is cancelled before.

The following one, for an availability between 1 and 31 March 2016 and a price of 58 eur, has different time frames with different cancellation costs:

"cancellationPolicies": [

{

"dateFrom": "2016-03-15T00:00:00.000Z",

"amount": 20

},

{

"dateFrom": "2016-03-22T00:00:00.000Z",

"amount": 35

},

{

"dateFrom": "2016-03-28T00:00:00.000Z",

"amount": 58

}

]

The time frames shown implies that:

If the booking is cancelled before 15 March, no cancellation fees are charged.
If the booking is cancelled between 15 (included) and 22 (excluded) March,then 20 euros are charged.
If the booking is cancelled between 22 (included) and 28 (excluded) March, then 35 euros are charged.
If the booking is cancelled starting from 28 March, then 58 euros are charged.

Documentation

Dashboard Menu

From a business perspective, the response returned by the API contains:

Specific details to identify the cancellation costs