Overall Series Compare

Bookings Overall Series Compare API returns two, time-based bookings overall data series at once: one defined by the specified {BookingsTimeframes} and {IATACodes} and another defined by {Comparison...} and compare_ prefixed query parameters (or auto-calculated with default values where specified).
Additional comparative time-based data series between the two data series are returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/flights/bookings/overall/series/compare

Path Parameters

Name	Description	Type	Examples
*{billing_plan}	Billing plan to be applied to the call.	string	ondemand
*{account_id}	Provided identifier of the account.	string

Header Parameters

Name	Description	Type	Examples
*x-api-key	Provided API key {x_api_key} that allows authentication.	string
*Authorization	Provided token {jwt_bearer} that allows authorization.	string	Bearer {jwt_bearer}

Query Parameters

Name	Description	Type	Examples	Default
*{BookingsTimeframes}	Flights Bookings timeframes filter.	BookingsTimeframes
*{IATACodes}	Actual IATA code identifiers.	IATACodes
*period	Time unit of the series.	string	day week month
{Comparison BookingsTimeframes}	Comparison Flights Bookings timeframes filter.	ComparisonBookingsTimeframes		One year before correspondent and valued {BookingsTimeframes}.
{ComparisonIATACodes}	Comparison IATA code identifiers.	ComparisonIATACodes		Same as {IATACodes}.
ⓝ departure_country ⓝ compare_departure_country	Filter by country of departure in ISO 3166-1 alpha-2 standard format (in lower case).	string	it
ⓝ arrival_country ⓝ compare_arrival_country	Filter by country of arrival in ISO 3166-1 alpha-2 standard format (in lower case).	string	fr
ⓝ cabin_class ⓝ compare_cabin_class	Filter by booked cabin class of the flight.	string	economy business first
ⓝ haul ⓝ compare_haul	Filter by duration range of the booked flight.	string	short medium long
flight_type compare_flight_type	Filter by flight type.	string	domestic international
trip_type compare_trip_type	Filter by trip type.	string	oneway round_trip
stop_days.eq stop_days.gt stop_days.gte stop_days.lt stop_days.lte compare_stop_days.eq compare_stop_days.gt compare_stop_days.gte compare_stop_days.lt compare_stop_days.lte	Filter by total number of days elapsed between multi-routes flights departure dates, including both stay time and flight connection waiting time. Field value can be filtered using multiple comparison modes:     .eq=     → =     .gt=      → >     .gte=    → ≥     .lt=        → <     .lte=      → ≤	int
pax.eq pax.gt pax.gte pax.lt pax.lte compare_pax.eq compare_pax.gt compare_pax.gte compare_pax.lt compare_pax.lte	Filter by number of passengers that booked the flight. Field value can be filtered using multiple comparison modes:     .eq=     → =     .gt=      → >     .gte=    → ≥     .lt=        → <     .lte=      → ≤	int

Supported values for period

• day
• week
• month

Supported values for cabin_class

• economy
• premium_economy
• business
• premium_business
• first
• premium_first

Supported values for haul

• short
• medium
• long

Supported values for flight_type

• domestic
• international

Supported values for trip_type

• oneway
• round_trip

Example

curl -X GET 'https://api.datappeal.io/v4/{billing_plan}/account/{account_id}/flights/bookings/overall/series/compare?from=2022-02-01&to=2022-03-31&iata_departure_code=flr&period=month' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Overall Series Compare data has been successfully returned.

Body

FlightsBookingsComparedSeriesOverall

Field	Description	Type
actual	Bookings overall data for the actual timeframe.	FlightsBookingsComparableSeriesOverall
comparison	Bookings overall data for the comparison timeframe.	FlightsBookingsComparableSeriesOverall
variation	Calculated difference between actual and comparison.	FlightsBookingsSeriesOverallVariation

FlightsBookingsComparableSeriesOverall

Field	Description	Type
timeframe	Reference date range.	Timeframe
value	Bookings overall data series for the corresponding timeframe.	FlightsBookingsSeriesOverall

Timeframe

Field	Description	Type
*from	Start date of timeframe.	date
*to	End date of timeframe.	date

FlightsBookingsSeriesOverall

Field	Description	Type
series	Bookings overall series data for the requested timeframe and period.	array[FlightsBookingsSeriesOverallElement]

FlightsBookingsSeriesOverallElement

Field	Description	Type
*period	Date representing the requested period, corresponding to the first day of the period. day: the day itself. week: first day of the corresponding week. month: first day of the corresponding month.	date
*value	Bookings overall data of corresponding period.	FlightsBookingsOverall

FlightsBookingsOverall

Field	Description	Type
passengers	Count of passengers by booking status.	FlightsBookingsPassengers
days_in_advance	Average number of days elapsed between booking/cancellation date and departure date.	FlightsBookingsDaysInAdvance
partition	Incidence percentage of the group's confirmed passengers over total confirmed passengers.	decimal

FlightsBookingsPassengers

Field	Description	Type
confirmed	Count of confirmed (not canceled) passengers.	int
canceled	Count of canceled passengers.	int
total	Count of total passengers.	int

FlightsBookingsDaysInAdvance

Field	Description	Type
booking	Average number of days elapsed between booking date and departure date.	decimal
cancellation	Average number of days elapsed between cancellation date and departure date.	decimal

