REST API
Содержание
- 1 Access-токен для OAuth2
- 2 Истечение срока действия access-токена
- 3 Получение списков рекламодателей для аккаунта агентства
- 4 Получение рекламных кампаний
- 5 Получение баннеров по указанной рекламной кампании
- 6 Получение статистики рекламного агентства
- 7 Получение статистики рекламодателя
- 8 Получение статистики кампании
- 9 Получение статистики баннера
- 10 Получение статистики ssp
Access-токен для OAuth2
Для аутентификации и авторизации в API используется протокол OAuth2 по схеме Client Credentials Grant.
Эта схема протокола OAuth2 позволяет пользователю взаимодействовать с API напрямую. Для пользователя создаётся клиент с параметрами client_id и client_secret, пользуясь которыми он сам получает access-токен для аутентификации в API.
clinetId и clientSecret вы можете получить оставив нам заявку.
При grant_type=client_credentials метод создаёт новый access-токен по паре client_id, client_secret, получаемой при регистрации OAuth-клиента.
Это реализация схемы Client Credentials Grant протокола OAuth2.
Запрос
POST /token HTTP/2
Host: https://api.hybrid.ru
Content-Type: application/x-www-form-urlencoded
- grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
- grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&advertiserId={advertiserId} - сгенерировать токен от имени агенства для рекламного аккаунта.
При grant_type=refresh_token метод создаёт новый access-токен взамен старого, который идентифицируется переданным параметром refresh_token.
В случае, если вызов осуществляется от агентского аккаунта вы можете сгенерировать токен для своего рекламодлателя передав дополнительный параметр в теле запроса (2).
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token": "{access_token}",
"token_type": "bearer",
"scope": "{scope}",
"expires_in": "86400",
"refresh_token": "{refresh_token}"
}
Истечение срока действия access-токена
Каждый полученный access-токен является действительным в течение суток. На это указывает свойство expires_in в ответе на запрос access-токена. Там же указывается refresh_token — специальный токен для получения нового access-токена. За это отвечает схема Refreshing an Access Token в протоколе OAuth2.
Запрос
POST /token HTTP/2
Host: https://api.hybrid.ru
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token": "{new_access_token}",
"token_type": "bearer",
"expires_in": "86400",
"refresh_token": "{refresh_token}"
}
Получение списков рекламодателей для аккаунта агентства
Для получения списка рекламодателей вашего агентства вам необходмо сгенерировать токен из предыдущего заголовка под пунктом 1. Затем с помощью этого токена вам необходимо запросить список ваших рекламодателей:
Запрос
GET /v2.0/agency/ HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
В ответ вы получите массив объектов c полями:
- id - идентификатор рекламодателя
- name - название рекламодателя
Пример ответа:
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"Id": "53df8633af55cd57805746f5",
"Name": "Advertiser 1"
},
{
"Id": "54f74d70870a8e44a023ghj5",
"Name": "Advertiser 2"
},
{
"Id": "5593b2ab9341f9b09819dq45",
"Name": "Advertiser 3"
}
]
После получения списка рекламодателей вы можете запросить токен для отдельного рекламодателя (1) и осуществлять с его помощью все вызовы к api.
Получение рекламных кампаний
GET /v2.0/advertiser/{advertiserId} HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
- advertiserId - идентификатор рекламодателя
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"Id": "53df8633af55cd57805746f5",
"Name": "Campaign 1"
},
{
"Id": "54f74d70870a8e44a023ghj5",
"Name": "Campaign 2"
},
{
"Id": "5593b2ab9341f9b09819dq45",
"Name": "Campaign 3"
}
]
Получение баннеров по указанной рекламной кампании
Запрос
GET /v2.0/campaign/{campaignId} HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
где campaign_id - идентификатор рекламной кампании.
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"Id": "58c1598f7bc72f277c4744ec",
"Name": "Banner 1"
},
{
"Id": "58c1598f7bc72f277c474408",
"Name": "Banner 2"
},
{
"Id": "58c1598f7bc72f277c474424",
"Name": "Banner 3"
},
{
"Id": "58c1598f7bc72f277c474440",
"Name": "Banner 4"
}
]
Получение статистики рекламного агентства
Запрос
GET v2.0/agency/{split}?from={from}&to={to}&page={page}&limit={limit}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
- Параметры
- split - срез статистики
- os - операционные системы
- device - устройства
- ssp
- month - месяцы
- day - дни
- hour - часы
- country - страны
- region - регионы
- advertiser - рекламодатели
- campaign - кампании
- banner - баннеры
- bannersize - размеры баннеров
- utm - utm метки
- from - нижний порог даты статистики (обязательный параметр)
- to - верхний порог даты статистики (обязательный параметр)
- page - номер страницы начиная с 0 (по умолчанию 0)
- limit - количество строк на странице (по умолчанию 100)
Дату необходимо передавать в формате ISO-8601.
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"Statisitic": [
{
"Device": "Unknown",
"ClickCount": 527,
"ImpressionCount": 5909,
"Reach": 3758,
"Frequence": 1.5723789249600852,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 65.9121155297415
},
{
"Device": "Desktop",
"ClickCount": 1951,
"ImpressionCount": 855180,
"Reach": 592994,
"Frequence": 1.4421393808369056,
"Install": 0,
"PostClickConversionsCount": 5,
"PostViewConversionsCount": 104,
"Cost": 12821.089281889
},
{
"Device": "Mobile",
"ClickCount": 834,
"ImpressionCount": 411352,
"Reach": 316451,
"Frequence": 1.2998916103914981,
"Install": 0,
"PostClickConversionsCount": 40,
"PostViewConversionsCount": 8,
"Cost": 5062.60356450518
},
{
"Device": "Tablet",
"ClickCount": 211,
"ImpressionCount": 119425,
"Reach": 81358,
"Frequence": 1.4678949826691905,
"Install": 0,
"PostClickConversionsCount": 20,
"PostViewConversionsCount": 8,
"Cost": 1342.02392719788
}
],
"Total": {
"ClickCount": 3523,
"ImpressionCount": 1391866,
"Reach": 992371,
"Frequence": 1.4025661773671339,
"Install": 0,
"PostClickConversionsCount": 65,
"PostViewConversionsCount": 120,
"Cost": 19291.6288891218
}
}
Получение статистики рекламодателя
Запрос
GET v2.0/advertiser/{split}?from={from}&to={to}&page={page}&limit={limit}&id={id}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
- Параметры
- split - срез статистики
- os - операционные системы
- device - устройства
- ssp
- month - месяцы
- day - дни
- hour - часы
- country - страны
- region - регионы
- campaign - кампании
- banner - баннеры
- bannersize - размеры баннеров
- utm - utm метки
- from - нижний порог даты статистики (обязательный параметр)
- to - верхний порог даты статистики (обязательный параметр)
- page - номер страницы начиная с 0 (по умолчанию 0)
- limit - количество строк на странице (по умолчанию 100)
- id - идентификатор рекламодателя
Дату необходимо передавать в формате ISO-8601.
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"Statisitic": [
{
"Os": "Unknown",
"ClickCount": 57,
"ImpressionCount": 1,
"Reach": 1,
"Frequence": 1,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
},
{
"Os": "Android",
"ClickCount": 11,
"ImpressionCount": 1712,
"Reach": 1052,
"Frequence": 1.6273764258555132,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 75.1080443749507
},
{
"Os": "Ios",
"ClickCount": 0,
"ImpressionCount": 524,
"Reach": 281,
"Frequence": 1.8647686832740213,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 13.273988726932
},
{
"Os": "Linux",
"ClickCount": 0,
"ImpressionCount": 21,
"Reach": 19,
"Frequence": 1.105263157894737,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0.257097037557959
},
{
"Os": "Windows",
"ClickCount": 7,
"ImpressionCount": 5711,
"Reach": 4129,
"Frequence": 1.383143618309518,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 42.4643435702017
}
],
"Total": {
"ClickCount": 75,
"ImpressionCount": 7969,
"Reach": 5482,
"Frequence": 1.4536665450565487,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 131.103473709642
}
}
Получение статистики кампании
Запрос
GET v2.0/campaign/{split}?from={from}&to={to}&page={page}&limit={limit}&id={id}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
- Параметры
- split - срез статистики
- os - операционные системы
- device - устройства
- ssp
- month - месяцы
- day - дни
- hour - часы
- country - страны
- region - регионы
- banner - баннеры
- bannersize - размеры баннеров
- utm - utm метки
- from - нижний порог даты статистики (обязательный параметр)
- to - верхний порог даты статистики (обязательный параметр)
- page - номер страницы начиная с 0 (по умолчанию 0)
- limit - количество строк на странице (по умолчанию 100)
- id - идентификатор кампании
Дату необходимо передавать в формате ISO-8601.
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"Statisitic": [
{
"Banner": "58b54fce7bc72f21ac0f6125",
"ClickCount": 57,
"ImpressionCount": 500,
"Reach": 410,
"Frequence": 0,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
},
{
"Banner": "52b54fce7bc72f21ac0f6335",
"ClickCount": 60,
"ImpressionCount": 500,
"Reach": 410,
"Frequence": 0,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
}
],
"Total": {
"ClickCount": 117,
"ImpressionCount": 1000,
"Reach": 820,
"Frequence": 0,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
}
}
Получение статистики баннера
Запрос
GET v2.0/banner/{split}?from={from}&to={to}&page={page}&limit={limit}&id={id}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
- Параметры
- split - срез статистики
- os - операционные системы
- device - устройства
- ssp
- month - месяцы
- day - дни
- hour - часы
- country - страны
- region - регионы
- bannersize - размеры баннера
- utm - utm метки
- from - нижний порог даты статистики (обязательный параметр)
- to - верхний порог даты статистики (обязательный параметр)
- page - номер страницы начиная с 0 (по умолчанию 0)
- limit - количество строк на странице (по умолчанию 100)
- id - идентификатор баннера
Дату необходимо передавать в формате ISO-8601.
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"Statisitic": [
{
"Date": "2017-03-01T00:00:00",
"ClickCount": 28,
"ImpressionCount": 90,
"Reach": 80,
"Frequence": 0,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
},
{
"Date": "2017-03-02T00:00:00",
"ClickCount": 29,
"ImpressionCount": 100,
"Reach": 82,
"Frequence": 0,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
}
],
"Total": {
"ClickCount": 57,
"ImpressionCount": 190,
"Reach": 160,
"Frequence": 0,
"Install": 0,
"PostClickConversionsCount": 0,
"PostViewConversionsCount": 0,
"Cost": 0
}
}
Получение статистики ssp
Запрос
GET v2.0/ssp?from={from}&to={to}
HTTP/2
Host: https://api.hybrid.ru
Authorization: Bearer {access_token}
- Параметры
- from - нижний порог даты статистики (обязательный параметр)
- to - верхний порог даты статистики (обязательный параметр)
Дату необходимо передавать в формате ISO-8601.
Пример ответа
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"Statisitic": [
{
"Day": "2017-03-01T00:00:00",
"WinCount": 0,
"ClickCount": 147,
"ImpressionCount": 152082,
"StartEventsCount": 0,
"SkipEventCount": 0,
"UnmuteEventCount": 0,
"MuteEvenCount": 0,
"PauseEventCount": 0,
"RewindEventCount": 0,
"FullscreenEventCount": 0,
"CollapseEventCount": 0,
"FirstQuartileEventCount": 0,
"MidpointEventCount": 0,
"ThirdQuartileEventCount": 0,
"CompleteEventCount": 0,
"ResumeEventCount": 0,
"ExpandEventCount": 0,
"AcceptInvitationEventCount": 0,
"CloseEventCount": 0,
"Cost": 1154.38055297814
},
{
"Day": "2017-03-02T00:00:00",
"WinCount": 0,
"ClickCount": 159,
"ImpressionCount": 207508,
"StartEventsCount": 0,
"SkipEventCount": 0,
"UnmuteEventCount": 0,
"MuteEvenCount": 0,
"PauseEventCount": 0,
"RewindEventCount": 0,
"FullscreenEventCount": 0,
"CollapseEventCount": 0,
"FirstQuartileEventCount": 0,
"MidpointEventCount": 0,
"ThirdQuartileEventCount": 0,
"CompleteEventCount": 0,
"ResumeEventCount": 0,
"ExpandEventCount": 0,
"AcceptInvitationEventCount": 0,
"CloseEventCount": 0,
"Cost": 1725.49061265143
}
],
"Total": {
"Day": "0001-01-01T00:00:00",
"WinCount": 0,
"ClickCount": 306,
"ImpressionCount": 359590,
"StartEventsCount": 0,
"SkipEventCount": 0,
"UnmuteEventCount": 0,
"MuteEvenCount": 0,
"PauseEventCount": 0,
"RewindEventCount": 0,
"FullscreenEventCount": 0,
"CollapseEventCount": 0,
"FirstQuartileEventCount": 0,
"MidpointEventCount": 0,
"ThirdQuartileEventCount": 0,
"CompleteEventCount": 0,
"ResumeEventCount": 0,
"ExpandEventCount": 0,
"AcceptInvitationEventCount": 0,
"CloseEventCount": 0,
"Cost": 2879.87116562957
}
}