API Сырых данных

API сырых данных

Шаг 1. Авторизация
Для взаимодействия с API системы используется метод авторизации через токен типа Bearer. Чтобы авторизовать запрос, нужно включить в заголовок Authorization токен в следующем формате: Bearer <авторизационный токен>.
Чтобы получить авторизационный токен, выполните следующие шаги:

Войдите в личный кабинет на сайте.
Перейдите в раздел "Настройки".
Найдите вкладку "API", где и сможете сгенерировать новый токен для авторизации.

Шаг 2. Запрос
Для получения данных о пути конверсии пожалуйста выполните следующие шаги:

Отправьте POST запрос на следующий URL: http://api.targetads.io/v1/reports/raw_reports?project_id=<ваш id проекта>
Убедитесь, что вы заменили <ваш id проекта> на реальный идентификатор вашего проекта в системе.
В теле запроса (BODY) передайте информацию в формате JSON, следуя указанной структуре данных.

{
   "ResponceType": string,
   "Fields": []string,
   "InteractionFilter" InteractionFilter,
   "Offset" int,
   "Limit": int 
}

Offset — при первом запросе данный параметр должен иметь значение 0. Для последующих запросов необходимо увеличивать значение Offset на количество строк, полученных в результате предыдущего запроса. Этот процесс повторяется до тех пор, пока в ответе сервера не будет возвращено 0 строк, что указывает на то, что вы загрузили все доступные данные.

Так как ответ может быть чрезвычайно большим из-за timeout или обрывов соединения, то кол-во строк в ответе может быть меньше чем лимит, поэтому offset необходимо инкрементировать на значение полученных строк.

Параметры поля Fields:

Атрибуты элементов взаимодействия; InteractionType;Тип взаимодействия InteractionTime;Время взаимодействия (UTC +3) InteractionUserID;Переданный user_id взаимодействия InteractionCustomParams;Переданные параметры взаимодействия InteractionDate;Дата взаимодействия InteractionUrlPath;URL взаимодействия InteractionReferer;Referer взаимодействия InteractionUtmSource;utm_source InteractionUtmMedium;utm_medium InteractionUtmCampaign;utm_campaign InteractionUtmContent;utm_content InteractionUtmTerm;utm_term InteractionYaMetrikaId;ID Yandex метрики InteractionGAId;ID Google Analytics InteractionDeviceType;Тип устройства взаимодейтсвия InteractionOsName;Операционная система взаимодействия InteractionBrowserName;Браузер взаимодействия InteractionAppId;ID приложения InteractionMediaCampaignName;Медиа кампания InteractionMediaPlacementName;Медиа креатив InteractionDomain;Домен взаимодействия InteractionDeviceID;ID устройства в системе TA InteractionMobileDeviceID;IDFA/GAID InteractionDate;Дата взаимодействия (UTC +3) InteractionCountry;Страна InteractionCity;Город InteractionBrowserVersion;Версия браузера InteractionOsVersion;Версия ОС InteractionDeviceType;Тип устройства InteractionUserAgent;User Agent InteractionMediaSourceName;Медиа источник InteractionSSP;SSP InteractionIP;IP адрес InteractionTargetEventType;Тип целевого события InteractionTargetEventCategory;Категория целевого события InteractionTargetEventName;Имя целевого события InteractionTargetEventValue;Ценность целевого события InteractionEcomId;ID продажи InteractionEcomAmount;Сумма продажи InteractionEcomQuantity;Кол-во проданных товаров InteractionEcomItemsId;Массив ID купленных товаров InteractionEcomItemsName;Массив названий купленных товаров InteractionEcomItemsBrand;Массив брендов купленных товаров InteractionEcomItemsCategory1;Массив 1 категории купленных товаров InteractionEcomItemsCategory2;Массив 2 категории купленных товаров InteractionEcomItemsVariant;Массив вариантов купленных товаров InteractionEcomItemsPrice;Массив цен купленных товаров InteractionEcomItemsQuantity;Массив кол-во купленных товаров

Описание объекта Interaction Filter
Объект позволяет отфильтровать события взаимодействия, которые нужно получить в ответе

Параметры DateFrom и DateTo обязательны к передаче

Фильтры применяются по условию "И"

Значения типов взаимодействий
Impression - показы медиа рекламы
PageView - просмотры страниц сайта
Session - сессии на сайте (может быть выбран либо режим сессии, либо просмотра страниц)
Event - отправленное событие на сайте
AddToCart - события добавления в корзину
Purchase - событие покупки

Пример запроса (показы медиа рекламы):

{
    "ResponseType": "JSON",
    "Fields": [
       "InteractionType", 
        "InteractionTime", 
        "InteractionDeviceID", 
        "InteractionMobileDeviceID", 
         "InteractionDate",
	"InteractionCustomParams",
	"InteractionDomain",
	"InteractionCountry",
	"InteractionCity",
	"InteractionBrowserName",
	"InteractionBrowserVersion",
	"InteractionOsName",
	"InteractionOsVersion",
	"InteractionDeviceType",
	"InteractionUserAgent",
	"InteractionMediaSourceName",
	"InteractionMediaCampaignName",
	"InteractionMediaPlacementName",
	"InteractionSSP",
	"InteractionIP"
    ],
    "InteractionFilter": {
        "DateFrom": "2024-10-01",
        "DateTo": "2024-12-02",
        "InteractionType": ["Impression"],
        "MediaCampaignId": [1, 2, 3]
    },
    "Offset": 5000, 
    "Limit": 5000
}

