Skip to content

Overall Series Compare

Searches Overall Series Compare API returns two, search time-based overall data series 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 time-based data series between the two data series are returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/flights/searches/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
*{SearchesTimeframes} Flights Searches timeframes filter. SearchesTimeframes
*{SearchesItinerary} Flights Searches itinerary filter. SearchesItinerary
*period Time unit of the series. string day
week
month
{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 period
  • day
  • week
  • month
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/compare?search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it&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

FlightsSearchesComparedSeriesOverall

Field Description Type
actual Searches overall data for the actual timeframe. FlightsSearchesComparableSeriesOverall
comparison Searches overall data for the comparison timeframe. FlightsSearchesComparableSeriesOverall
variation Calculated difference between actual and comparison. FlightsSearchesSeriesOverallVariation
FlightsSearchesComparableSeriesOverall
Field Description Type
timeframe Reference date range. FlightsSearchesComparableTimeframe
value Searches overall data series for the corresponding timeframe. FlightsSearchesSeriesOverall
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
FlightsSearchesSeriesOverall
Field Description Type
series Searches overall series data for the requested period. array[FlightsSearchesSeriesOverallElement]
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
FlightsSearchesSeriesOverallVariation
Field Description Type
series Searches overall data series for the requested timeframe and period. array[FlightsSearchesSeriesOverallVariationElement]
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. FlightsSearchesOverallVariation
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.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": {
            "search": {
                "from": "2022-10-15",
                "to": "2023-10-15"
            },
            "departure": {
                "from": "2024-10-15",
                "to": "2025-10-15"
            }
        },
        "value": {
            "series": [
                {
                    "period": "2022-10-01",
                    "value": {
                        "searches": 103757,
                        "days_in_advance":  40.3,
                        "length_of_stay": 5.0,
                        "partition": 100.0
                    }
                },
                {
                    "period": "2022-11-01",
                    "value": {
                        "searches": 103758,
                        "days_in_advance":  40.4,
                        "length_of_stay": 5.1,
                        "partition": 100.0
                    }
                }
            ]
        }
    },
    "comparison": {
        "timeframe": {
            "search": {
                "from": "2021-10-15",
                "to": "2022-10-15"
            },
            "departure": {
                "from": "2023-10-15",
                "to": "2024-10-15"
            }
        },
        "value": {
            "series": [
                {
                    "period": "2021-10-01",
                    "value": {
                        "searches": 103757,
                        "days_in_advance":  40.3,
                        "length_of_stay": 5.0,
                        "partition": 100.0
                    }
                },
                {
                    "period": "2021-11-01",
                    "value": {
                        "searches": 101234,
                        "days_in_advance":  24.3,
                        "length_of_stay": 3.2,
                        "partition": 100.0
                    }
                }
            ]
        }
    },
    "variation": {
        "series": [
            {
                "actual_period": "2022-10-01",
                "comparison_period": "2021-10-01",
                "value": {
                     "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
                    }
                }
            },
            {
                "actual_period": "2022-11-01",
                "comparison_period": "2021-11-01",
                "value": {
                    "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
                    }
                }
            }
        ]
    }
}