Skip to main content

Response mapping index

With the new v3 the response object has changed around a lot so this guide will explain all the changes and help you navigate the new structure.

Important differences​

  • rating & ratingBreakdown properties have been added which give a rating (partner quality score) based on travellers booking experience feedback
  • Itineraries now are unordered, you can utilize sortingOptions to order flights.
  • sustainabilityData is available through an opt-in parameter includeSustainabilityData. You can check more information here.
  • Currencies have been removed from the response data.
  • Changed a lot of objects types to be maps in v3 instead of arrays in v1.0.
  • The structure of the response has now changed, with the main content under content.results instead of query object
  • All properties in the response now are formatted with camelCase instead of an PascalCase . For example PricingOptions has become pricingOptions.
  • Dates have now changed from a string value 2023-01-20T16:45:00 to a Date object.
  • We have the following new fields

Response Data Structure​

Since the data response structure has changed, we will need a new way to retrieve and manipulate the data.

In order to get all the flights we will need to get the itineraryId from the sortingOptions based on the preferred criteria.

Here is an example where we get all best flights in Javascript.

const bestItineraryIds = response.content.sortingOptions.best.map(
  (flight) => flight.itineraryId,
);

const bestItineraries = Object.keys(response.content.results.itineraries)
  .filter((key) => bestItineraryIds.includes(key))
  .reduce((obj, key) => {
    obj[key] = response.content.results.itineraries[key];
    return obj;
  }, {});

New in v3​

Action​

action is a new field added which instructs you on how to treat the flight results in the response. For example, if the value of the action is RESULT_ACTION_REPLACED then you should replace the previous data with the new data you received.

There are three different action values that can be in the response.

Action v3Description
RESULT_ACTION_REPLACEDThe results contained in this response fully replace any previously received results.
RESULT_ACTION_NOT_MODIFIEDThe response contains no new results in this search session. Any previously received results for this inventory type still apply.
RESULT_ACTION_OMITTEDNot able to provide results for the request. Therefore, the response does not contain any results and will not in a future polling operation.

Stats​

Stats provide information regarding the flights returned. It contains the minPrice, minDurtation, maxDuration of the flights and also an aggregated object stops which contains the data of how are direct, have 1 stop, or multiple stops.

Stats can be useful to get fastest/longest trip amongst other things.

Show stats structure
{
  "stats": {
    "itineraries": {
      "minDuration": 605,
      "maxDuration": 1990,
      "total": {
        "count": 10,
        "minPrice": {
          "amount": 147320,
          "unit": "PRICE_UNIT_MILLI"
        }
      },
      "stops": {
        "direct": {
          "total": {
            "count": 0,
            "minPrice": {
              "amount": 0,
              "unit": "PRICE_UNIT_UNSPECIFIED"
            }
          },
          "ticketTypes": {
            "singleTicket": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            },
            "multiTicketNonNpt": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            },
            "multiTicketNpt": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            }
          }
        },
        "oneStop": {
          "total": {
            "count": 8,
            "minPrice": {
              "amount": 884260,
              "unit": "PRICE_UNIT_MILLI"
            }
          },
          "ticketTypes": {
            "singleTicket": {
              "count": 8,
              "minPrice": {
                "amount": 884260,
                "unit": "PRICE_UNIT_MILLI"
              }
            },
            "multiTicketNonNpt": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            },
            "multiTicketNpt": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            }
          }
        },
        "twoPlusStops": {
          "total": {
            "count": 2,
            "minPrice": {
              "amount": 147320,
              "unit": "PRICE_UNIT_MILLI"
            }
          },
          "ticketTypes": {
            "singleTicket": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            },
            "multiTicketNonNpt": {
              "count": 0,
              "minPrice": {
                "amount": 0,
                "unit": "PRICE_UNIT_UNSPECIFIED"
              }
            },
            "multiTicketNpt": {
              "count": 2,
              "minPrice": {
                "amount": 147320,
                "unit": "PRICE_UNIT_MILLI"
              }
            }
          }
        }
      },
      "hasChangeAirportTransfer": false
    }
  }
}

Sorting options​

Sorting options are used to help you sort itineraries based on your preferred criteria. You can now sort the itineraries based on fastest,cheapest or best trips.

The sorting options now give the flexibility to sort itineraries based on your need compared to v1.0 where they were pre-ordered.

Sorting options contain the iteneraryId that can be used to filter out the flights in the itineraries object returned.

Show sortingOptions structure
{
  "sortingOptions": {
    "best": [
      {
        "score": 1,
        "itineraryId": "11235-2301201930--32480-0-13554-2301202055|13554-2301211130--32480-0-11235-2301211255"
      },
      {
        "score": 0.971871,
        "itineraryId": "11235-2301201255--32480-0-13554-2301201420|13554-2301211130--32480-0-11235-2301211255"
      },
      },
      ...
    ],
    "cheapest": [
      {
        "score": 1,
        "itineraryId": "11235-2301201930--32480-0-13554-2301202055|13554-2301211130--32480-0-11235-2301211255"
      },
      ...
    ],
    "fastest": [
      {
        "score": 1,
        "itineraryId": "11235-2301201930--32480-0-13554-2301202055|13554-2301211130--32480-0-11235-2301211255"
      },
      ...
    ]
  }
}

Changed in v3​

Itineraries​

  • agentIds are now in string format.
  • The outbound / inbound leg is now listed as the key of the object, separated by a |
  • There is now a fares object that will give bookingCode and fareBasisCode, linked to a segment.
  • deeplink is an Impact link now.
info

Adding unique identifier to a deeplink

If you want to add a unique identifier to an Impact deeplink, you can do it by adding a p.auid and sharedid query parameter at the end of the link.

Adding tracking to Flight Live Prices

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "OutboundLegId": "11235-2301201",
  "InboundLegId": "13554-2301211",
  "PricingOptions": [
    {
      "Agents": [4061456],
      "QuoteAgeInMinutes": 0,
      "Price": 268.07,
      "DeeplinkUrl": "https://pa.."
    }
  ],
  "BookingDetailsLink": {
    "Uri": "/apiservices/pric..",
    "Body": "OutboundLegId=112..",
    "Method": "PUT"
  }
}
{
  "11235-2301201130": {
    "pricingOptions": [
      {
        "price": {
          "amount": 73100,
          "unit": "PRICE_UNIT_MILLI"
        },
        "agentIds": ["wauk"],
        "items": [
          {
            "price": {
              "amount": 73100,
              "unit": "PRICE_UNIT_MILLI"
            },
            "agentId": "wauk",
            "deepLink": "https://skyscanner.px..",
            "fares": [
              {
                "segmentId": "11235-13554",
                "bookingCode": "",
                "fareBasisCode": ""
              }
            ]
          }
        ]
      }
    ],
    "legIds": ["11235-2301201130", "13554-2301211130"],
    "sustainabilityData": {
      "isEcoContender": false,
      "ecoContenderDelta": -1.7906785011291504
    }
  }
}

Legs​

Legs show the details of an itinerary. Every key of the object is an itineraryId.

  • There is no longer a directionality outbound/inbound for legs, and FlightNumbers have been moved to segments.
  • Directionality has been removed
  • FlightNumbers has been moved to segments

Also, the departureDateTime and arrivalDateTime is now an object.

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "Id": "11235-2301201645",
  "SegmentIds": [0],
  "OriginStation": 11235,
  "DestinationStation": 13554,
  "Departure": "2023-01-20T16:45:00",
  "Arrival": "2023-01-20T18:10:00",
  "Duration": 85,
  "JourneyMode": "Flight",
  "Stops": [],
  "Carriers": [881],
  "OperatingCarriers": [881],
  "Directionality": "Outbound",
  "FlightNumbers": [
    {
      "FlightNumber": "1455",
      "CarrierId": 881
    }
  ]
}
{
  "13554-2301211640": {
    "originPlaceId": "95565050",
    "destinationPlaceId": "95673668",
    "departureDateTime": {
      "year": 2023,
      "month": 1,
      "day": 21,
      "hour": 16,
      "minute": 40,
      "second": 0
    },
    "arrivalDateTime": {
      "year": 2023,
      "month": 1,
      "day": 21,
      "hour": 18,
      "minute": 5,
      "second": 0
    },
    "durationInMinutes": 85,
    "stopCount": 0,
    "marketingCarrierIds": ["-32480"],
    "operatingCarrierIds": ["-32480"],
    "segmentIds": ["13554-11235-2301211640"]
  }
}

Segments​

Note that segmentId is now the key of the object 13554-11235-2301211640-2301211805--32480.

Also, the departureDateTime and arrivalDateTime is now a date object.

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "Id": 0,
  "OriginStation": 11235,
  "DestinationStation": 13554,
  "DepartureDateTime": "2023-01-20T16:45:00",
  "ArrivalDateTime": "2023-01-20T18:10:00",
  "Carrier": 881,
  "OperatingCarrier": 881,
  "Duration": 85,
  "FlightNumber": "1455",
  "JourneyMode": "Flight",
  "Directionality": "Outbound"
}
{
  "13554-11235-2301211640-2301211805--32480": {
    "originPlaceId": "95565050",
    "destinationPlaceId": "95673668",
    "departureDateTime": {
      "year": 2023,
      "month": 1,
      "day": 21,
      "hour": 16,
      "minute": 40,
      "second": 0
    },
    "arrivalDateTime": {
      "year": 2023,
      "month": 1,
      "day": 21,
      "hour": 18,
      "minute": 5,
      "second": 0
    },
    "durationInMinutes": 85,
    "marketingFlightNumber": "1452",
    "marketingCarrierId": "-32480",
    "operatingCarrierId": "-32480"
  }
}

Places​

  • entityId has been added to the places object. This is an internal id for Skyscanner.
  • The object now has a key which is the entityId value.
  • Id has been removed

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "Id": 4698,
  "ParentId": 247,
  "Code": "LON",
  "Type": "City",
  "Name": "London"
}
{
  "27544008": {
    "parentId": "29475375",
    "name": "London",
    "type": "PLACE_TYPE_CITY",
    "iata": "LON",
    "entityId": "27544008"
  }
}

Agents​

  • OptimisedForMobile has been renamed to isOptimisedForMobile
  • Status has been removed
  • New rating & ratingBreakdown properties have been added in order to show how reliable an agent is.
  • New feedbackCount property has been added to [placeholder]

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "Id": 2807320,
  "Name": "Iberia Express",
  "ImageUrl": "https://s1.ap..",
  "Status": "UpdatesComplete",
  "OptimisedForMobile": true,
  "Type": "Airline"
}
{
  "ibex": {
    "name": "Iberia Express",
    "type": "AGENT_TYPE_AIRLINE",
    "imageUrl": "https://logos.skys..",
    "feedbackCount": 196,
    "rating": 4.3,
    "ratingBreakdown": {
      "customerService": 5,
      "reliablePrices": 4.24262,
      "clearExtraFees": 4.64124,
      "easeOfBooking": 4.720964,
      "other": 3.604824
    },
    "isOptimisedForMobile": true
  }
}

Carriers​

  • Id of carrier is now moved outside as the key.
  • Code has been renamed to iata
  • DisplayCode has been removed
  • allianceId has been added and points to the alliance of the carrier.

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "Id": -32480,
  "Code": "BA",
  "Name": "British Airways",
  "ImageUrl": "https://s1.apideeplink..",
  "DisplayCode": "BA"
}
{
  "-32480": {
    "name": "British Airways",
    "allianceId": "-32000",
    "imageUrl": "https://logos.skyscnr..",
    "iata": "BA"
  }
}

Dates​

Dates have changed from string values to an object. Here is the new structure of dates in v3.

Here is the new structure in v3 compared to v1.0.

v1.0 (before)v3 (after)
{
  "departureDateTime": "2023-01-21T16:40:00"
}
{
  "departureDateTime": {
    "year": 2023,
    "month": 1,
    "day": 21,
    "hour": 16,
    "minute": 40,
    "second": 0
  }
}

Layout​

See the layout of the response in the API reference.