Overall Compare

Searches Overall Compare API returns two different searches overall data sets at once: one defined by the specified {SearchesTimeframes} and {SearchesItinerary} and another defined by {Comparison...} and compare_ prefixed query parameters (or auto-calculated with default values where specified).
Additional comparative data between the two data sets is returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/flights/searches/overall/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
*{SearchesTimeframes}	Flights Searches timeframes filter.	SearchesTimeframes
*{SearchesItinerary}	Flights Searches itinerary filter.	SearchesItinerary
{Comparison SearchesTimeframes}	Comparison Flights Searches timeframes filter.	ComparisonSearchesTimeframes		One year before correspondent and valued {SearchesTimeframes}.
{Comparison SearchesItinerary}	Comparison Flights Searches itinerary filter.	ComparisonSearchesItinerary		Same as correspondent and valued {SearchesItinerary}.
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

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

ComparisonSearchesTimeframes

Name	Description	Type	Default
{Comparison SearchTimeframe}	Filter by comparison search timeframe.	ComparisonSearchTimeframe	One year before correspondent and valued {SearchTimeframe}.
{Comparison DepartureTimeframe}	Filter by comparison departure timeframe.	ComparisonDepartureTimeframe	One year before correspondent and valued {DepartureTimeframe}.

ComparisonSearchTimeframe

Field	Description	Type	Examples
*compare_search_from	Start date of comparison search timeframe.	date	2022-01-01
*compare_search_to	End date of comparison search timeframe.	date	2022-03-31

ComparisonDepartureTimeframe

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

ComparisonSearchesItinerary

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

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/compare?search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Overall Compare data has been successfully returned.

Body

FlightsSearchesComparedOverall

Field	Description	Type
actual	Searches overall data for the actual timeframe.	FlightsSearchesComparableOverall
comparison	Searches overall data for the comparison timeframe.	FlightsSearchesComparableOverall
variation	Calculated difference between `actual` and `comparison`.	FlightsSearchesOverallVariation

FlightsSearchesComparableOverall

Field	Description	Type
timeframe	Reference date ranges.	FlightsSearchesComparableTimeframe
value	Searches overall data for the corresponding `timeframe`.	FlightsSearchesOverall

FlightsSearchesComparableTimeframe

Field	Description	Type
search	Reference search date range.	Timeframe
departure	Reference departure date range.	Timeframe

Timeframe

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

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

FlightsSearchesOverallVariation

Field	Description	Type
searches	Searches count variation.	Variation
days_in_advance	Average days in advance variation.	Variation
length_of_stay	Average length of stay variation.	Variation
partition	Group passengers count variation.	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

Value of $.actual,comparison.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": {
            "search": {
                "from": "2022-10-15",
                "to": "2023-10-15"
            },
            "departure": {
                "from": "2024-10-15",
                "to": "2025-10-15"
            }
        },
        "value": {
            "searches": 103757,
            "days_in_advance":  40.3,
            "length_of_stay": 5.0,
            "partition": 100.0
        }
    },
    "comparison": {
        "timeframe": {
            "search": {
                "from": "2021-10-15",
                "to": "2022-10-15"
            },
            "departure": {
                "from": "2023-10-15",
                "to": "2024-10-15"
            }
        },
        "value": {
            "searches": 103754,
            "days_in_advance":  40.1,
            "length_of_stay": 4.9,
            "partition": 100.0
        }
    },
    "variation": {
        "searches": {
            "variation": "POSITIVE",
            "value": 3
        },
        "days_in_advance": {
            "variation": "POSITIVE",
            "value": 0.2
        },
        "length_of_stay": {
            "variation": "POSITIVE",
            "value": 0.1
        },
        "partition": {
            "variation": "NEUTRAL",
            "value": 0.0
        }
    }
}