Mapping legacy/backwards-compatible requests to Consolidated endpoint requests

The Consolidated Routehappy 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 Consolidated endpoint requests in order to receive the same - or very close to the same - information as before.

Schema

Here is the latest schema for the Consolidated Endpoint.

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 Consolidated endpoint requests page or in the API's schema.

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 Consolidated 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

Consolidated request

An equivalent request to the Consolidated 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 Consolidated 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

Consolidated request

An equivalent request to the Consolidated 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 Consolidated 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

Consolidated request

An equivalent request to the Consolidated 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 Consolidated endpoint is that the legacy/backwards-compatible Hub endpoints works per leg, whereas the Consolidated 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 Consolidated endpoint.

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

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