Consolidated Endpoint
Routehappy API Endpoint
The Routehappy API endpoint provides access to all Routehappy Content types - Amenities, UPAs, and UTAs - from a single request, with a new schema and new functionality compared with the previous Routehappy Rich Content APIs.
Attention
The table below contains the URLs for the UPA Staging, Gold and Production environments of the Routehappy API endpoint's and schemas, respectively.
| API Endpoint | Schema | UPA DS* | UTA DS* | Amenities DS* |
|---|---|---|---|---|
| https://gold.retailing.apis.atpco.net/stagingupa/consolidated | UPA Staging Schema | Hub Gold | ATPCO Subs Prod | Amenities Prod |
| https://gold.retailing.apis.atpco.net/routehappy/consolidated | Gold Schema | Hub Prod | ATPCO Subs Prod | Amenities Prod |
| https://retailing.apis.atpco.net/routehappy/consolidated | Production Schema | Hub Prod | ATPCO Subs Prod | Amenities Prod |
* DS - Data Source within ATPCO from which the system is processing the data it displays.
NOTE: For field descriptions below stating "(requires extended_req_fields feature)", please refer to Opt-in Features for more information.
Request parameters
The top-level parameters in a request to the Routehappy API endpoint are req_id, acct_code, control, currency, data, pos, src, psgrs, pcc, travel_agency_id, and office_id. Much of the definition of your request will fall within the control and data parameters.
| Field Name | Description | Type | Values |
|---|---|---|---|
data | Wrapper for the specifications of the requested tickets/reservations. | Object | |
control | (optional) Wrapper for the specifications of the types of Routehappy content to be included in the response. | Object | |
req_id | (optional) Request identifier that you can set (up to 50 characters). You will receive the same identifier in the response. | String | |
acct_code | (optional) Needed for corporate fares (can be overriden on itinerary level). | String | |
currency | (optional) The type of currency for which the ticket was purchased and will be applied to all itineraries (can be overriden on itinerary level). | String | currency codes |
pos | (optional) (requires extended_req_fields feature) The point of sale to be applied to all itineraries (can be overriden on itinerary level). | String | |
src | (optional) (requires extended_req_fields feature) Where the pricing/fare came from, applies to all itineraries (can be overriden on itinerary level). Valid GDS code must be provided. | String | |
psgrs | (optional) (requires extended_req_fields feature) The passangers list consisted of PAX classes to be applied for all itineraries (can be overriden on itinerary level). | Array | ADT, CNN, and others |
pcc | (optional) A pseudo city code. This code is used in ATPCO fare filings to determine if the sales channel has access to this data. Applies to all itineraries (can be overriden on itinerary level). | String | |
travel_agency_id | (optional) A Travel Agency ID code. This code is used in ATPCO fare filings to determine if the sales channel has access to this data . Applies to all itineraries (can be overriden on itinerary level). | String | |
office_id | (optional) An Office ID code. The first 3 characters represent the office location IATA city code, and the rest of the characters represent the office ID. The office location and ID codes are used in ATPCO fare filings to determine if the sales channel has access to this data. Applies to all itineraries (can be overriden on itinerary level). | String |
Channels that provide security codes need to use just one of pcc, travel_agency_id or office_id, they are not required to pass all three at the same time. In case more than one of the fields are provided at the same time, pcc will take precedence over travel_agency_id, and travel_agency_id will take precedence over office_id.
Request identifier
Use the req_id parameter when you need to tie any request to its response with your own string. The response returns a field with the same value as passed in the request. Please note that the uniqueness of this value is your responsibility.
Example
To receive a response to this request containing your unique string, include the req_id field in the request as such:
In return, you'd get something similar to:
Control parameters
Control parameters are all specified within a control object in the request body and describe the specifications of the types of Routehappy Content to be included in the response.
| Field Name | Description | Type | Values |
|---|---|---|---|
includes | (optional) Specifies which Routehappy Content types to include in the response | Array | amenity, upa, uta |
include_rq | (optional) Use if you would like to include the segment/flight information in the response. This is important if you want to map back to flight segments but the request data is not available. | Boolean | true, false |
Amenities control
| Field Name | Description | Type | Values |
|---|---|---|---|
amenity_categories_filter | (optional) Specifies which amenities categories and summaries should be in the response | Array | aircraft, beverage, entertainment, fresh_food, layout, power, seat, wifi, aircraft_summary, entertainment_summary, fresh_food_summary, layout_summary, power_summary, seat_summary, wifi_summary |
UPAs control
| Field Name | Description | Type | Values |
|---|---|---|---|
upa_categories_filter | (optional) Specifies which UPA categories should be in the response | Array | seat, wi-fi, meals, lounge, and others (more information coming soon) |
upa_sources_filter | (optional) Specifies which UPAs should be in the response, based on their source | Array | ATPCO, airline |
upa_attributes_include | (optional) Specifies which UPA attributes should be included in the response. If omitted or empty, all attributes are included by default. See the examples section for more information. | Array | photo, video, tour, infographic, marketing_graphic, seat_characteristics |
upa_attributes_filter | (optional) Specifies which UPAs should be returned in the response, based on what attributes they have. If omitted or empty, no filters are applied and all matched UPAs are returned. See the examples section for more information. | Array | photo, video, tour, infographic, marketing_graphic, seat_characteristics |
upa_seat_characteristics_filter | (optional) (requires seat_characteristics feature) Specifies which UPAs should be returned in the response, based on what seat characteristic codes they have been targeted to. This filter will only apply to the UPAs which have passed the internal seat characteristics validation. This filter will be applied only to UPAs which have seat characteristic targeting, meaning that UPAs without seat characteristics will be retained in the response. If only the UPAs with the specified seat characteristic codes are needed, this filter needs to be combined with the upa_attributes_filter. If omitted or empty, no filters are applied and all matched UPAs are returned. See the Opt-In features section for more information. | Array | Any valid seat characteristic codes |
disable_upa_photo | (optional) Specifies whether photos should be ommitted from the response | Boolean | true, false |
disable_upa_tour | (optional) Specifies whether tours should be ommitted from the response | Boolean | true, false |
disable_upa_video | (optional) Specifies whether videos should be ommitted from the response | Boolean | true, false |
disable_upa_infographics | (optional) Specifies whether infographic should be ommitted from the response | Boolean | true, false |
disable_upa_marketing_graphics | (optional) Specifies whether marketing graphics should be ommitted from the response | Boolean | true, false |
Segments Control
| Field Name | Description | Type | Values |
|---|---|---|---|
disable_technical_stops | (optional) Specifies whether technical stops (hidden segments) should be omitted from the response. Setting this to true will show each segment in the response as it was passed in the request without expanding it to include technical stops. | Boolean | true, false |
UTAs control
| Field Name | Description | Type | Values |
|---|---|---|---|
ticket_attributes_filter | (optional) Specifies which UTA categories should be in the response | Array | advance_change, boarding_priority, brand, cancellation, carry_on_baggage, checked_baggage, check_in_priority, lounge_access, same_day_change, seat_selection, upgrade_eligibility, loyalty_rewards, transferable_funds |
os_override | (optional) Specifies which types of data the Routehappy API should process using data from branded fares instead of baggage engine | Array | advance_change, cancellation, carry_on_baggage, checked_baggage |
UTA application filter
UTA application filters are all specified within an optional uta_application_filter object in the control section and describe the specifications of the requested UTAs' applications. Any unspecified fields will simply return the UTAs of the field's type without filtering them by their application which is the default API behaviour - assuming no other filters, features or specifications have been applied. advance_change, cancellation, brand, checked_bag and carry_on_bag cannot be filtered due to their different nature.
| Field Name | Description | Type | Values |
|---|---|---|---|
boarding_priority | (optional) Specifies the desired application type of Boarding Priorities in the response | Array | free, for a charge, not offered, displayed |
check_in_priority | (optional) Specifies the desired application type of Check In Priorities in the response | Array | free, for a charge, not offered, displayed |
lounge_access | (optional) Specifies the desired application type of Lounge Accesses in the response | Array | free, for a charge, not offered, displayed |
same_day_change | (optional) Specifies the desired application type of Same Day Changes in the response | Array | free, for a charge, not offered, displayed |
seat_selection | (optional) Specifies the desired application type of Seat Selections in the response | Array | free, for a charge, not offered, displayed |
upgrade_eligibility | (optional) Specifies the desired application type of Upgrade Eligibilities in the response | Array | free, for a charge, not offered, displayed |
loyalty_rewards | (optional) Specifies the desired application type of Loyalty Rewards in the response | Array | free, for a charge, not offered, displayed |
transferable_funds | (optional) Specifies the desired application type of Transferable Funds in the response | Array | free, for a charge, not offered, displayed |
Data parameters
Data parameters are all specified within a data object in the request body and describe the specifications of the requested tickets/reservations.
| Field Name | Description | Type | Values |
|---|---|---|---|
tkt_date | (optional) Ticketing date | Date-formatted string | YYYY-MM-DD |
res_date | (optional) Date that the reservation was made | Date-formatted string | YYYY-MM-DD |
itineraries | List of itineraries (objects) in the request | Array |
Itinerary parameters
Itinerary parameters reside within the itineraries array and describe the specification of single itinerary.
| Field Name | Description | Type | Values |
|---|---|---|---|
segments | List of flight segments (objects) | Array | |
pos | (optional) Point of sale of the ticket. Can be a city, country, or airport (2-3 letter code). Overrides the top-level request param. | String | IATA codes |
psgrs | (optional*) List containing a single passenger type (string). Include one type of passenger on the ticket and the passenger type will be mapped to data. * psgrs defaults to ADT if not included when when requesting UPAs or UTAs. Overrides the top-level request param. | Array | ADT, CNN, and others |
src | (optional*) Where the pricing/fare came from. Overrides the top-level request param. Valid GDS code must be provided. | String | |
acct_code | (optional) (requires extended_req_fields feature) Needed for corporate fares. Overrides the top-level request param. | String | |
currency | (optional) (requires extended_req_fields feature) The type of currency for which the ticket was purchased. Overrides the top-level request param. | String | currency codes |
pcc | (optional) (requires extended_req_fields feature) A pseudo city code. This code is used in ATPCO fare filings to determine if the sales channel has access to this data. Overrides the top-level request param. | String | |
travel_agency_id | (optional) (requires extended_req_fields feature) A Travel Agency ID code. This code is used in ATPCO fare filings to determine if the sales channel has access to this data. Overrides the top-level request param. | String | |
office_id | (optional) (requires extended_req_fields feature) An Office ID code. The first 3 characters represent the office location IATA city code, and the rest of the characters represent the office ID. The office location and ID codes are used in ATPCO fare filings to determine if the sales channel has access to this data. Overrides the top-level request param. | String |
Segment parameters
Segment parameters reside within the segments array and describe the specification of a single segment.
| Field Name | Description | Type | Values |
|---|---|---|---|
arr | Arrival airport for the itinerary segment | String | IATA codes |
cabin | Cabin of the fare where 1=economy, 2=premium economy, 3=business, 4=first | integer | 1-4 |
cxr | Carrier for the itinerary segment | String | IATA codes |
date | Departure date for the itinerary segment | Date-formatted string | YYYY-MM-DD |
dep | Departure airport for the itinerary segment | String | IATA codes |
fbc | (optional) Fare basis code. This field is required when fare-related/brand information is requested (for example, UPAs or UTAs) | String | |
rule_no | (optional) Rule number field is fully optional and takes effect only when passed in with fbc to discover a more specific fare when multiple variants are available for the search criteria | String | |
fltno | Flight number for the itinerary segment | integer | 1-9999 |
rbd | (optional) Reservation booking designator for the itinerary segment | upper-case character | A-Z |
Header controls
Some settings are controlled by the headers, which are for general usage and not tightly related to the itineraries.
| Header Name | Value | Type | Values |
|---|---|---|---|
Accept-Language | A valid ISO-639 2-alpha code language (for example, us) or 2-alpha code language with region-specific code (for example, en-UK). This changes the language in the response wherever applicable. Priority input in all the languages is supported. The default language is en. | String | ATPCO supported languages |
x-seller-id | A custom designator that marks the ID of a seller on whose behalf you are making the request. | integer | 8 characters |
Example of using both headers in a request: