API статистики бронирований партнёрских программ

С помощью API статистики Travelpayouts можно получить данные по бронированиям, которые были сделаны в рамках партнёрских программ, к которым подключен партнёр.

Для получения данных вместе с запросом требуется передавать партнёрский токен. Он доступен всем партнёрам сразу после регистрации в личном кабинете. Токен передаётся в Header запроса в параметре X-Access-Token.

Обратите внимание, для API запросов существуют лимиты, которые описаны в статье Лимиты при работе с API данных.

При работе с API вы можете задавать какие данные необходимо получить, за какой период, как отсортировать и так далее.

Чтобы получить список всех доступных полей и их типов для формирования запроса, используется метод https://api.travelpayouts.com/statistics/v1/get_fields_list.

Все данные делятся на raw и aggregated, по умолчанию в ответе от statistics/v1/get_fields_list приходят raw поля. Чтобы получить aggregated данные, используйте get-параметр data_type:

aggregated — запросить aggregated поля;
raw — запросить raw поля.

Пример списка raw полей:

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

Поля, полученные в get_fields_list, используются для отправки POST-запроса в методе https://api.travelpayouts.com/statistics/v1/execute_query. Ответ будет содержать данные по партнёрской программе, ID которой указан в запросе.

Примечание: ID программы можно получить из ссылки на неё в личном кабинете. Например, https://www.travelpayouts.com/programs/84/about, где 84 — это ID программы Booking.com.

В теле запроса должен быть JSON, структурированный следующим образом:

fields — массив строк, составленный из названий полей, которые необходимо получить в ответе (из полей, полученных в get_fields_list);
filters — фильтры, применяемые к запросу. Важно: фильтр по created_at является обязательным. Чтобы получить метаданные по событиям в программах, добавьте фильтр по campaign_id. Каждый фильтр состоит из трех полей:
- field — строка, указывающая на поле, к которому будет применяться фильтр;
- op — операция, которая будет применяться (список возможных к применению операций выдается в get_fields_list в поле available_filters):
  - eq — равенство;
  - ne — неравенство;
  - gt — больше;
  - ge — больше, либо равно;
  - le — меньше, либо равно;
  - lt — меньше.
- value — значение, относительно которого будет применяться операция (для некоторых полей существует заранее определенный набор допустимых значений — выдается в get_fields_list в поле available_values).
field — строка, указывающая на поле, по которому мы будем сортировать данные в ответе;
order — строка, указывающая на порядок, в котором мы будем сортировать по этому полю:
- asc — сортировка по возрастанию;
- desc — сортировка по убыванию.
offset — сдвиг (0 по дефолту);
limit — количество записей (100 по дефолту, максимальное — 10 000).

Пример запроса:

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

Пример ответа:

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

Поля ответа:

cancelled_actions_count — количество отменённых бронирований/заказов;
clicks_count — количество кликов по партнёрским инструментам;
inits_count — количество инициализаций виджета;
paid_actions_count — количество оплаченных бронирований/заказов;
paid_profit_eur_sum — полученный доход, в выбранной валюте;
processing_actions_count — количество бронирований/заказов в обработке;
processing_profit_eur_sum — сумма дохода в выбранной валюте по бронированиям/заказам в обработке (потенциальный доход);
searches_count — количество поисков;
user_device_type — тип устройства, с которого пользователь совершил действие (поиск, бронирование, заказ);
filters — применённые фильтры;
group — выбранный способ группировки;
offset — количество пропущенных записей из базы данных;
limit — количество выводимых записей из базы данных.