Search widget

Get Started

Getting started

Search widget

Search Widget API Functional Specification

min read

Overview

This document describes the APIs that are available to integrate with TRAVLR product search to create custom search modules on the partner site. At the time of writing there are 4 types of products available on the TRAVLR platform; Accommodation, Deals, Activities and Flights.

Search API

To create a unified search result linking interface for the platform, TRAVLR exposes endpoints for each product type as follows:

The basic flow for all search widget use cases is:

Customer interacts with search widget
Partner calls any TRAVLR API suggest or GET endpoints to retrieve typeahead suggestions or select list items
Partner builds /searchResource query and POST to endpoint
Completes inputs and clicks Search
TRAVLR API responds with resource response Redirect customer to resource url

Accommodation

Components

The Accommodation search widget is composed of:

Destination/Property search input
Check In-Check Out Date input
Rooms/Occupancy input

Rules

Max adults per room is 8
Minimum 1 Adult per room
Max children per room is 8
Max rooms is 8
Check in date must be prior to check out date
Check in date must be no earlier than today
Max stay duration 28 days (i.e. from checkin to checkout max 28 days inclusive)

Destination/Property Suggestions

To retrieve Destination or Property suggestions for a keyword make a GET request to the /api/accommodation/suggest endpoint on the TRAVLR API.

Example:

https://api.travlr.com/travlrblack-prod/accommodation/suggest?q=Queenstown

Will return Destinations and Properties that match the keyword Queenstown. The response will be an object with a suggestions JSON array with 0-20 objects of either type destination or type accommodation, in the format:

{
   "suggestions": [
       {
           "level": "city",
           "name": "Queenstown, New Zealand",
           "fullName": "Queenstown, New Zealand",
           "location": "global",
           "id": "queenstown-4189",
           "highlight": null,
           "type": "destination",
           "isPossibleDestination": false
}, {
} ],
"id": 69476,
"name": "Sofitel Queenstown Hotel and Spa, Otago, New Zealand",
"fullName": "Sofitel Queenstown Hotel and Spa, Otago, New Zealand",
"city": "Queenstown",
"type": "accommodation",
"expediaId": 1246483,
"agodaId": 69476,
"propertyLinkageId": 122825
 ... }

Note: When a user selects a suggestion object from the search form input, the object should be passed through unchanged to the query parameter of the searchResource request to make a query for the selected destination or property.

Search

A search resource URL is created by performing a POST request to the /api/accommodation/searchResource endpoint.

The response will be a Search response payload. A successful search response will have a 200 http status code and a JSON body containing a URL to redirect the user to their search results.

Request

Request Model
{
   "keyword": "string | destination suggestion | accommodation suggestion",
   "rooms": [
"occupancy"
   ],
   "checkInDate": "yyyy-mm-dd",
   "checkOutDate": "yyyy-mm-dd",
   "currency": "string"
}
Occupancy Model
[
"guest"
]
Guest Model
{
   "ageQualifyingCode": "integer", // 10 - Adult, 8 - Child
"age": "integer", // 0 - Infant, 1-17 - Child, 18+ - Adult
   "count": "positiveInteger"
}

Response

200

Accommodation Search Response Model
{
   "id": "string",
   "resource": {
       "url": "string"
   }
}

400

Search Response Error Model
{
   "errorCode": "string",
   "message": "string",
   "detail": [
"string"
] }

Examples:

Search Queenstown accommodation check in today 1 room for 2 adults
POST /api/accommodation/searchResource
{
   "keyword": {
       "level": "city",
       "name": "Queenstown, New Zealand",
       "fullName": "Queenstown, New Zealand",
       "location": "global",
"id": "queenstown-4189",
       "highlight": null,
       "type": "destination",
       "isPossibleDestination": false
} }
Response {
   "id": "fb34cae2-6c1b-4135-85a4-a13844643d7d",
   "resource": {
       "url":
"https://travlrblack.com/accommodation/search?Dest=Queenstown&DestFullName=Queenstown%
2C%20New%20Zealand&GeoAreaId=queenstown-4189"
} }

Note: if no dates are supplied then the default check in is today for 1 night stay. If no guest parameters are supplied then the default is 2 adults and 1 room. The currency will default to the Platform currency (AUD).

Search Queenstown accommodation check in june 2 rooms 1 with 3 adults, another with 2
adults, 1 child, 1 infant
Request
POST /api/accommodation/searchResource
{
   "keyword": {
       "level": "city",
       "name": "Queenstown, New Zealand",
       "fullName": "Queenstown, New Zealand",
       "location": "global",
       "id": "queenstown-4189",
       "highlight": null,
       "type": "destination",
       "isPossibleDestination": false
   },
   "checkInDate": "2021-06-14",
   "checkOutDate": "2021-06-18",
   "rooms": [
[
           { "ageQualifyingCode": 10, "age": 18, "count": 3 }
], [
] ]
}
Response {
   "id": "fb34cae2-6c1b-4135-85a4-a13844643d7d",
   "resource": {
       "url":
"https://travlrblack.com/accommodation/search?Dest=Queenstown&DestFullName=Queenstown%
2C%20New%20Zealand&CheckIn=2021-06-14&CheckOut=2021-06-18&CurrencyCode=NZD&GuestCounts
[0][0][AgeQualifyingCode]=10&GuestCounts[0][0][Count]=3&GuestCounts[0][1][AgeQualifyin
gCode]=8&GuestCounts[0][1][Count]=1&GuestCounts[0][1][Age]=10&GuestCounts[1][0][AgeQua
lifyingCode]=10&GuestCounts[1][0][Count]=1&GuestCounts[1][1][AgeQualifyingCode]=8&Gues
tCounts[1][1][Count]=1&GuestCounts[1][1][Age]=17&GeoAreaId=queenstown-4189"
} }

Will create a search for Queenstown accommodation for check in on June 14th 2021 and checkout on 18th June 2021

Room and Occupancy Parameters

The rooms parameter specifies both the number of rooms and the occupancy using a multidimensional array.

The first dimension in the array specified the rooms using a zero based index. I.e. if the first dimension index is 0, this refers to the occupancy for the first room. If additional rooms are required then the first dimension index will be 1 for the second room, 2 for the third room and so on.

There are 3 different age groups for accommodation:

When querying with different occupant types the age parameter must be set for each occupant to ensure matching rooms are returned.

Property Search

If the user selects an accommodation type from the suggestion list then a property search can be triggered by querying with the selected accommodation suggestion:

Search Sofitel Queenstown accommodation check in today, 1 room for 2 adults
POST /api/accommodation/searchResource
{
   "keyword": {
       "id": 69476,
       "name": "Sofitel Queenstown Hotel and Spa, Otago, New Zealand",
       "fullName": "Sofitel Queenstown Hotel and Spa, Otago, New Zealand",
       "city": "Queenstown",
       "type": "accommodation",
       "expediaId": 1246483,
       "agodaId": 69476,
       "propertyLinkageId": 122825
}, "rooms": [
       [
           { "ageQualifyingCode": 10, "age": 18, "count": 2 }
] ]
}
Response {
   "id": "fb34cae2-6c1b-4135-85a4-a13844643d7d",
   "resource": {
"url":
"https://travlrblack.com/accommodation/search?PropertyName=Sofitel%20Queenstown%20Hote
l%20and%20Spa%2C%20Otago%2C%20New%20Zealand&AgodaId=69476&ExpediaId=1246483"
} }

Keyword Search

Keyword search is also supported if the query is a string (i.e. destination or accommodation suggestion is not populated in the query). So to search for all ‘sofitel’ hotels we can provide a string keyword in the PropertyName parameter like so:

POST /api/accommodation/searchResource
{
   "keyword": "sofitel",
   "rooms": [
       [
           { "ageQualifyingCode": 10, "age": 18, "count": 2 }
] ]
}
Response {
   "id": "fb34cae2-6c1b-4135-85a4-a13844643d7d",
   "resource": {
       "url":
"https://travlrblack.com/accommodation/search?PropertyName=sofitel&GeoAreaId=global"
} }

Deals

Components

The deals search widget is composed of:

Text input
Destination select list
Search Button

Destinations

The /api/deals/destinations endpoint returns a list of destinations from the platform where there are available deals.

The destinations returned from this api should be used as the values for the Destination select list.

Request
GET /api/deals/destinations

200

Response Model
{
   "destinations": [
       "destination"
] }
Destination Model
{
   "id": "positiveInteger",
   "name": "string"
}

400

Search Response Error Model
{
   "errorCode": "string",
   "message": "string",
   "detail": [
"string"
] }

Example:

GET /api/deals/destinations
{
   "destinations": [
       {
"id":87,
           "name":"New Zealand"
       },
{
"id":92,
           "name":"Australia"
       },
{
"id":244,
           "name":"Queensland"
       }
] }

Search

A search resource URL is created by performing a POST request to the /api/deals/searchResource endpoint.

The response will be a Search response payload. A successful search response will have a 200 http status code and a JSON body containing a URL to redirect the user to their search results.

POST /api/deals/searchResource
Request Model
{
   "keyword": "string",
   "destination": "destination suggestion"
}

200

{
   "id": "string",
   "resource": {
       "url": "string"
   }
}

400

{
   "errorCode": "string",
   "message": "string",
   "detail": [
"string"
] }

Example:

