Mapping legacy/backwards-compatible requests to Routehappy API endpoint requests

The Routehappy API endpoint provides access to all Routehappy Content types - Amenities, UPAs, and UTAs - with a unified new schema.

This page shows how to map all legacy/backwards-compatible requests to their equivalent Routehappy API endpoint requests in order to receive the same - or very close to the same - information as before.

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.

Amenities endpoints

All legacy/backwards-compatible Amenities endpoints always use two query parameters: ids and include (see the Amenities examples page for full descriptions).

The ids parameter uses three different separators, depending on the context:

  • ~ (tilde) - separates the segments in a leg (in the /legs and /itineraries endpoints)
  • . (period) - separates the legs in an itinerary (in the /itineraries endpoint), and marks the point of turnaround
  • , (comma) - separates the segments (in the /segments endpoint), the legs (in the /legs endpoint), or the itineraries (in the /itineraries endpoint)
attention

You can see the full list of possible values for the amenity_categories_filter on the Routehappy API endpoint requests page or in the API's schema for the corresponding endpoint above.

Specifying the point of turnaround in /itineraries

While a period (.) can be used to specify the point of turnaround of an itinerary in the legacy/backwards-compatible /itineraries endpoints, the point of turnaround cannot be specified when using the Routehappy API endpoint.

Itineraries endpoint

The legacy/backwards-compatible Itineraries endpoints can be used to process multiple itineraries, with multiple legs each, with multiple segments per leg.

Legacy/Backwards-compatible request

Consider a request to the legacy or backwards-compatible Itineraries endpoint (/itineraries) that includes the following parameters:

Copy
Copied
ids=JFK-LHR-AA-106-20211215-ECON.LHR-JFK-AA-6930-20211222-ECON,JFK-MIA-AA-2262-20211215-ECON~MIA-LAX-AA-2289-20211215-ECON

and

Copy
Copied
include=segments.aircraft,segments.entertainment

Routehappy API request

An equivalent request to the Routehappy API endpoint looks like this:

Copy
Copied
{
  "control": {
    "includes": [
      "amenity"
    ],
    "amenity_categories_filter": [
      "aircraft",
      "entertainment"
    ],
    "os_override": [],
    "include_rq": true
  },
  "data": {
    "itineraries": [
      {
        "segments": [
          {
            "dep": "JFK",
            "arr": "LHR",
            "cxr": "AA",
            "fltno": 106,
            "date": "2021-12-15",
            "cabin": 1
          },
          {
            "dep": "LHR",
            "arr": "JFK",
            "cxr": "AA",
            "fltno": 6930,
            "date": "2021-12-22",
            "cabin": 1
          }
        ]
      },
      {
        "segments": [
          {
            "dep": "JFK",
            "arr": "MIA",
            "cxr": "AA",
            "fltno": 2262,
            "date": "2021-12-15",
            "cabin": 1
          },
          {
            "dep": "MIA",
            "arr": "LAX",
            "cxr": "AA",
            "fltno": 2289,
            "date": "2021-12-15",
            "cabin": 1
          }
        ]
      }
    ]
  }
}

Legs endpoint

The legacy/backwards-compatible Legs endpoints can be used to process multiple legs, with multiple segments each. In the Routehappy API endpoint, each leg should be sent as a single itinerary with all of the original leg's segments in it.

Legacy/Backwards-compatible request

Consider a request to the legacy or backwards-compatible Legs endpoint (/legs) that includes the following parameters:

Copy
Copied
ids=JFK-LHR-AA-106-20211215-ECON,LHR-JFK-AA-6930-20211222-ECON,JFK-MIA-AA-2262-20211215-ECON~MIA-LAX-AA-2289-20211215-ECON

and

Copy
Copied
include=power,entertainment,fresh_food

Routehappy API request

An equivalent request to the Routehappy API endpoint looks like this:

Copy
Copied
{
  "control": {
    "includes": [
      "amenity"
    ],
    "amenity_categories_filter": [
      "fresh_food",
      "entertainment",
      "power"
    ],
    "os_override": [],
    "include_rq": true
  },
  "data": {
    "itineraries": [
      {
        "segments": [
          {
            "dep": "JFK",
            "arr": "LHR",
            "cxr": "AA",
            "fltno": 106,
            "date": "2021-12-15",
            "cabin": 1
          }
        ]
      },
      {
        "segments": [
          {
            "dep": "LHR",
            "arr": "JFK",
            "cxr": "AA",
            "fltno": 6930,
            "date": "2021-12-22",
            "cabin": 1
          }
        ]
      },
      {
        "segments": [
          {
            "dep": "JFK",
            "arr": "MIA",
            "cxr": "AA",
            "fltno": 2262,
            "date": "2021-12-15",
            "cabin": 1
          },
          {
            "dep": "MIA",
            "arr": "LAX",
            "cxr": "AA",
            "fltno": 2289,
            "date": "2021-12-15",
            "cabin": 1
          }
        ]
      }
    ]
  }
}

