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

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

Для получения данных вместе с запросом требуется передавать API токен. Он доступен партнёрам после регистрации на платформе Travelpayouts и подключения к программе Aviasales или Hotelook. Вы сможете найти API токен на вкладке Инструменты в разделе API. 

Токен передаётся в 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.

Пример запроса для raw полей

https://api.travelpayouts.com/statistics/v1/get_fields_list?data_type=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"
      ]
    }
  ]
}

Вы также можете передать в запрос аргумент campaign_id=<id>, чтобы дополнительно получить поля, специфичные для конкретной программы. Например, для программы Aviasales можно выполнить запрос https://api.travelpayouts.com/statistics/v1/get_fields_list?campaign_id=100 и тогда ещё вернутся такие поля, как airline_code, airline_name, adults, children и некоторые другие.

ID программы можно найти в ссылке на её страницу на Travelpayouts: https://app.travelpayouts.com/programs/100/about 

Далее, поля, полученные в 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.

Параметры запроса

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

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

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

{
   "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":"Здесь указать дату в формате 2020-01-30
"
      }
   ],
   "sort":[
      {
         "field":"date",
         "order":"asc"
      }
   ],
   "offset":0,
   "limit":100
}

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

{
  "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": "datet",
      "op": "ge",
      "value": "2020-01-30"
    },
    {
      "field": "date",
      "op": "le",
      "value": "2020-01-30"
    },
    {
      "field": "campaign_id",
      "op": "eq",
      "value": 100
    }
  ],
  "group": [
    "user_device_type"
  ],
  "offset": 0,
  "limit": 100
}

Поля ответа

  • cancelled_actions_count — количество отменённых бронирований/заказов;
  • redirect_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 — количество выводимых записей из базы данных.

Советы по применению фильтров для запроса

Скорость выполнения запроса напрямую зависит от набора переданных фильтров. Чем они строже, тем быстрее вы получите свои данные.

Самые важные фильтры, влияющие на скорость:

  • date — фильтр по дате. Чем шире диапазон дат, тем медленнее выполняется запрос, старайтесь не указывать широкие диапазоны без необходимости.
  • type — тип события. Если вы четко знаете, какого типа данные хотите получить, обязательно добавляйте такой фильтр.
  • state — статус события, работает только для type = action|referral, если вы запрашиваете данные по таким типам событий и точно знаете, в каком статусе данные вам нужны - обязательно добавляйте такой фильтр.

Примеры оптимальных фильтров для разных случаев:

  • Хочу получить число инициализаций виджетов за июнь 2023.

Тут нужен фильтр по типу события и нас интересуют только init:

[{"field":"date","op":"ge","value":"2023-06-01"},{"field":"date","op":"lt","value":"2023-07-01"},{"field":"type","op":"eq","value":"init"}]
  • Хочу получить общее число бронирований за июль 2023.

В этом случае лучше всего применить фильтр по типу события с оператором in, и включить action и referral:

[{"field":"date","op":"ge","value":"2023-07-01"},{"field":"date","op":"lt","value":"2023-08-01"},{"field":"type","op":"in","value":["action", "referral"]}]
  • Хочу получить число оплаченных бронирований, не включая реферальные, за август 2023.

Тут нужно применить не только фильтр по типу события, равный action, но еще и фильтр по состоянию события (нас интересуют только оплаченные):

[{"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"}]
  • Хочу получить сумму оплаченных букингов в валюте X за август 2023.

Мы платим только за бронирования и реферальные действия, а значит в этом случае нужен фильтр по типу события, равный action или referral, плюс фильтр по состоянию события (нас интересуют только оплаченные). В итоге фильтры для этого случая будут идентичны случаю выше:

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