Typeahead API beta Integration Guide
Description
This article provides an overview of the new Typeahead API beta on Rapid. This new feature is available upon request to partners on Rapid 3. It is a beta API endpoint, meaning the schema is subject to change before the feature’s full public launch. Please get in touch with your Account Manager if you would like to gain access and start testing Typeahead API.
How Typeahead API beta works
Typehead is a new API endpoint enables partners to offer their travelers a suggestive search experience based on geographic regions and relevant locations.
Sometimes known as an autocomplete or autosuggest, Typeahead API is a language prediction tool that returns a list of regions or locations 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, 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 APIYour Account Manager will provide an overview of the Typeahead API beta’s current limitations.
Once the partner agrees to proceed knowingthe feature’s limitations,Partner Connect will work with the partner’s technical team to align on integration strategy and establish launch timelines.
Limitations of the offering
- Specific properties are not returned.
- Partners must adopt and use the opaque access token process outlined below.
- Access tokens can only be used by the same CID/API key that requested.
- Access tokens can only exist for 25 minutes and will fail once a new access token is generated.
- 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.
The Typeahead API endpoint
Rapid’s Typeahead API is available to request (via partner CID) on the production endpoints by partners currently on Rapid version 3. Access will be granted upon request to join the beta. Once approved, your existing CIDs will have the permissions required to successfully use the API.
Below is a copy of the latest API schema, which includes the Typeahead API beta. To view the swagger documentation, copy and paste the YAML file into the swagger editor: https://editor.swagger.io/
YAML file: At the bottom of this page.
Authorization:
Authentication for the Typeahead API differs from our other Rapid API features. An access key is used to allow requests from the client 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.
Making an access key request
Parameters
- 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`
- The required `Authorization` parameter is 'Authorization' and value is 'Basic {apikey}:{shared_secret}'
Making an autocomplete request
Parameters
- 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`
- The required `Host` parameter specifies the host that the client would like to receive back. This must be `api.ean.com`. Eg. `api.ean.com`
- 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 `region_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®ion_type=CITY
Possible values: AIRPORT, CITY, MULTICITY, NEIGHBORHOOD, POI, ADDRESS, METROCODE, MULTIREGION, TRAINSTATION, METROSTATION, BUSSTATION
An 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.
- Hotel
- package_flight_hotel
- flight
- car
- The `max_results` 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. max_results=5
POST – https://api.ean.com/identity/oauth2/v3/token
Header:
Key: 'Authorization'
Value: 'Basic {apikey}:{shared_secret}'
Example response:
{
"access_token": "p1xy6rxahicQPUIX_Sq6a52yFnHXpX3ImaSX9sKiUI4:XM8qZiTr1HPDc8FgBE5HLvFTFdICuRFV0-l7gFWI-WU",
"token_type": "bearer",
"expires_in": 1800,
"scope": "demand-solutions.demand-api-wrappers-playground.all"
}
Once you have the access_token to make a typeahead request
Header is : Bearer {{access_token}}
API Response:
{
"region_id": 178279,
"region_type": "MULTICITY",
"name": "London (and vicinity)",
"name_full": "London (and vicinity), England, United Kingdom",
"coordinates": {
"latitude": 51.507538,
"longitude": -0.127804
},
"country_code": "GB",
"airport_code": "LON",
"metro_code": "LON"
},
{
"region_id": 2114,
"region_type": "CITY",
"name": "London",
"name_full": "London, England, United Kingdom",
"coordinates": {
"latitude": 51.507538,
"longitude": -0.127804
},
"country_code": "GB",
"airport_code": "LON",
"metro_code": "LON"
}
How Typeahead API interacts with other Rapid features
The Typeahead API is designed to integrate with Rapid’s Geography APIs (Region(s) APIs) or your specific geography solution. Its responses will contain Rapid API region IDs, coordinates, and, in most instances, country codes, airport codes, and metro codes.
To surface the most relevant lodging properties to travelers, it is recommended that your systems use these geographic indicators.
What it means to integrate Typeahead API beta
By adopting Typeahead API while it is in beta, you are getting early access 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 above, the Typeahead API beta’s schema is subject to change based on feedback from our beta users.
Your responsibilities as a beta partner
If you choose to participate in a beta test, you’ll 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 resultsAdditionally, 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
For additional support on the Typeahead API beta:
- You can post feedback or questions via the Rapid Typeahead API beta forum on the EPS Support site at XXX
- You can also email your Account Manager or Partner Connect representative
Latest and upcoming changes
Latest changes:
- None
Latest changes:
- None
FAQs
- I don’t use Expedia Group Region IDs, can I use the Typeahead API beta?
- Yes, while Region IDs are recommended, the responses from the Typeahead API will also include coordinates and the name of the region that can be used in conjunction with other geography systems.
- My access_token is expiring before the 30-minute window, what do I do?
- Make sure that no one else is creating an access_token based on the same apikey because when a new access_token is created it will automatically invalidate any earlier access_tokens that use the same apikey.
- Why am I not getting results back for Syria, North Korea or Cuba?
- Lodging and geographic information for certain areas under US economic sanctions is not available in the Typeahead.
Comments
1 comment
2 comments:
1) Auth API header Authorization value should be base64 encoded.
2) Both APIs' request header should include Host (yaml file needs an update as well).
Please sign in to leave a comment.