API of affiliate programs booking statistics

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

To return data upon a request, a partner token is necessary. It is submitted to all partners at once after registration in the dashboard. A token is submitted to the request Header in X-Access-Token.

Please note, 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.

To obtain the list of all the available fields and their types to form a request, https://api.travelpayouts.com/statistics/v1/get_fields_list is used.

All data can be divided into raw and aggregated, by default statistics/v1/get_fields_list returns raw fields. To obtain aggregated data, use data_type GET-parameter:

aggregated — request aggregated fields;
raw — request raw fields.

Example of raw fields list:

{
    "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"
            ]
        }
    ]
}

Fields returned by get_fields_list are used to send a POST-request using the method https://api.com/statistics/v1/execute_query. Response will contain affiliate program data with the requested ID.

Note: Program ID is provided in a link in the account. For example, https://www.travelpayouts.com/programs/84/about, where 84 is the ID of Booking.com program.

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: created_at needs an obligatory filter. To get metadata about events in programs, add a filter by campaign_id. 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
- 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) field
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).

Request example:

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

Response example:

{
    "results": [
        {
            "cancelled_actions_count": 44,
            "clicks_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",
        "clicks_count",
        "processing_actions_count",
        "cancelled_actions_count",
        "paid_actions_count",
        "paid_profit_eur_sum",
        "processing_profit_eur_sum"
    ],
    "filters": [
        {
            "field": "created_at",
            "op": "ge",
            "value": "2020-12-01 00:00:00"
        },
        {
            "field": "created_at",
            "op": "le",
            "value": "2020-12-31 00:00:00"
        },
        {
            "field": "campaign_id",
            "op": "eq",
            "value": 100
        }
    ],
    "group": [
        "user_device_type"
    ],
    "offset": 0,
    "limit": 100
}

Response field:

cancelled_actions_count — number of cancelled booking/orders
clicks_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 — 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.