Overall Series Grouped

Bookings Overall Series Grouped API returns a time-based bookings overall data series for the specified {BookingsTimeframes} and {IATACodes}, grouped by time unit (period) and other additional fields (group_type).

Request

Endpoint

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

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}	IATA code identifiers.	IATACodes
*period	Time unit of the series.	string	day week month
ⓝ *group_type	Field(s) for which perform grouping.	string	trip_type flight_type
ⓝ departure_country	Filter by country of departure in ISO 3166-1 alpha-2 standard format (in lower case).	string	it
ⓝ arrival_country	Filter by country of arrival in ISO 3166-1 alpha-2 standard format (in lower case).	string	fr
ⓝ cabin_class	Filter by booked cabin class of the flight.	string	economy business first
ⓝ haul	Filter by duration range of the booked flight.	string	short medium long
flight_type	Filter by flight type.	string	domestic international
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	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	Filter by number of passengers that booked the flight. Field value can be filtered using multiple comparison modes: .eq= → = .gt= → > .gte= → ≥ .lt= → < .lte= → ≤	int
page	Requested page number for paginated results.	int		1
page_size	Requested page size for paginated results in the range [1, 100].	int		25

Supported values for period

day
week
month

Supported values for group_type

iata_departure_code
iata_arrival_code
departure_country
arrival_country
cabin_class
haul
flight_type
trip_type
status
stop_days
pax

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/grouped?iata_departure_code=flr&period=month&from=2022-02-01&to=2022-03-31&arrival_from=2022-06-01&arrival_to=2022-07-31&group_type=trip_type&group_type=flight_type' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

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

Body

FlightsBookingsGroupedSeriesOverall

Name	Description	Type
*results	Paginated list of time-based bookings data series grouped by `group_type` requested field(s).	array[FlightsBookingsGroupedSeriesOverallElement]
paging	Response pagination.	Paging

FlightsBookingsGroupedSeriesOverallElement

Field	Description	Type
*group	Group fields values combination for the requested grouping.	array[FlightsGroupElement]
*series	Bookings overall series data of corresponding `group`.	array[FlightsBookingsSeriesOverallElement]

FlightsGroupElement

Field	Description	Type	Examples
*name	Name that identifies the element in the group.	string	trip_type flight_type
*value	Value of the corresponding element.	string	oneway active

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

Paging

Field	Description	Type
last	A relative URI to the last page.	string
first	A relative URI to the first page.	string
prev	A relative URI to the previous page.	string
next	A relative URI to the next page.	string
current	A relative URI to the current page.	string
pages	A set of relative URIs calculated around the current page.	Page
elements	All indexes shown on the current page.	array[int]
total	The number of all elements that API can retrieve.	int
size	The selected page size.	int

Page

Field	Description	Type
number	Number of the page.	int
uri	URI of the page.	string

Example

{
    "results": [
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "round_trip"
                },
                {
                    "name": "flight_type",
                    "value": "international"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "passengers": {
                            "confirmed": 5683,
                            "canceled": 2425,
                            "total": 8108
                        },
                        "days_in_advance": {
                            "booking": 50.9,
                            "cancellation": 67.4
                        },
                        "partition": 54.5
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "passengers": {
                            "confirmed": 7302,
                            "canceled": 2136,
                            "total": 9438
                        },
                        "days_in_advance": {
                            "booking": 48.8,
                            "cancellation": 63.5
                        },
                        "partition": 49.2
                    }
                }
            ]
        },
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "oneway"
                },
                {
                    "name": "flight_type",
                    "value": "international"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "passengers": {
                            "confirmed": 4511,
                            "canceled": 981,
                            "total": 5492
                        },
                        "days_in_advance": {
                            "booking": 53.6,
                            "cancellation": 52.3
                        },
                        "partition": 43.3
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "passengers": {
                            "confirmed": 7088,
                            "canceled": 1073,
                            "total": 8161
                        },
                        "days_in_advance": {
                            "booking": 50.7,
                            "cancellation": 48.8
                        },
                        "partition": 47.8
                    }
                }
            ]
        },
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "oneway"
                },
                {
                    "name": "flight_type",
                    "value": "domestic"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "passengers": {
                            "confirmed": 166,
                            "canceled": 52,
                            "total": 218
                        },
                        "days_in_advance": {
                            "booking": 117.4,
                            "cancellation": 96.5
                        },
                        "partition": 1.6
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "passengers": {
                            "confirmed": 328,
                            "canceled": 54,
                            "total": 382
                        },
                        "days_in_advance": {
                            "booking": 81.0,
                            "cancellation": 53.3
                        },
                        "partition": 2.2
                    }
                }
            ]
        },
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "round_trip"
                },
                {
                    "name": "flight_type",
                    "value": "domestic"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "passengers": {
                            "confirmed": 59,
                            "canceled": 18,
                            "total": 77
                        },
                        "days_in_advance": {
                            "booking": 97.5,
                            "cancellation": 78.0
                        },
                        "partition": 0.6
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "passengers": {
                            "confirmed": 124,
                            "canceled": 36,
                            "total": 160
                        },
                        "days_in_advance": {
                            "booking": 62.9,
                            "cancellation": 65.8
                        },
                        "partition": 0.8
                    }
                }
            ]
        }
    ],
    "paging": {
        "last": "/bookings/overall/series/grouped?page=1&page_size=25&iata_departure_code=flr&period=month&from=2022-02-01&group_type=trip_type&group_type=flight_type&to=2022-03-31",
        "first": "/bookings/overall/series/grouped?page=1&page_size=25&iata_departure_code=flr&period=month&from=2022-02-01&group_type=trip_type&group_type=flight_type&to=2022-03-31",
        "prev": null,
        "next": null,
        "current": "/bookings/overall/series/grouped?page=1&page_size=25&iata_departure_code=flr&period=month&from=2022-02-01&group_type=trip_type&group_type=flight_type&to=2022-03-31",
        "pages": [
            {
                "number": 1,
                "uri": "/bookings/overall/series/grouped?page=1&page_size=25&iata_departure_code=flr&period=month&from=2022-02-01&group_type=trip_type&group_type=flight_type&to=2022-03-31"
            }
        ],
        "elements": [
            1,
            2,
            3,
            4
        ],
        "total": 4,
        "size": 25
    }
}