Overall Series Grouped

Searches Overall Series Grouped API returns a search time-based overall data series for the specified {SearchesTimeframes} and {SearchesItinerary}, grouped by time unit (period) and other additional fields (group_type).

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/flights/searches/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
*{SearchesTimeframes}	Flights Searches timeframes filter.	SearchesTimeframes
*{SearchesItinerary}	Flights Searches itinerary filter.	SearchesItinerary
*period	Time unit of the series.	string	day week month
ⓝ *group_type	Field(s) for which perform grouping.	string	origin_country destination_city trip_type
flight_type	Filter by flight type.	string	domestic international
trip_type	Filter by trip type.	string	oneway round_trip

SearchesTimeframes

Name	Description	Type
{SearchTimeframe}	Filter by search timeframe.	SearchTimeframe
{DepartureTimeframe}	Filter by departure timeframe.	DepartureTimeframe

SearchTimeframe

Timeframe that filters flight searches by search date.

Field	Description	Type	Examples
*search_from	Start date of search timeframe.	date	2022-01-01
*search_to	End date of search timeframe.	date	2022-03-31

DepartureTimeframe

Timeframe that filters flight searches by departure date.

Field	Description	Type	Examples
*departure_from	Start date of departure timeframe.	date	2022-01-01
*departure_to	End date of departure timeframe.	date	2022-03-31

SearchesItinerary

Field	Description	Type	Examples
ⓝ origin_country	Filter by country of origin in ISO 3166-1 alpha-2 standard format (in lower case).	string	it
ⓝ destination_country	Filter by country of destination in ISO 3166-1 alpha-2 standard format (in lower case).	string	fr
ⓝ origin_city	Filter by city of origin in IATA code standard format (in lower case).	string	mil
ⓝ destination_city	Filter by city of destination in IATA code standard format (in lower case).	string	rom

Supported values for period

day
week
month

Supported values for group_type

origin_country
destination_country
origin_city
destination_city
flight_type
trip_type
length_of_stay

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/searches/overall/series/grouped?search_from=2022-10-15&search_to=2023-10-15&origin_country=it&group_type=trip_type&group_type=flight_type&period=month' \
-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

FlightsSearchesGroupedSeriesOverall

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

FlightsSearchesGroupedSeriesOverallElement

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

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

FlightsSearchesSeriesOverallElement

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	Searches overall data of corresponding `period`.	FlightsSearchesOverall

FlightsSearchesOverall

Field	Description	Type
searches	Count of searches performed.	int
days_in_advance	Average number of days elapsed between search date and departure date.	decimal
length_of_stay	Average number of days elapsed between outbound and inbound departure dates for round trip flights.	decimal
partition	Incidence percentage of the group's searches over total searches.	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": {
                        "searches": 103757,
                        "days_in_advance":  40.3,
                        "length_of_stay": 5.0,
                        "partition": 51.5
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "searches": 103857,
                        "days_in_advance":  41.3,
                        "length_of_stay": 5.2,
                        "partition": 51.7
                    }
                }
            ]
        },
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "oneway"
                },
                {
                    "name": "flight_type",
                    "value": "international"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "searches": 101234,
                        "days_in_advance":  24.3,
                        "length_of_stay": 3.2,
                        "partition": 46.0
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "searches": 102234,
                        "days_in_advance":  25.3,
                        "length_of_stay": 3.6,
                        "partition": 46.8
                    }
                }
            ]
        },
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "oneway"
                },
                {
                    "name": "flight_type",
                    "value": "domestic"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "searches": 10377,
                        "days_in_advance":  36.7,
                        "length_of_stay": 4.3,
                        "partition": 1.9
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "searches": 10477,
                        "days_in_advance":  37.7,
                        "length_of_stay": 4.4,
                        "partition": 1.8
                    }
                }
            ]
        },
        {
            "group": [
                {
                    "name": "trip_type",
                    "value": "round_trip"
                },
                {
                    "name": "flight_type",
                    "value": "domestic"
                }
            ],
            "series": [
                {
                    "period": "2022-02-01",
                    "value": {
                        "searches": 1022,
                        "days_in_advance":  33.1,
                        "length_of_stay": 4.9,
                        "partition": 0.6
                    }
                },
                {
                    "period": "2022-03-01",
                    "value": {
                        "searches": 1032,
                        "days_in_advance":  32.1,
                        "length_of_stay": 4.6,
                        "partition": 0.7
                    }
                }
            ]
        }
    ],
    "paging": {
        "last": "/searches/overall/series/grouped?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&origin_country=it&group_type=trip_type&group_type=flight_type",
        "first": "/searches/overall/series/grouped?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&origin_country=it&group_type=trip_type&group_type=flight_type",
        "prev": null,
        "next": null,
        "current": "/searches/overall/series/grouped?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&origin_country=it&group_type=trip_type&group_type=flight_type",
        "pages": [
            {
                "number": 1,
                "uri": "/searches/overall/series/grouped?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&origin_country=it&group_type=trip_type&group_type=flight_type"
            }
        ],
        "elements": [
            1,
            2,
            3,
            4
        ],
        "total": 4,
        "size": 25
    }
}