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.

Schema

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:

Copy
Copied
{
    "req_id": "some_unique_string",
    "data": {
        "itineraries": [
            {
                "segments": [
                    {
                        "arr": "TPE",
                        "cabin": 3,
                        "cxr": "BR",
                        "date": "2022-09-08",
                        "dep": "CDG",
                        "fltno": 88,
                        "rbd": "C"
                    }
                ]
            }
        ]
    }
}

In return, you'd get something similar to:

Copy
Copied
{
    "req_id": "some_unique_string",
    "data": {
        "advance_change": [],
        "amenity": {
            "aircrafts": [
                {
                    "cabin_pressure": "normal",
                    "display_text": "777 (widebody)",
                    "id": "3",
                    "model": "777",
                    "quality": "standard",
                    "type": "widebody",
                    "updated_at": "2016-05-31T10:00:47Z",
                    "window_size": "standard"
                }
            ],
    // ...

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.

Copy
Copied
{
	"control" : {
		// control parameters go here
	},
	// ...
}
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
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.

Copy
Copied
{
    "control": {
      "uta_application_filter": {
         "boarding_priority": ...,
         "check_in_priority": ...,
         "lounge_access": ...,
         "same_day_change": ...,
         "seat_selection": ...,
         "upgrade_eligibility": ...,
         "loyalty_rewards": ...
        }
    },
	// ...
}
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

Data parameters

Data parameters are all specified within a data object in the request body and describe the specifications of the requested tickets/reservations.

Copy
Copied
{
	// ...
	"data" : {
		// control parameters go here
	},
	// ...
}
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:

Copy
Copied
curl --location --request POST 'https://retailing.apis.atpco.net/retailing/consolidated' \
--header 'Content-Type: application/json' \
--header 'x-seller-id: 12345678' \
--header 'Accept-Language: en-UK' \
--header 'Authorization: Bearer token'\
--data-raw '{
    "data": {
        "itineraries": [
            {
                "segments": [
                    {
                        "dep": "IAD",
                        "arr": "MUC",
                        "cxr": "UA",
                        "fltno": 106,
                        "date": "2022-06-17",
                        "cabin": 1,
                        "fbc": "HH346LGT",
                        "rule_no": "G104",
                        "rbd": "H"
                    }
                ]
            }
        ]
    }
}'