Segments endpoint

The legacy/backwards-compatible Segments endpoints can be used to process multiple segments. In the Routehappy API endpoint, each segment should be sent as a single itinerary with a single segment in it.

Legacy/Backwards-compatible request

Consider a request to the legacy or backwards-compatible Segments endpoint (/segments) that includes the following parameters:

Copy
Copied
ids=JFK-LHR-AA-106-20211215-ECON,LHR-JFK-AA-6930-20211222-ECON,JFK-MIA-AA-2262-20211215-ECON,MIA-LAX-AA-2289-20211215-ECON

and

Copy
Copied
include=wifi

Routehappy API request

An equivalent request to the Routehappy API endpoint looks like this:

Copy
Copied
{
  "control": {
    "includes": [
      "amenity"
    ],
    "amenity_categories_filter": [
      "wifi"
    ],
    "os_override": [],
    "include_rq": true
  },
  "data": {
    "itineraries": [
      {
        "segments": [
          {
            "dep": "JFK",
            "arr": "LHR",
            "cxr": "AA",
            "fltno": 106,
            "date": "2021-12-15",
            "cabin": 1
          }
        ]
      },
      {
        "segments": [
          {
            "dep": "LHR",
            "arr": "JFK",
            "cxr": "AA",
            "fltno": 6930,
            "date": "2021-12-22",
            "cabin": 1
          }
        ]
      },
      {
        "segments": [
          {
            "dep": "JFK",
            "arr": "MIA",
            "cxr": "AA",
            "fltno": 2262,
            "date": "2021-12-15",
            "cabin": 1
          }
        ]
      },
      {
        "segments": [
          {
            "dep": "MIA",
            "arr": "LAX",
            "cxr": "AA",
            "fltno": 2289,
            "date": "2021-12-15",
            "cabin": 1
          }
        ]
      }
    ]
  }
}

Hub Legs Searches endpoint

The biggest difference between the legacy/backwards-compatible Hub Legs Searches endpoints and the Routehappy API endpoint is that the legacy/backwards-compatible Hub endpoints works per leg, whereas the Routehappy API endpoint works per itinerary. This means that Round Trip and Open Jaw journeys are sent as multiple legs to the Hub endpoint, whereas they are sent as a single itinerary to the Routehappy API endpoint.

Consider the following requests for the same round-trip to both the legacy/backwards-compatible Hub endpoints and the Routehappy API endpoint:

Hub endpointRoutehappy API endpoint
Copy
Copied
{
  "data": {
    "type": "legs_search",
    "attributes": {
      "fare_source": "1A",
      "legs": [
        {
          "segments": [
            {
              "dep": "BOS",
              "arr": "DEN",
              "carrier": "UA",
              "flt_no": "1129",
              "dep_date": "2021-12-09",
              "cabin_id": 1,
              "fare_basis_code": "TAG4AKES"
            },
            {
              "dep": "DEN",
              "arr": "LAX",
              "carrier": "UA",
              "flt_no": "2654",
              "dep_date": "2021-12-09",
              "cabin_id": 1,
              "fare_basis_code": "TAG4AKES"
            }
          ]
        },
        {
          "segments": [
            {
              "dep": "LAX",
              "arr": "DEN",
              "carrier": "UA",
              "flt_no": "1029",
              "dep_date": "2021-12-16",
              "cabin_id": 1,
              "fare_basis_code": "TAG4AKES"
            },
            {
              "dep": "DEN",
              "arr": "BOS",
              "carrier": "UA",
              "flt_no": "361",
              "dep_date": "2021-12-16",
              "cabin_id": 1,
              "fare_basis_code": "TAG4AKES"
            }
          ]
        }
      ]
    }
  }
}
Copy
Copied
{
  "control": {
    "includes": [
      "uta"
    ],
    "os_override": [],
    "include_rq": true
  },
  "currency": "USD",
  "data": {
    "itineraries": [
      {
        "src": "1A",
        "segments": [
          {
            "dep": "BOS",
            "arr": "DEN",
            "cxr": "UA",
            "fltno": 1129,
            "date": "2021-12-09",
            "cabin": 1,
            "fbc": "TAG4AKES"
          },
          {
            "dep": "DEN",
            "arr": "LAX",
            "cxr": "UA",
            "fltno": 2654,
            "date": "2021-12-09",
            "cabin": 1,
            "fbc": "TAG4AKES"
          },
          {
            "dep": "LAX",
            "arr": "DEN",
            "cxr": "UA",
            "fltno": 1029,
            "date": "2021-12-16",
            "cabin": 1,
            "fbc": "TAG4AKES"
          },
          {
            "dep": "DEN",
            "arr": "BOS",
            "cxr": "UA",
            "fltno": 361,
            "date": "2021-12-16",
            "cabin": 1,
            "fbc": "TAG4AKES"
          }
        ]
      }
    ]
  }
}