Пример запроса (сессии и целевые действия на сайте):

{
    "ResponseType": "JSON",
    "Fields": [
       "InteractionType", "InteractionTime", "InteractionDeviceID", 
        "InteractionMobileDeviceID", "InteractionDate",
	"InteractionUserID",
	"InteractionCustomParams",
	"InteractionDomain",
	"InteractionUrlPath",
	"InteractionReferer",
	"InteractionUtmSource",
	"InteractionUtmMedium",
	"InteractionUtmCampaign",
	"InteractionUtmContent",
	"InteractionUtmTerm",
	"InteractionYaMetrikaId",
	"InteractionGAId",
	"InteractionCountry",
	"InteractionCity",
	"InteractionBrowserName",
	"InteractionBrowserVersion",
	"InteractionOsName",
	"InteractionOsVersion",
	"InteractionDeviceType",
	"InteractionUserAgent",
	"InteractionIP",

	"InteractionTargetEventType",
	"InteractionTargetEventCategory",
	"InteractionTargetEventName",
	"InteractionTargetEventValue",

	"InteractionEcomId",
	"InteractionEcomAmount",

	"InteractionEcomQuantity",
	"InteractionEcomItemsId",
	"InteractionEcomItemsName",
	"InteractionEcomItemsBrand",

	"InteractionEcomItemsCategory1",
	"InteractionEcomItemsCategory2",
	"InteractionEcomItemsVariant",
	"InteractionEcomItemsPrice",
	"InteractionEcomItemsQuantity"
    ],
    "InteractionFilter": {
        "DateFrom": "2024-10-01",
        "DateTo": "2024-12-02",
        "InteractionType": ["Session", "Event", "AddToCart", "Purchase"],
    },
    "Offset": 0, 
    "Limit": 10000
}

Важно: ответ может быть большим и достигать сотен мегабайт в рамках установленного лимита. Используйте для запроса только те поля, которые вам действительно необходимы.

Ответы
В случае успешного ответа отправляется код ответа 200 и JSON следующего вида:

Пример ответа (показы):

{
    "Columns": [
        "InteractionType",
        "InteractionTime",
        "InteractionDeviceID",
        "InteractionDate",
        "InteractionCustomParams",
        "InteractionDomain",
        "InteractionCountry",
        "InteractionCity",
        "InteractionBrowserName",
        "InteractionBrowserVersion",
        "InteractionOsName",
        "InteractionOsVersion",
        "InteractionDeviceType",
        "InteractionUserAgent",
        "InteractionMediaSourceName",
        "InteractionMediaCampaignName",
        "InteractionMediaPlacementName",
        "InteractionSSP",
        "InteractionIP"
    ],
    "Rows": [
        [
            "Impression",
            "2024-10-05 01:19:47",
            "14886759351289802407",
            "2024-10-05",
            "{'banner':'300x250_v2','group':'66fd4fdf4d506e4430ef5682'}",
            "hayao-miyadzaki-lordfilm.ru",
            "Россия",
            "Видное",
            "Chrome",
            "129.0.0.0",
            "Android",
            "10",
            "mobile",
            "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36",
            "hybrid",
            "hybrid_banners",
            "sept24_18_25",
            "between",
            "31.185.7.66"
        ],
        [
            "Impression",
            "2024-10-05 01:19:48",
            "10535289285631773198",
            "2024-10-05",
            "{'banner':'300x250_v4','group':'66fd4fdf4d506e4430ef5682'}",
            "wifigid.ru",
            "Россия",
            "Москва",
            "Chrome",
            "129.0.0.0",
            "Android",
            "10",
            "mobile",
            "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36",
            "hybrid",
            "hybrid_banners",
            "sept24_18_25_msk",
            "vox",
            "213.87.133.151"
        ],
        [
            "Impression",
            "2024-10-05 01:19:49",
            "13079985877589116264",
            "2024-10-05",
            "{'banner':'240х400-1_white','group':'66fd4fdf4d506e4430ef5682'}",
            "e.mail.ru",
            "Россия",
            "Реутов",
            "Chrome",
            "129.0.0.0",
            "Windows",
            "10.0",
            "desktop",
            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
            "hybrid",
            "hybrid_banners",
            "sept24_18_25",
            "yandexortb",
            "193.169.5.190"
        ]
    ],
    "CountRows": 3
}

Каждая строка в ответе — это взаимодействие с пользователем и его атрибуты. Объединять разные типы взаимодействия можно по полю InteractionDeviceID

В случае возникновения ошибки в ответе могут быть представлены следующие коды:

400 код означает, что была допущена ошибка в параметрах запроса.
429 код указывает на превышение лимита числа запросов.
500 код свидетельствует о наличии внутренней серверной ошибки.

У API установлены лимиты на ID проекта: 20 запросов за 60 секунд. Это ограничение связано с возможным большим объемом данных, передаваемым в ответе.

В ответе также передаются заголовки вязанные с лимитами:

Перейти к созданию источника в Target Ads

Давай настроим источник, чтобы все корректно работало.