Search Filters

In the next sections we will show different search options and examples when using different filters.

Search by Destination Code

The following JSON message represents a Search Request message example where the results are filtered by destination code, meaning that only results for that particular destination will be returned:

{
    "filters": [{
        "searchFilterItems": [{"type": "destination", "value": "BCN"}]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

The exampled search will return all activities available between 29 March 2016 and 31 March 2016 in Barcelona Destination.

The exact meaning of each attribute can be found here. A list of available destinations can be retrieved either by the calls included in the Contents API or from the downloadable static contents located in the Active Content (for more information on the Active Content please contact us on integrations@activitiesbank.com)

Search by Hotel Code

The following JSON message represents a Search Request message example where the results are filtered by Hotelbeds hotel code:

{
    "filters": [{
        "searchFilterItems": [{"type": "hotel", "value": "1524"}]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

The exampled search will return all the activities between 29 March 2016 and 31 March 2016. If the activity is a ticket, it will return all the tickets in the same destination as the one linked to the hotel code 1524. If it is an excursion it return all the excursions where the hotel 1524 is configured as a valid pickup point.

The exact meaning of each attribute can be found here. A list of available destinations can be retrieved either by the calls included in the Contents API or from the downloadable static contents located in the Active Content (for more information on the Active Content please contact us on integrations@activitiesbank.com)

Other hotel codes such as TTI or GIATA can also be used. The sample request above would appear as the following:

{
    "filters": [{
        "searchFilterItems": [{"type": "tti", "value": "1234556789"}]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}
{
    "filters": [{
        "searchFilterItems": [{"type": "giata", "value": "65488422"}]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

Search by GPS

The following JSON message represents a Search Request message example where the results are filtered by a particular GPS coordinates or geolocation:

{
    "filters": [{
        "searchFilterItems": {"type": "gps",
                              "latitude": 41.49004,
                              "longitude":2.08161}]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

The exampled search will return all the activities between 29 March 2016 and 31 March 2016. There will be a particularity in regards to whether the activity is a ticket or an excursion.

  • For tickets the product being returned are all tickets linked to the destination that embeds the GPS coordinates or geolocation.  
  • For Excursions the product being return are all the excursions for the hotel that is the closest to the GPS coordinates or geolocation provided in the request.

The exact meaning of each attribute can be found here. A list of available destinations can be retrieved either by the calls included in the Contents API or from the downloadable static contents located in the Active Content (for more information on the Active Content please contact us on integrations@activitiesbank.com)

Search by factsheet code

A Contents Factsheet is the set of attributes that provide all relevant information that describe an Activity. A content factsheet could define the contents for one or more than one service. 

A JSON message example is provided below:

{
    "filters": [{
        "searchFilterItems": {"type": "factsheet", "value": "15877"}]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

The search call will provide only those services included in the content factsheet id 15877 and considering that dates are between 29 March 2016 and 31 March 2016.

The exact meaning of each attribute can be found here. A list of available destinations can be retrieved either by the calls included in the Contents API or from the downloadable static contents located in the Active Content (for more information on the Active Content please contact us on integrations@activitiesbank.com)

Search by segmentation

Segmentation is composed by a group of attributes that categorize the activity. A segment or group of segments are included as attributes in the content factsheet. In regard to the use of segmentation it is important to understand that it CAN NOT be used by itself. It is mandatory to provide one of the following additional filters:

  • Destination
  • GPS coordinates

The reason for it is that if only segmentation is provided the number of resutls could be too high as it will provide product from all around the world that match that segmentation.  An example is shown below where it is included the Destination and the Segmentation code being searched for:

 

An example of the JSON message is detailed below:

{
    "filters": [{
        "searchFilterItems": [
                              {"type": "segment", "value": "88559"},
                              {"type": "destination", "value": "BCN"}
         ]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

The example is looking for all products/services whose content factsheet contains the segment 88559 and that dates are between 29 March 2016 and 31 March 2016. 

Segments available can be obtained from the offline contents FTP or by calling to the Cotents API “Segments” operation.

The exact meaning of each attribute can be found here. A list of available destinations can be retrieved either by the calls included in the Contents API or from the downloadable static contents located in the Active Content (for more information on the Active Content please contact us on integrations@activitiesbank.com)

Search with a price range

The Search API call has also the ability to filter results by a range of prices. The following is an example applying price from and to for a given destination:

{
    "filters": [{
        "searchFilterItems": [
                              {"type": "destination", "value": "BCN"},
                              {"type": "priceFrom", "value": "10"},
                              {"type": "priceTo", "value": "50"}
        ]
    }],
    "from": "2016-03-29",
    "to": "2016-03-31"
}

The example above uses a combined filter. The product that will be provided in the Search response will be only the product from Barcelona (BCN) destination where the price is between 10 and 50. The currency of the price is the same as the one configured for the client. The priceRange has to have always either a Destination Code or a GPS coordinate or a hotel code (Hotelbeds, Giata, or TTI are all accepted). 

Search with keywords

The Search API call has also the ability to filter results using keywords. When using the keywords and as detailed before it can only be done if the keyword is accompanied by either a DestinationCode, a HotelCode, or a GPS coordinates. The following is an example:

 

 

{
  "language" : "en",
  "pagination" : {
    "itemsPerPage" : 30,
    "page" : 1
  },
  "filters" : [
    {
      "searchFilterItems" : [
        {"type" : "gps", "longitude" : "2.6416219","latitude" : "39.6392898"},
        {"type" : "text","value" : "beach"}
      ]
    }
  ],
  "to" : "2016-05-15",
  "order" : "DEFAULT",
  "from" : "2016-05-08"
} 

The example above uses a combined filter. The product that will be provided in the Search response will be only the product based on the GeoCoordinates (longitude and latitude) as well as considering the filter of keywords ("text"). 

 

Filters combination and constraints

As explained above, the filters can be combined to generate “AND” and “OR” conditions. A few considerations have to be present before we implement combinations. These considerations are: 

  • At least one filter must be defined
  • Dates (from and to) are always mandatory
  • Hotel codes can be combined in the same filter. That means, Hotelbeds hotel codes can be combined with Hotelbeds codes, GIATA codes with GIATA codes and TTI codes with TTI codes, but they cannot be mixed when searching for multiple hotels.
  • GPS cannot be combined with Hotel Code and Destination Code.
  • Keywords, segment code and pricerange are also available but can only be use when combined with a destination code, Hotel Code or GPS. 
  • Segment Codes can be combined with a Destination code, Hotel Code or GPS. However, 2 or more values for "Segment codes" filter is not allowed.

Now that we understand the considerations let's see an example of and AND:

{   
  "filters": [        
	{
            "searchFilterItems": [
                {"type": "destination", "value": "MCO"},
                {"type": "text", "value": "night"},
                {"type": "text", "value": "day"}
             ]
        }
  ],
  "from": "2016-07-29",  
  "to": "2016-07-29",  
  "language": "en",  
  "pagination": {
    "itemsPerPage": 10,
    "page": 1  },
  "order": "DEFAULT"
}

In this example the keywords "night" and "day" are linked with an AND.

However, if we wanted to do "night" OR "day" it shall be done using the following example:

{  "filters": [
        {
            "searchFilterItems": [
                {"type": "destination", "value": "MCO"},
                {"type": "text", "value": "night"}
            ]
        },
        {
            "searchFilterItems": [
                {"type": "destination", "value": "MCO"},
                {"type": "text", "value": "day"}
            ]
        }
  ],
  "from": "2016-07-29",
  "to": "2016-07-29",
  "language": "en",
  "pagination": {
    "itemsPerPage": 10,
    "page": 1  },
  "order": "DEFAULT"
}

The difference here is that you create two searchFilterItems in order to create the OR conditional.

IMPORTANT: you have to duplicate the destination line, as what you are actyually looking to do is: (Destination MCO and "night) OR (Destination MCO and "day").

 

In the event of having trouble with a filter definition, please, contact to the support team at integrations@activitiesbank.com.

Docs Navigation