Typeahead API for Rapid

Offer travelers suggestions as they search

Typehead (GET /suggestions) is a new API endpoint that lets you offer your travelers a suggestive search experience based on geographic regions, relevant locations, and available properties. This endpoint returns a list of suggestions based on partial search strings and any request parameters they’ve entered. Please contact your account manager to add Typeahead to your account.

How it works

Typeahead API is a language prediction tool—sometimes referred to as an autocomplete or autosuggest. It returns a list of regions, locations, or properties based on the input of partial information typed into a search box. When the user types 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

You’ll need to reach out to your account manager or Partner Connect representative to learn about the API. They’ll request access approval and, if you’re approved, will amend your agreement to include Typeahead. Once Typeahead has been enabled for your organization, the Partner Connect representative will support you with any necessary development.

Launch requirements:

• You must adopt and use the opaque access token process for authentication.
• Access tokens can only be used by the same circuit ID or API key that requested it.
• 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. See the list of Rapid's supported languages.

Authorization and access

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

Establish authorization

Authentication for the Typeahead API differs from our other Rapid API features in that it requires an access key. Using an authorization header, you will provide your apikey to call the EPS gateway to get an access key. Then, you can call the Typeahead API endpoint by passing the access key as the authorization header.

Example: Encode API Key in base64 format

var api_key = postman.getEnvironmentVariable("api_key");
var shared_secret= postman.getEnvironmentVariable("shared_secret");
var base64Hash = CryptoJS.enc.Utf8.parse(api_key + ":" + shared_secret);
var base64 = CryptoJS.enc.Base64.stringify(base64Hash);
postman.setEnvironmentVariable("base64",base64);

Get an opaque access token

An opaque access token—one that does not contain any information about the user or resource—is required to use the Typeahead API.

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" 

}

Make an autocomplete request

You’ll need to include some required information in the request headers and the query parameters. To make the response more robust, you can also include optional query parameters.

Request headers

Required

• Accept: specifies the response format that the client would like to receive back. This value must be application/json.
• AcceptEncoding: specifies the response encoding that the client would like to receive back. This value must be gzip.
• User-Agent: 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}. For example, TravelNow/3.30.112.

Query parameters

Required

• language: 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 as described by w3.org (for example, language=en-US). See the list of Rapid’s supported languages.
• text: the input string to query, with a limit of 150 characters (for example, text=Springfie).
• feature: changes the calculation of the suggestion results. Values include hierarchy, nearby_airport, and postal_code.
• line_of_business: informs the search_environment. This parameter provides search heuristics, and a valid value ensures the response will be more relevant. See the Allowed values table below for available options.

Optional

• type: describes the place the user is looking for. This parameter can be supplied multiple times with different values (for example, region_type=AIRPORT&region_type=CITY). If it’s not provided, the default will include all types. See the Allowed values table below for available options.
• region_id: filters the results to properties with the specified region.
• origin: specifies whether the query text is an origin rather than a destination. The default search will find destinations only.
• package_type: filters by the package types the user specifies. See the Allowed values table below for available options.
• limit: specifies the maximum number of suggestions returned by the response. This value must be between 1 and 10 (for example, limit=5). If this parameter is not provided, the default value is 10.

Allowed values

Any values not included in the table above will result in an error.

Data requests

Once you have the access_token, you’ll set up the GET request.

Sample request

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" 
  } 
]

Error codes

Typeahead API shares common error codes with the other Rapid APIs. All of those codes are detailed on our Common error responses page.

Interacting with other Rapid APIs

When the end user types text into the search bar, the Typeahead API pulls the region (region ID, name, coordinates, etc.) or property information, depending on the search’s designated type. The API then displays that information as results in the autocomplete list.

When the user selects a region from the autocomplete list, the Region API is called to obtain a property list around that region. Use the property IDs returned from that search to call the Shop API, get availability, and display the properties in the list.

If the user selects a property from the autocomplete list, the Shopping API will generate a details page with information on availability and the property contents.

API details

See the API Explorer and the Content API schema for the details of the /suggestions endpoint.