Search for wine deals in New Zealand
POST /api/deals/searchResource
{
   "keyword": "wine",
   "destination": {
"id":87,
       "name":"New Zealand"
   }
}
Response
{
   "id": "fb34cae2-6c1b-4135-85a4-a13844643d7d",
   "resource": {
       "url":
"https://travlrblack.com/deals-and-offers/search?keyword=wine&destination=New%20Zealan
d"
} }

Activities

Components

The activities search widget is composed of the following components:

Destination/Activity suggestion input
Search Button

Suggest

A list of suggested destinations, activity categories and activities and be retrieved from the suggest endpoint using a GET request.

GET /api/activities/suggest?q={keyword}

200

{
   "destinations": [
"string"
   ],
   "categories": [
"string"
   ],
   "listing": [
"listing"
] }
Listing Model
{
   "text": "string",
   "url": "string"
}

400

{
   "errorCode": "string",
   "message": "string",
   "detail": [
"string"
] }

Examples:

GET /api/activities/suggest?q=outdoor
{
   "destinations": [],
   "categories": [
       { "name": "Outdoor Activities", "type": "category" }
     ],
   "listings": [
       {
           "text": "Outdoors In Seoul",
           "url": "/activities/outdoors-in-seoul-1759076",
           "type": "listing"
}, {
}, {
           "url":
"/activities/outdoors-experience-paintball-in-transylvania-100081477",
           "type": "listing"
       },
... ]
}
GET /api/activities/suggest?q=queenstown
{
   "destinations": [
       { "name": "Queenstown, New Zealand", "type": "destination" },
       { "name": "Queenstown City Centre, Queenstown, New Zealand", "type":
"destination" },
       { "name": "Queenstown, Tasmania, Australia", "type": "destination" },
       { "name": "Queenstown, South Australia, Australia", "type": "destination" },
       { "name": "Queenstown, Maryland, United States of America", "type":
"destination" },
       { "name": "Fernhill, Queenstown, New Zealand", "type": "destination" }
   ],
   "categories": [],
   "listings": [
       {
           "text": "Queenstown Discovery",
           "url": "/activities/queenstown-discovery-40432",
           "type": "listing"
"text": "The Outdoors Adventure",
"url": "/activities/the-outdoors-adventure-100116889",
"type": "listing"
"text": "Outdoors experience - Paintball in Transylvania",

}, {
           "url":
"/activities/vine-hopper-queenstowns-ultimate-wine--microbrewery-adventure-1852520",
           "type": "listing"
       },
       {
           "text": "Queenstown ATV Tour",
           "url": "/activities/queenstown-atv-tour-43589",
           "type": "listing"
},
... ]
}

Search

A search resource URL is created by performing a POST request to the /api/activities/searchResource endpoint.

The response will be a Search response payload. A successful search response will have a 200 http status code and a JSON body containing a URL to redirect the user to their search results.

A user can perform a search by keyword (string), category (by passing a category suggestion) or destination (by passing a destination suggestion)

Note: If the user selects a Listing suggestion it is best to simply redirect the user to the url from the listing suggestion rather than creating a new searchResource.

POST /api/activities/searchResource
{
   "query": "string | category | destination | listing",
}
Category Model
{
   "name": "string",
"type": "category"
}
Destination Model
{
   "name": "string",
   "type": "destination"
}

200

{
   "id": "string",
   "resource": {
       "url": "string"
   }
}

400

{
   "errorCode": "string",
   "message": "string",
   "detail": [
"string"
] }

Examples:

All activities in Queenstown
POST /api/activities/searchResource
{
   "query": {
       "name": "Queenstown, New Zealand",
       "type": "destination"
} }
Response {
   "id": "",
   "resource": {
       "url":
"https://travlrblack.com/activities/search?q=queenstown%2c%20new%20zealand&qtype=desti
nation"
} }

Skiing in queenstown
POST /api/activities/searchResource
{
   "query": "skiing queenstown",
}
Response {
   "id": "fb34cae2-6c1b-4135-85a4-a13844643d7d",
   "resource": {
       "url": "https://travlrblack.com/activities/search?q=skiing%20queenstown"
   }
}

Flights

Components

The flights search widget is composed of:

Journey type radio input
1. Return
2. One Way
From Airport search input
From-To Airport switch button
To Airport search input
Date Selector
1. Single date when One Way Journey Type is selected
2. Departure date and Return date when Return Journey Type is selected
Passenger and Class Selection
1. Classes available are First Class, Business, Premium Economy and Economy
2. Number of Infants (<2 years old)
3. Number of Children (2 to 18)
4. Number of Adults
Search Button

Rules

Departure date is the same or prior to return date (when in Return Journey mode)
Departure date is no earlier than today
Max total passengers is 6
Max infants must be less than or equal to the number of adults

