REST API Маркетгид для заработка

Основные положения REST API

REST API Marketgid  позволяет  интегрировать внешние приложения с системой  интернет-рекламы Marketgid.

API дает возможность извлекать, добавлять и изменять данные. Практически   каждым объектом в Marketgid (будь то клиент, рекламная компания, тизер и т.д.) можно  управлять с помощью API.

Запрос  Marketgid REST API – это   HTTP запрос, в котором, с помощью  путей  в URL  задается объект для выполнения действия, а с помощью параметров передаются необходимые данные. Marketgid API является "RESTful Web API".

Параметры запросов являются регистрозависимыми.

API использует  следующие команды REST:

  • GET
  • PUT
  • PATCH
  • POST
  • DELETE

Эти команды соответствуют определенным действия внутри системы Marketgid.

Команда Действие Описание
POST Создать Создание новый элемента (например, тизера)
GET Получить (чтение) Получить элемент или коллекцию  элементов (например, список рекламных кампаний)
PUT Обновить Пересоздать существующий элемент или коллекцию элементов
PATCH Изменить Изменить определенные свойства элемента
DELETE Удалять Удалить элемент или коллекцию элементов (например, переместить тизер в корзину)
Важно! POST и PUT не являются взаимозаменяемыми.

Каждая из команд выполняет свою определенную функцию.

В общем виде запрос выглядит как

http://api.marketgid.com/v1/модуль/контроллер/действие?token= _токен_клиента_&параметр_1=значение_параметра_1& параметр_2=значение_параметра_2&параметр_3=значение_параметра_3....

Идентификация

Для идентификации в REST API Marketgid используется уникальный токен, состоящий из 32 символов и передаваемый в запросе клиента.

Для получения действующего токена  клиент должен воспользоваться специальной функцией API

Каждый запрос, отправленный к REST API Marketgid обязательно  должен содержать токен API.

Ответ REST API Marketgid

В ответ на запрос к REST API сервер  всегда  возвращает HTTP ответ с кодом состояния, зависящего от  результата запроса.

Код ответа Описание
200 OK Запрос был успешно обработан.
400 Bad Request Синтаксическая ошибка
404 Not Found Элемент или страница не найдены

Формат возвращаемых данных

Возвращаемые данные могут быть  в формате  JSON, либо — XML.

По умолчанию используется формат  JSON.

Для задания формата, в котором будут возвращаться данные, используется заголовок запроса. Клиент отсылает заголовок Accept, в котором указывает желаемый формат ответа:

Accept: application/xml

или

Accept: application/json

Описание формата ответа отправляется в ответе в заголовке Content-Type.

Возвращаемые  в ответе данные, представляют собой JSON строку (http://json.org/json-ru.html), которая в общем виде,  выглядет  следующим образом:

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

Работа с клиентами

Получение действующего токена клиента

Метод POST
URL api.marketgid.com/v1/auth/token

Передаваемые параметры:

Параметр Значение
email Адрес электронной почты клиента, указанный при регистрации в системе Marketgid
password Пароль клиента, полученный при регистрации

Возвращаемый ответ:

_текущий_токен_  используется для идентификации  клиента;

_токен_для_обновления_ - будет использован в последующих версиях для обновления просроченного текущего токена.

Работа с информерами

Получение статистики по КИ

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/widgets

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token _токен_клиента_
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
siteId Если указан - выводится статистика только по информерам, связанными с сайтом(ами). Может принимать несколько значений через запятую.
widgetId ID КИ. Если указан - выводится статистика только по указанному информеру(ам). Может принимать несколько значений через запятую.

Возвращаемый ответ:

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

Получение статистики по sub-ids информера КИ

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/widget-sub-ids-stat

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token _токен_клиента_
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
widgetId   ID композита

Возвращаемый ответ:

Получение подневной статистики по каждому sub-id информера КИ

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/widget-sub-id-stat-by-date

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token _токен_клиента_
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
widgetId   ID композита
widgetSubId ID subID композита

Возвращаемый ответ:

Получение статистики в разрезе стран

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/widget-stat-by-countries

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token _токен_клиента_
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
widgetId   ID композита

Возвращаемый ответ:

Полный список кодов стран можно найти здесь

Получение статистики по стране в разрезе дней

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/widget-stat-by-country

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token _токен_клиента_
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
widgetId   ID композита
countryIso Код страны в ISO 3166-1. Полный список кодов стран можно найти здесь

Возвращаемый ответ:

Работа с cайтами

Получение статистики по сайтам

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/sites-stat

Работает только для обмена и внутреннего обмена.

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token _токен_клиента_
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
siteId Если указан - выводится статистика только по указанному сайту. Может принимать несколько значений через запятую.

Возвращаемый ответ:

Пользовательские отчеты

Метод GET
URL api.marketgid.com/v1/publishers/{authId}/widget-custom-report

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token токен клиента
dateInterval Интервал, за который нужно получить статистику. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд. Учитываются временные рамки в 90 дней
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней

Дополнительно можно передать часовые интервалы:

  • startHour - начальный час 0-23
  • endHour - конечный час 0-23
siteId ID сайта клиета
dimensions список полей по которым производить группировку. Может принимать множество значений разделенных запятой. Допустимые значения:

  • date
  • widgetId
  • deviceType
  • subId
  • countryIso
metrics список полей для извлечения показателей. Может принимать множество значений разделенных запятой. Допустимые значения:

  • shows
  • realShows
  • visibilityRate
  • clicks
  • wages
  • cpm
  • vCpm
  • cpc
  • ctr
widgetId ID композитного информера
deviceType тип устройства (desktop, tablet, mobile)
countryIso код страны (alpha2)
sortBy сортировка по полю (может принимать одно из переданых значений dimensions или metrics), если не передан, сортирует по первому параметру из dimensions
sortMethod направление сортировки (asc, desc), если не передан то применяется ASC направление
timeZone Смещение по времени отображаемой статистики в отношении указанной таймзоны. Список доступных таймзон здесь ( TZ )

 

Похожие статьи