Overall Grouped Compare
Searches Overall Grouped Compare API returns two, time-based searches overall grouped data sets along with a comparative calculation.
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/flights/searches/overall/grouped/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 | ||
| ⓝ *group_type | Field(s) for which perform grouping. | string | origin_countrydestination_citytrip_type | |
| {Comparison SearchesTimeframes} |
Comparison Flights Searches timeframes filter. | Comparison |
One year before correspondent and valued {SearchesTimeframes}. | |
| {Comparison SearchesItinerary} |
Comparison Flights Searches itinerary filter. | Comparison |
Same as correspondent and valued {SearchesItinerary}. | |
| flight_typecompare_flight_type | Filter by flight type. | string | domesticinternational | |
| trip_typecompare_trip_type | Filter by trip type. | string | onewayround_trip | |
| page | Requested page number for paginated results. | int | 1 | |
| page_size | Requested page size for paginated results in the range [1, 100]. | int | 25 |
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. | Comparison |
One year before correspondent and valued {SearchTimeframe}. |
| {Comparison DepartureTimeframe} |
Filter by comparison departure timeframe. | Comparison |
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 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/grouped/compare?search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it&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 Grouped Compare data has been successfully returned. |
Body
FlightsSearchesGroupedComparedOverall
| Field | Description | Type |
|---|---|---|
| *results | Paginated grouped compared searches overall data. | FlightsSearchesGroupedComparedOverallResults |
| paging | Response pagination. | Paging |
FlightsSearchesGroupedComparedOverallResults
| Field | Description | Type |
|---|---|---|
| actual | Searches overall grouped data for the actual timeframe. | FlightsSearchesGroupedComparableOverall |
| comparison | Searches overall grouped data for the comparison timeframe. | FlightsSearchesGroupedComparableOverall |
| variation | Calculated difference between actual and comparison. |
array[FlightsSearchesGroupedOverallVariation] |
FlightsSearchesGroupedComparableOverall
| Field | Description | Type |
|---|---|---|
| timeframe | Reference date range. | FlightsSearchesComparableTimeframe |
| value | Searches overall grouped data for the corresponding timeframe. |
array[FlightsSearchesGroupedOverallElement] |
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 |
FlightsSearchesGroupedOverallElement
| Field | Description | Type |
|---|---|---|
| *group | Group fields values combination for the requested grouping. | array[FlightsGroupElement] |
| *overall | Bookings overall values of the corresponding group. |
FlightsBookingsOverall |
FlightsGroupElement
| Field | Description | Type | Examples |
|---|---|---|---|
| *name | Name that identifies the element in the group. | string | trip_typeflight_type |
| *value | Value of the corresponding element. | string | onewayactive |
FlightsBookingsOverall
| 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 |
FlightsSearchesGroupedOverallVariation
| Field | Description | Type |
|---|---|---|
| *group | Group fields values combination for the requested grouping. | array[FlightsGroupElement] |
| *overall | Searches overall variation for the corresponding group. |
FlightsSearchesOverallVariation |
FlightsGroupElement
| Field | Description | Type | Examples |
|---|---|---|---|
| *name | Name that identifies the element in the group. | string | trip_typeflight_type |
| *value | Value of the corresponding element. | string | onewayactive |
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 |
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": {
"actual": {
"timeframe": {
"search": {
"from": "2022-10-15",
"to": "2023-10-15"
},
"departure": {
"from": "2024-10-15",
"to": "2025-10-15"
}
},
"value": [
{
"group": [
{
"name": "trip_type",
"value": "round_trip"
},
{
"name": "flight_type",
"value": "international"
}
],
"overall": {
"searches": 103757,
"days_in_advance": 40.3,
"length_of_stay": 5.0,
"partition": 50.5
}
},
{
"group": [
{
"name": "trip_type",
"value": "oneway"
},
{
"name": "flight_type",
"value": "international"
}
],
"overall": {
"searches": 101234,
"days_in_advance": 24.3,
"length_of_stay": 3.2,
"partition": 45.8
}
},
{
"group": [
{
"name": "trip_type",
"value": "oneway"
},
{
"name": "flight_type",
"value": "domestic"
}
],
"overall": {
"searches": 10377,
"days_in_advance": 36.7,
"length_of_stay": 4.3,
"partition": 2.1
}
},
{
"group": [
{
"name": "trip_type",
"value": "round_trip"
},
{
"name": "flight_type",
"value": "domestic"
}
],
"overall": {
"searches": 1022,
"days_in_advance": 33.1,
"length_of_stay": 4.9,
"partition": 1.6
}
}
]
},
"comparison": {
"timeframe": {
"search": {
"from": "2021-10-15",
"to": "2022-10-15"
},
"departure": {
"from": "2023-10-15",
"to": "2024-10-15"
}
},
"value": [
{
"group": [
{
"name": "trip_type",
"value": "round_trip"
},
{
"name": "flight_type",
"value": "international"
}
],
"overall": {
"searches": 103757,
"days_in_advance": 40.3,
"length_of_stay": 5.0,
"partition": 37.0
}
},
{
"group": [
{
"name": "trip_type",
"value": "oneway"
},
{
"name": "flight_type",
"value": "international"
}
],
"overall": {
"searches": 101234,
"days_in_advance": 24.3,
"length_of_stay": 3.2,
"partition": 41.0
}
},
{
"group": [
{
"name": "trip_type",
"value": "oneway"
},
{
"name": "flight_type",
"value": "domestic"
}
],
"overall": {
"searches": 10377,
"days_in_advance": 36.7,
"length_of_stay": 4.3,
"partition": 12.0
}
},
{
"group": [
{
"name": "trip_type",
"value": "round_trip"
},
{
"name": "flight_type",
"value": "domestic"
}
],
"overall": {
"searches": 1022,
"days_in_advance": 33.1,
"length_of_stay": 4.9,
"partition": 10.0
}
}
]
},
"variation": [
{
"group": [
{
"name": "trip_type",
"value": "round_trip"
},
{
"name": "flight_type",
"value": "international"
}
],
"compare": {
"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
}
}
},
{
"group": [
{
"name": "trip_type",
"value": "oneway"
},
{
"name": "flight_type",
"value": "international"
}
],
"compare": {
"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
}
}
},
{
"group": [
{
"name": "trip_type",
"value": "oneway"
},
{
"name": "flight_type",
"value": "domestic"
}
],
"compare": {
"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
}
}
},
{
"group": [
{
"name": "trip_type",
"value": "round_trip"
},
{
"name": "flight_type",
"value": "domestic"
}
],
"compare": {
"searches": {
"variation": "POSITIVE",
"value": 3
},
"days_in_advance": {
"variation": "POSITIVE",
"value": 0.2
},
"length_of_stay": {
"variation": "POSITIVE",
"value": 0.1
},
"partition": {
"variation": "NEGATIVE",
"value": -0.1
}
}
}
]
},
"paging": {
"last": "/searches/overall/grouped/compare?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it&group_type=trip_type&group_type=flight_type",
"first": "/searches/overall/grouped/compare?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it&group_type=trip_type&group_type=flight_type",
"prev": null,
"next": null,
"current": "/searches/overall/grouped/compare?page=1&page_size=25&&search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it&group_type=trip_type&group_type=flight_type",
"pages": [
{
"number": 1,
"uri": "/searches/overall/grouped/compare?page=1&page_size=25&search_from=2022-10-15&search_to=2023-10-15&departure_from=2024-10-15&departure_to=2025-10-15&origin_country=it&group_type=trip_type&group_type=flight_type"
}
],
"elements": [
1,
2,
3,
4
],
"total": 4,
"size": 25
}
}