Search Request

The search API call returns available activities. These activities will return a price from. In case of any filters applied (see filters section) the results will be according to the filters selected.

Each website or mobile app requires different booking funnels to adapt to customers’ needs. This is the reason why the APITUDE for activities have different filters that can be combined to obtain the specific results required.

Specifications

Live URL: https://api.hotelbeds.com/activity-api/3.0/activities

Test URL: https://api.test.hotelbeds.com/activity-api/3.0/activities

Method: POST

Request

There are different alternatives on how to structure the search request call. Every single response will contain the same structure but it will have more or less information being returned depending on the filters that are applied.

The following table contains the specifications for the Search call:

Search Request

 

NAME

DESCRIPTION

Mandatory / Optional

filters

The available filters for the search are listed below.

It contains an array of filter/s with the following structure:

[{"searchFilterItems": [{"type": "destination", "value": "BCN"}]}]

The Object “searchFilterItems” contains the following attributes: type and value.

The following examples illustrate the different types and values for each filter:

Country

{"type": "country", "value": "PT"}

 

Destination Code

{"type": "destination", "value": "MCO"}

 

Factsheet ID

{"type": "factsheet", "value": "33880"}

 

Service Code

{"type": "service", "value": "E-E10-DINNERCRUI"}

 

Hotel Code – Hotelbeds code (take into consideration that the list of hotels available is not the one from the Hotel BookingAPI but directly from the Activities BookingAPI. For Activities there are more hotels available to be used).

{"type": "hotel", "value": "8011"}

 

Hotel Code – Standard GIATA code

{"type": "giata", "value": "29744"}

 

Hotel Code – Standard TTI code

{"type": "tti", "value": "22293826"}

 

Destination and Segment value

{"type": "destination", "value": "MCO"}, {"type": "segment", "value": "3"}

 

Service and Modality

{"type": "service_modality", "value": "E-U10-DINNERCRUI@@#@@7PMDINNER"}

 

Range of prices

{"type": "priceFrom", "value": "50"}
{"type": "priceTo", "value": "60"}

 

GPS coordinates or geolocation

{"type": "gps", "latitude": 41.49004, "longitude":2.08161}

 

Keywords - IMPORTANT: When using Keywords it is mandatory to include also a Destination Code, or a Hotel Code or a GPS coordinates at the same time

{"type" : "text", "value" : "beach"}

 

Can filters be combined?

The filters can be combined meaning that more than one filter can be implemented at the same time. An example is below:

"filters": [
  // all the following filters are applied with a "AND" condition:
  {"searchFilterItems": [{ "type": "country", "value": "ES" },
  {"type": "destination", "value": "BCN" },
  {"type": "service", "value": "E-E10-EXPER"}        
]},
// The following is going to be applied also with an "OR" condition to the previous  filter
  {"searchFilterItems": [{ "type": "segment", "value": "102" }]},

In other words the previous filter will mean that the search will be done for:

 - (Country ES – Spain AND Destination BCN – Barcelona AND Service is E-E10-EXPER) OR (Segment 102)

More examples and explanation can be found below.

 

At least the implementation of one filter is mandatory.

 

from

Return activities available from the specified date indicated (date format must be: YYYY-MM-DD)

Mandatory

to

Return activities available up to the specified date (date format must be: YYYY-MM-DD)

Mandatory

language

Language code in which multi-language texts will be returned in the response of the API. (see here for static list of language codes or use the Contents API to retrieve them).

If no language is provided, the results will be returned in the language previously used to authenticate credentials (see authentication procedure).

Optional

pagination

The results returned can be divided in pages. If provided, the “pagination” attribute can specify the number of pages and the number of items per page.

See an example:

"pagination": {"itemsPerPage": 10, "page": 1}

Optional

order

If not specified, the “DEFAULT” order will be used.

A specific order can be requested. The following are the different “order” available values:

  • PRICE (“order”: “PRICE”). Results are ordered from lowest to highest
  • NAME (“order”: “NAME”). Results are ordered alphabetically by activity name.
  • DEFAULT (“order”: “DEFAULT”). Results are ordered according to APITUDE recommendation engine rules.

 

Optional

Docs Navigation