API of affiliate programs booking statistics

Using Travelpayouts API statistics, one can view the data on the bookings made within the affiliate programs the partner is connected to.

To return data upon request, an API token is required. It is available after registering on the Travelpayouts platform and connecting to the Aviasales or Hotelook program. You can find the API token on the Tools tab in the API section.

The token is submitted to the Header of the request in the X-Access-Token parameter.



Please note that API methods use limits, which are described in the article API rate limits.

Working with API, users may set the data to be provided, the period of data collection, data sorting, etc.

Request

First, you can get a list of all available fields and their types to form a request, using the following method:

https://api.travelpayouts.com/statistics/v1/get_fields_list 

All data is divided into raw and aggregated data, by default statistics/v1/get_fields_list returns raw fields. To get aggregated data use data_type GET-parameter.

Example query for raw fields:

https://api.travelpayouts.com/statistics/v1/get_fields_list?data_type=raw 

Example response of raw fields:

{
    "fields": [
       {
            "name": "action_id",
            "type": "string",
            "available_filters": [
                "eq",
                "ne"
           ]
       },
       {
            "name": "action_type",
            "type": "string",
            "available_filters": [
                "eq",
                "ne"
           ],
            "available_values": [
                "booking",
                "paid_click",
                "advertise_profit"
           ]
       },
       {
            "name": "user_device_type",
            "type": "string",
            "available_filters": [
                "eq",
                "ne"
           ]
       }
   ]
}

You can also pass the campaign_id=<id> argument to the query to get additional program-specific fields. For example, for the Aviasales program, you can query https://api.travelpayouts.com/statistics/v1/get_fields_list?campaign_id=100  and then you will get back such fields as airline_code, airline_name, adults, children, and some others.

The ID of the program can be found in the URL of the link to this program page on Travelpayouts. For example, https://www.travelpayouts.com/programs/84/about, where 84 is the ID of the Booking.com program.

Next, the fields returned by get_fields_list are used to send a POST request using the method https://api.travelpayouts.com/statistics/v1/execute_query. The response will contain affiliate program data with the requested ID.

Request parameters

The POST request body shall contain JSON structured in the following way:

  • fields — strings array comprised of the names of fields to be returned (from fields obtained in get_fields_list)
  • filters — filters of the request. Important note: date filter is mandatory. Each filter contains three fields:
    • field — string referring to the field the filter will belong to 
    • op — operation to be conducted (list of available operations is returned by get_fields_list in available_filters) field:
      • eq — equality
      • ne — inequality
      • gt — greater
      • ge — greater than or equal
      • le — lower than or equal
      • lt — lower
      • in — any of the values
        Important: The in operator can only be used with fields that have a filled-in value in available_values (e.g. type and state)
    • value — the value the operation will be applied to (some fields have a predefined set of available values returned by get_fields_list in available_values)
  • sort — sorting of the response
    • field — string referring to the field used as a basis for data sorting in the response
    • order — string referring to the order used as a basis for data sorting in the field:
      • asc — ascending sorting
      • desc — descending sorting
  • offset — offset (0 by default)
  • limit — number of entries (100 by default, maximum — 10,000).

Sample request

{
   "fields": [
       "action_id",
       "external_click_id",
       "sub_id",
       "price_rub",
       "paid_profit_rub",
       "state",
       "date",
       "updated_at"
   ],
   "filters": [
       {
           "field": "type",
           "op": "eq",
           "value": "action"
       },
       {
           "field": "campaign_id",
           "op": "eq",
           "value": 100
       },
       {
          "field": "date",
           "op": "ge",
           "value": "Enter here date and time in the format 2020-01-30"
       }
   ],
   "sort": [
       {
           "field": "date",
           "order": "asc"
       }
   ],
   "offset": 0,
   "limit": 100
}

Sample response

{
   "results": [
       {
           "cancelled_actions_count": 44,
           "redirect_count": 8312,
           "inits_count": 11642,
           "paid_actions_count": 303,
           "paid_profit_eur_sum": "557.37788661",
           "processing_actions_count": 0,
           "processing_profit_eur_sum": "0.00000000000000",
           "searches_count": 48987,
           "user_device_type": "Desktop"
       }
   ],
   "fields": [
       "user_device_type",
       "inits_count",
       "searches_count",
       "redirect_count",
       "processing_actions_count",
       "cancelled_actions_count",
       "paid_actions_count",
      "paid_profit_eur_sum",
       "processing_profit_eur_sum"
   ],
   "filters": [
       {
           "field": "date",
           "op": "ge",
           "value": "2020-12-01"
       },
       {
           "field": "date",
           "op": "le",
           "value": "2020-12-31"
       },
       {
           "field": "campaign_id",
           "op": "eq",
           "value": 100
       }
   ],
   "group": [
       "user_device_type"
   ],
   "offset": 0,
   "limit": 100
}

Response definitions

  • cancelled_actions_count — number of canceled bookings
  • redirect_count — number of clicks on partner tools
  • inits_count — number of widget initializations
  • paid_actions_count — number of paid bookings/orders
  • paid_profit_eur_sum — income obtained, in the selected currency
  • processing_actions_count — number of processing bookings/orders
  • processing_profit_eur_sum — income amount in the selected currently for processing bookings/orders (potential income)
  • searches_count — number of searches
  • user_device_type — the type of device used by users for an action (search, booking or order)
  • filters — filters used
  • group — selected grouping type
  • offset — number of missed database entries
  • limit — number of shown database entries.

Tips for using filters

The speed of query execution depends directly on the set of filters passed. The stricter they are, the faster you will get your data.

The most important filters affecting the speed:

  • date — filter by date. The wider the date range, the slower the query will be executed, try not to specify large ranges unnecessarily.
  • type — event type. If you know exactly what types of data you want to get, you should definitely add this filter
  • state — event status, works only for type = action|referral, if you are requesting data on these types of events and you know exactly what state you need the data in — be sure to add this filter.

Examples of optimal filters for different cases

  • I want to get the number of widget initializations for June 2023.

Here we need a filter by dates and also event type and we are only interested in init:

[{"field":"date","op":"ge","value":"2023-06-01"},{"field":"date","op":"lt","value":"2023-07-01"},{"field":"type","op":"eq","value":"init"}]
  • I want to get the total number of bookings for July 2023.

In this case, it is best to apply a filter by type with the in operator, and include action and referral:

[{"field":"date","op":"ge","value":"2023-07-01"},{"field":"date","op":"lt","value":"2023-08-01"},{"field":"type","op":"in","value":["action", "referral"]}]
  • I want to get the number of paid bookings, not including referral bookings, for August 2023.

Here you need to apply not only a filter by type equal to action, but also a filter by state (we are interested only in paid bookings):

[{"field":"date","op":"ge","value":"2023-08-01"},{"field":"date","op":"lt","value":"2023-09-01"},{"field":"type","op":"eq","value":"action"},{"field":"state","op":"eq","value":"paid"}]
  • I want to get the sum of paid bookings in currency X for August 2023.

We only pay for bookings and referral actions, which means in this case we need a filter by event type equal to action or referral, plus a filter by event state (we are only interested in paid ones). In the end, the filters for this case will be identical to the case above:

[{"field":"date","op":"ge","value":"2023-08-01"},{"field":"date","op":"lt","value":"2023-09-01"},{"field":"type","op":"eq","value":"action"},{"field":"state","op":"eq","value":"paid"}]