Skip to main content

Migration guide

Overview​

This documentation is a guide to support you with the migration from v1.0 to v3 of the Geo API (Geo Catalog).

The API will return all the geographical entities that can be used in flights searches:

  • Airports
  • Cities
  • Countries (Flights Indicative Prices API only)

It will also return Continents for completion, though they cannot be used in flights searches directly.

Key changes​

  • The API key is now passed as a header.
  • The response keys are in camelCase instead of PascalCase.
  • The response data is not nested anymore. Instead, we return a flat response structure which can be nested as needed based on the parent ID.
  • The places are now returned as a map so the relationships between them can be resolved more efficiently.
  • We removed the coordinates of airports and cities. We didn't think they were actually being used. We can consider adding them on demand so contact us if you think you need them for your use-case.

Changes​

info

What are the variables

The URL changed:

v1.0 (before)v3 (after)
{base-url}/geo/v1.0{base-url}/v3/geo/hierarchy/flights/{locale}
Show request example
curl --location --request GET 'https://partners.api.skyscanner.net/apiservices/v3/geo/hierarchy/flights/en-GB' \
    --header 'x-api-key: prtl6749387986743898559646983194'

The simplified the response structure a lot. The values are now normalised, so they can be used in a more flexible way.

v1.0 (Before)​

response
├── Continents
│   ├── Id
│   ├── Name
│   └── Countries
│   │   ├── CurrencyId
│   │   └── Cities
│   │   │   ├── Id
│   │   │   ├── Name
│   │   │   ├── SingleAirportCity
│   │   │   ├── CountryId
│   │   │   ├── Location
│   │   │   ├── IataCode
│   │   │   └── Airports
│   │   │   │   ├── Id
│   │   │   │   ├── Name
│   │   │   │   ├── CityId
│   │   │   │   ├── CountryId
└── └── └── └── └── Location

v3 (After)​

response
├── status
├── places
│   ├── entityId
│   ├── parentId
│   ├── name
│   ├── type
└── └── iata
Show the response comparison
v1.0 (before)v3 (after)
{
  "Continents": [
    {
      "Id": "E",
      "Name": "Europe",
      "Countries": [
        {
          "Id": "UK",
          "Name": "United Kingdom",
          "CurrencyId": "GBP",
          "LanguageId": "EN",
          "Regions": [
            {
              "Id": "ENGLA",
              "Name": "England",
              "CountryId": "UK"
            },
            {
              "Id": "N_IRE",
              "Name": "Northern Ireland",
              "CountryId": "UK"
            },
            {
              "Id": "SCOTL",
              "Name": "Scotland",
              "CountryId": "UK"
            },
            {
              "Id": "WALES",
              "Name": "Wales",
              "CountryId": "UK"
            }
          ],
          "Cities": [
            {
              "Id": "LOND",
              "Name": "London",
              "SingleAirportCity": false,
              "CountryId": "UK",
              "RegionId": "ENGLA",
              "Location": "-0.094346534, 51.504117",
              "IataCode": "LON",
              "Airports": [
                {
                  "Id": "LHR",
                  "Name": "London Heathrow",
                  "CityId": "LOND",
                  "CountryId": "UK",
                  "RegionId": "ENGLA",
                  "Location": "-0.452778, 51.471389"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
{
  "status": "RESULT_STATUS_COMPLETE",
  "places": {
    "95565050": {
      "entityId": "95565050",
      "parentId": "27544008",
      "name": "London Heathrow",
      "type": "PLACE_TYPE_AIRPORT",
      "iata": "LHR"
    },
    "27544008": {
      "entityId": "27544008",
      "parentId": "29475375",
      "name": "London",
      "type": "PLACE_TYPE_CITY",
      "iata": "LON"
    },
    "29475375": {
      "entityId": "29475375",
      "parentId": "27563221",
      "name": "United Kingdom",
      "type": "PLACE_TYPE_COUNTRY"
    },
    "27563221": {
      "entityId": "27563221",
      "name": "Europe",
      "type": "PLACE_TYPE_CONTINENT"
    }
  }
}

The type of the place determines now which entity type it is, instead of relying on the nesting hierarchy.

You can now determine the parents of a place following the parentId up the hierarchy.

The hierarchy is Airport -> City -> Country -> Continent. Note that there can be missing items from the hierarchy in some cases. For example, there can be airports that are not in a city, so the parent ID in that case would reference a country.