Skip to content

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