API of affiliate programs 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.

mceclip0.png

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.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. 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).

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": "Здесь указать дату в формате 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.

Was this article helpful?

Have more questions? Submit a request