Suggest

The Airport Search component contains a simple typeahead suggestion input of all global IATA Airports and Cities containing multiple airports for the departure and arrival.

A list of suggested airports can be retrieved from the suggest endpoint using a GET request.

The selected suggestion result should be passed through unchanged in the searchResource request.

GET /api/flights/suggest?q={keyword}

200

Flight Suggestion Response Model
{
   "suggestions": [
       "airport"
] }
Airport Model
{
   "airportCode": "string",
   "airportName": "string",
   "cityCode": "string", // can be used to group multiple airports under the city code
   "cityName": "string",
   "code": "string",
   "countryCode": "string",
   "countryName": "string",
   "fakeName": "string (deprecated)",
   "name": "string",
   "type": "airport | city",
   "priority": "int",
   "objectId": "string"
}

400

{
   "errorCode": "string",
   "message": "string",
   "detail": [
"string"
] }

Example:

GET /api/flights/suggest?q=syd
Response {
   "suggestions": [
       {
           "airportCode": "SYD",
           "airportName": "Kingsford Smith",
           "cityCode": "SYD",
           "cityName": "Sydney",
           "code": "SYD",
           "countryCode": "AU",
           "countryName": "Australia",
           "fakeName": "IATASEARCH_Sydney, AU - Kingsford Smith",
           "name": "Sydney, AU - Kingsford Smith",
           "type": "airport",
           "priority": 10,
           "objectId": "1481265510"
}, {
},
...
] }

Search

A search is created by GET request to the /flights/searchResource endpoint of the booking platform.

Request
POST /api/flights/searchResource
{
   "journeyType": "OneWay | Return",
   "departureAirport": "airport suggestion", // Full object from Suggest call
   "arrivalAirport": "airport suggestion", // Full object from Suggest call
   "departureDate": "yyyy-mm-dd",
   "returnDate": "yyyy-mm-dd", // Conditionally required based on journeyType
   "cabinClass": "First | Business | PremiumEconomy | Economy",
   "passengers": {
       "adult": "positiveInteger",
       "child": "positiveInteger",
       "infant": "positiveInteger"
} }

Response

200

Flight Search Response Model
{
   "id": "string",
   "resource": {
       "url": "string"
   }
}

400

Search Response Error Model
{
   "errorCode": "string",
"message": "string",
   "detail": [
"string"
] }

Example:

Melbourne to Sydney return
POST /api/flights/searchResource
{
    "journeyType": "Return",
    "departureAirport": {
            "airportCode": "MEL",
            "airportName": "Tullamarine",
            "cityCode": "MEL",
            "cityName": "Melbourne",
            "code": "MEL",
            "countryCode": "AU",
            "countryName": "Australia",
            "fakeName": "IATASEARCH_Melbourne, AU - Tullamarine",
            "name": "Melbourne, AU - Tullamarine",
            "type": "airport",
            "priority": 10,
            "objectId": "1481215140"
        },
    "arrivalAirport": {
            "airportCode": "SYD",
            "airportName": "Kingsford Smith",
            "cityCode": "SYD",
            "cityName": "Sydney",
            "code": "SYD",
            "countryCode": "AU",
            "countryName": "Australia",
            "fakeName": "IATASEARCH_Sydney, AU - Kingsford Smith",
            "name": "Sydney, AU - Kingsford Smith",
            "type": "airport",
            "priority": 10,
            "objectId": "1481265510"
},
    "departureDate": "2022-02-22",
    "returnDate": "2022-02-25",
    "cabinClass": "Economy",
    "passengers": {
        "adult": "2",
        "child": "0",
        "infant": "0"
} }
Response
{
    "id": "fb91ea54-4222-4f0c-8708-5251b6b87779",
    "resource": {
        "url":
"https://travlrblack.com/flights/search?journeyType=Return&origin=MEL&originType=Airpo
rt&destination=SYD&destinationType=Airport&departureDate=2022-02-22&returnDate=2022-02
-25&cabinClass=Economy&adult=2&child=0&infant=0"
} }

Note: Full documentation of flights deeplinking is provided here.

Custom Product

Product widget

TRAVLR Updates

Sign up for our TRAVLR Updates mailing list where you get first access to all our new releases, functionality optimizations, or BETA trials. Don't miss out on being at the forefront of the industry!

TRAVLR Updates

Sign up for our TRAVLR Updates mailing list where you get first access to all our new releases, functionality optimizations, or BETA trials. Don't miss out on being at the forefront of the industry!

TRAVLR Updates

Sign up for our TRAVLR Updates mailing list where you get first access to all our new releases, functionality optimizations, or BETA trials. Don't miss out on being at the forefront of the industry!

TRAVLR

Terms

TRAVLR

Terms

TRAVLR

Terms