FlightsBookingsSeriesOverallVariation

Field	Description	Type
series	Bookings overall data series for the requested timeframe and period.	array[FlightsBookingsSeriesOverallVariationElement]

LocationSeriesOverallVariationElement

Field	Description	Type
*actual_period	Date representing the actual period, corresponding to the first day of the period. day: the day itself. week: first day of the corresponding week. month: first day of the corresponding month.	date
*comparison_period	Date representing the comparison period, corresponding to the first day of the period. day: the day itself. week: first day of the corresponding week. month: first day of the corresponding month.	date
*value	Overall variation data between actual_period and comparison_period.	FlightsBookingsOverallVariation

FlightsBookingsOverallVariation

Field	Description	Type
passengers	Passengers count variation.	FlightsBookingsPassengersVariation
days_in_advance	Average days in advance variation.	FlightsBookingsDaysInAdvanceVariation
partition	Group passengers count variation.	Variation

FlightsBookingsPassengersVariation

Field	Description	Type
confirmed	Variation of confirmed (not canceled) passengers.	Variation
canceled	Variation of canceled passengers.	Variation
total	Variation of total passengers.	Variation

Variation

Field	Description	Type	Examples
value	Difference between actual value and comparison value.	decimal	1.12
variation	The explicit variation polarity. It is null when values are not available in both timeframes.	string	POSITIVE NEUTRAL NEGATIVE

FlightsBookingsDaysInAdvanceVariation

Field	Description	Type
booking	Variation of average days in advance of bookings.	Variation
cancellation	Variation of average days in advance of cancellations.	Variation

Variation

Field	Description	Type	Examples
value	Difference between actual value and comparison value.	decimal	1.12
variation	The explicit variation polarity. It is null when values are not available in both timeframes.	string	POSITIVE NEUTRAL NEGATIVE

Variation

Field	Description	Type	Examples
value	Difference between actual value and comparison value.	decimal	1.12
variation	The explicit variation polarity. It is null when values are not available in both timeframes.	string	POSITIVE NEUTRAL NEGATIVE

Value of $.actual,comparison.value.series[*].value.partition

For non-grouped API calls, this value will always be 100.0: since no grouping is taking place, the total is considered as one whole group.

Example

{
    "actual": {
        "timeframe": {
            "from": "2022-02-01",
            "to": "2022-03-31"
        },
        "value": {
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "passengers": {
                            "confirmed": 10419,
                            "canceled": 3476,
                            "total": 13895
                        },
                        "days_in_advance": {
                            "booking": 52.9,
                            "cancellation": 63.4
                        },
                        "partition": 100.0
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "passengers": {
                            "confirmed": 14842,
                            "canceled": 3299,
                            "total": 18141
                        },
                        "days_in_advance": {
                            "booking": 50.3,
                            "cancellation": 58.5
                        },
                        "partition": 100.0
                    }
                }
            ]
        }
    },
    "comparison": {
        "timeframe": {
            "from": "2021-02-01",
            "to": "2021-03-31"
        },
        "value": {
            "series": [
                {
                    "period": "2021-02-01",
                    "value": {
                        "passengers": {
                            "confirmed": 362,
                            "canceled": 461,
                            "total": 823
                        },
                        "days_in_advance": {
                            "booking": 124.6,
                            "cancellation": 82.5
                        },
                        "partition": 100.0
                    }
                },
                {
                    "period": "2021-03-01",
                    "value": {
                        "passengers": {
                            "confirmed": 856,
                            "canceled": 718,
                            "total": 1574
                        },
                        "days_in_advance": {
                            "booking": 76.1,
                            "cancellation": 69.5
                        },
                        "partition": 100.0
                    }
                }
            ]
        }
    },
    "variation": {
        "series": [
            {
                "actual_period": "2022-02-01",
                "comparison_period": "2021-02-01",
                "value": {
                    "passengers": {
                        "confirmed": {
                            "value": 10057,
                            "variation": "POSITIVE"
                        },
                        "canceled": {
                            "value": 3015,
                            "variation": "POSITIVE"
                        },
                        "total": {
                            "value": 13072,
                            "variation": "POSITIVE"
                        }
                    },
                    "days_in_advance": {
                        "booking": {
                            "value": -71.7,
                            "variation": "NEGATIVE"
                        },
                        "cancellation": {
                            "value": -19.1,
                            "variation": "NEGATIVE"
                        }
                    },
                    "partition": {
                        "variation": "NEUTRAL",
                        "value": 0.0
                    }
                }
            },
            {
                "actual_period": "2022-03-01",
                "comparison_period": "2021-03-01",
                "value": {
                    "passengers": {
                        "confirmed": {
                            "value": 13986,
                            "variation": "POSITIVE"
                        },
                        "canceled": {
                            "value": 2581,
                            "variation": "POSITIVE"
                        },
                        "total": {
                            "value": 16567,
                            "variation": "POSITIVE"
                        }
                    },
                    "days_in_advance": {
                        "booking": {
                            "value": -25.8,
                            "variation": "NEGATIVE"
                        },
                        "cancellation": {
                            "value": -11.0,
                            "variation": "NEGATIVE"
                        }
                    },
                    "partition": {
                        "variation": "NEUTRAL",
                        "value": 0.0
                    }
                }
            }
        ]
    }
}