Rapid Typeahead v2 - External Integration guide - BETA

Description

This article provides an overview of the new Typeahead API on Rapid while in the BETA phase. This API endpoint is in an beta phase, meaning the schema is subject to change before the feature’s full public launch. You have access this page as you have been approved as a beta partner for Typeahead API. 

How Typeahead API works

Typehead(GET /suggestions) is a new API endpoint that enables you to offer their travelers a suggestive search experience based on geographic regions, relevant locations and properties.

This endpoint returns a list of suggestions based on partial search strings as a user may input into a text field. The types of suggestions returned are controlled by the request parameters.

Sometimes known as an autocomplete or autosuggest, Typeahead API is a language prediction tool that returns a list of regions, locations or properties based on the input of partial information typed into a search box. After a minimum of 3 letters are typed into a search box, Typeahead API will begin returning up to 10 results using city, region, property, or postal code information. The traveler can then select from this list to initiate their search or keep typing to continue to refine the automatically suggested results. For example, a search that starts with “Memp” would see several geographic options, including neighborhoods, train stations, airports, etc. related to “Memphis, Tennessee, US followed by Memphis, Missouri, US. 

Launch Guide 

How to integrate Typeahead API 

• Contact your Account Manager or Partner Connect representative to request access to Typeahead.
• Confirm you are happy with the limitations of the beta product (see below).
• Internal approval will need to be granted.
• If approval is given, an amendment to the agreement is required to include Typeahead terms.
• Partner Connect will enable Typeahead on your credentials and will create an integration ticket to support you with development.

Limitations of the offering

• You must adopt and use the opaque access token process.
• Access tokens can only be used by the same CID/API key that requested. 
• Access tokens can only exist for 25 minutes.  
• Requests for new access tokens should be built to consistently refresh on that schedule and not too frequently update.  
• Language and the text of the request are required parameters. 
• Languages supported:

Technical details for integration

The Typeahead API endpoint 

Rapid’s Typeahead API is available to request on the API endpoints by partners currently on Rapid version 3. Once approved, your existing profile will have the permissions required to successfully use the API.  

Below is a copy of the latest API schema, which includes the Beta Typeahead API. To view the swagger documentation, copy and paste the YAML file into the swagger Editor: https://editor.swagger.io/ 

YAML file: (Please download from the attached file.)

Dev hub: https://test.developers.expediagroup.com/docs.pr1254/products/rapid/lodging/geography#get-/suggestions

Authorization: 

Authentication for the Typeahead API differs from our other Rapid API features. An access key is used to allow requests from the client's server or browser side. 

Using an authorization header, you will provide your apikey to call the EPS Gateway to obtain an access key. Then, you can call the Typeahead API endpoint by passing the access key as the authorization header. 

Base64 encoding

Encode API Key in base64 format

Get an opaque access token

Sample Request:

POST – https://api.ean.com/identity/oauth2/v3/token 

Header: 
Key: 'Authorization' 
Value: 'Basic {base64}' 

Sample Response:  

{ 

    "access_token": "p1xy6rxahicQPUIX_Sq6a52yFnHXpX3ImaSX9sKiUI4:XM8qZiTr1HPDc8FgBE5HLvFTFdICuRFV0-l7gFWI-WU", 
    "token_type": "bearer", 
    "expires_in": 1800, 
    "scope": "demand-solutions.demand-api-wrappers-playground.all" 

} 

Making an autocomplete request 

Parameters 

Request Headers:

- The required `Accept` parameter specifies the response format that the client would like to receive back. This must be `application/json`. Eg. `application/json` 

- The required `AcceptEncoding` parameter specifies the response encoding that the client would like to receive back. This must be `gzip`. Eg. `gzip` 

- The required `User-Agent` parameter is a header string from the customer's request, as captured by your integration. If you are building an application, then the `User-Agent` value should be `{app name}/{app version}`. Eg. `TravelNow/3.30.112`  

Query Parameters:

- The required `language` parameter specifies the desired language for the response as a subset of BCP47 format that only uses hyphenated pairs of two-digit language and country codes. Use only ISO639-1 alpha 2 language codes and ISO3166-1 alpha 2 country codes. See [here](https://www.w3.org/International/articles/language-tags/). Eg. language=en-US 

- The required `text` parameter is the input string to query for. Eg. text=Springfie 

- The required `feature` parameter is the feature that change the calculation of the suggestion results. 

• hierarchy
• nearby_airport 
• postal_code

- The `type` parameter is optional and is the geographic region entity type which describes the place the user is looking for. This parameter can be supplied multiple times with different values. If this parameter is not provided the default will include all types. Eg. region_type=AIRPORT&region_type=CITY 

Possible values:  

• airport 
• city 
• multi_city_vicinity 
• neighborhood 
• point_of_interest 
• airport_metro_code 
• multi_region 
• train_station 
• metro_station 
• address (Added in version 2)
• property (Added in version 2)
• bus_station (Added in version 2)

- The `line_of_business` parameter is optional Parameter exists for search_environment. It provides search heuristics and geographic restrictions are lifted for flight searches.  It is recommended that Rapid partners omit this parameter unless otherwise directed by your account manager.  

• Properties
• flights
• packages
• car 
• activities

- The `region_id` parameter is optional parameter for filtering the results to properties with the specified region.

- The `origin` parameter is optional parameter and is specifies whether the query text is an origin instead of a destination.

- The `package_type` parameter is optional parameter and is for package types that accompany the packages line of business.

• flight_property
• flight_property_car
• flight_car 
• property_car

- The `limit` parameter is optional and specifies the maximum number of matched predictions returned by the response. This value must be between 1 and 10. If this parameter is not provided the default will be 10. Eg. limit=5 

Once you have the access_token to make a typeahead request 

Sample Response: 

GET - https://api.ean.com/v3/suggestions?max_results=5&language=en-US&text=vaslui 

Header : 
Authorization: Bearer {{access_token}} 

Sample Response: 

[ 
  { 
    "region_id": 602962, 
    "region_type": "city", 
    "name": "Springfield", 
    "name_full": "Springfield, Missouri, United States of America", 
    "coordinates": { 
      "center_latitude": 37.207138, 
      "center_longitude": -93.292328 
    }, 
    "country_code": "US", 
    "country_code_3": "USA", 
    "airport_code": "SGF" 
  }, 
  { 
    "region_id": 9777, 
    "region_type": "city", 
    "name": "Springdale", 
    "name_full": "Springdale, Utah, United States of America", 
    "coordinates": { 
      "center_latitude": 37.18887, 
      "center_longitude": -112.99855 
    }, 
    "country_code": "US", 
    "country_code_3": "USA", 
    "airport_code": "SGU" 
  }, 
  { 
    "region_id": 3249, 
    "region_type": "city", 
    "name": "Springfield", 
    "name_full": "Springfield, Illinois, United States of America", 
    "coordinates": { 
      "center_latitude": 39.79937, 
      "center_longitude": -89.649406 
    }, 
    "country_code": "US", 
    "country_code_3": "USA", 
    "airport_code": "SPI" 
  }, 
  { 
    "region_id": 6047669, 
    "region_type": "CITY", 
    "name": "Springfield", 
    "name_full": "Springfield, Massachusetts, United States of America", 
    "coordinates": { 
      "center_latitude": 42.1017, 
      "center_longitude": -72.588608 
    }, 
    "country_code": "US", 
    "country_code_3": "USA", 
    "airport_code": "BOS", 
    "metro_code": "BOS" 
  } 
] 

How Typeahead API interacts with other Rapid features

How to use Typeahead API:

1. When end user type in the search, the Typeahead API is called based on the information to obtain the Region information (Region ID, name, coordinates, etc..) or Property information depends on type.

2. The acquired region information and property information are displayed as results in the auto-completion section.

3. If the user selects one region from the auto-complete list, the Region API is called to obtain a property list around that region

4. Call Shop API with the property ids returned from Region API to get availability and display the properties in the list page.

5. If the user selects one property from the auto-complete list, the Shop API is called to get availability and display the property contents in the detail page. 

6. When display the property, you can use score returned from Shop API.

What it means to integrate the Beta Typeahead API

By adopting Typeahead API while it is in an beta phase, you are getting beta to test Expedia Group’s latest technology. You will be able to give feedback on Typeahead API that will help us finalize the feature before we make it available to all partners.  

Given the information above, the Typeahead API’s beta schema is subject to change based on feedback from our beta users. 

Your responsibilities as an beta partner

If you choose to participate in an beta phase, you will be one of just a few partners to access this feature before it’s widely available. All we ask in return is that you provide timely feedback on the product’s functionality and any bugs you experience. If you don’t feel you will be able to meet these expectations, please talk to your Account Manager. 

How is beta feedback gathered? 

We will be tracking feature usage and results. Additionally, we will arrange regular review sessions to get your direct feedback on Typeahead API. The frequency and timing of these meetings will be at your convenience. 

Support

Please use your Typeahead integration ticket for support.

FAQs

Q1) I don’t use Rapid’s Regions IDs, can I use the Beta Typeahead API? 

A) Yes, while we recommend using Rapid’s Regions IDs, the responses from the Typeahead API will also include coordinates and the name of the region that can be used in conjunction with your geography systems. 

Q2) Why am I not getting results back for Syria, North Korea, or Cuba? 

A) Lodging and geographic information for certain areas under US economic sanctions are not available via Typeahead API.