REST API MGID для заработка

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

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

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

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

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

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

  • GET
  • PUT
  • PATCH
  • POST
  • DELETE

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

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

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

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

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

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

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

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

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

Ответ REST API MGID

В ответ на запрос к 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), которая в общем виде,  выглядет  следующим образом:

{
       "элемент_1":"значение_элемента_1",
       "элемент_2":"значение_элемента_2",
       "элемент_3":       {
               "свойство_1_элемента_3":"значение_свойства_1_элемента_3",
               "свойство_2_элемента_3":               [
                      "значение_1_свойства_2_элемента_3",
                      "значение_2_свойства_2_элемента_3"

         
      ]          
   },
      . . . .
}

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

{
      "errors":      [
              "      [
         _описание_ошибки_
      ]      "         
   ]
}

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

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

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

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

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

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

{
    "token":"_текущий_токен_",
    "refreshToken":"_токен_для_обновления_"
    "idAuth":"_идентификатор_учетной_записи_клиента_"
}

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

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

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

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

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

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

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

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

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

{  
  "_dateInterval_":{  
     "_widgetId_":{  
        "impressions":"_показы_",
        "realImpressions":"_реальные показы_",
        "visibilityRate":"_% показов_",
        "clicks":"_клики_",
        "ctr":"_ctr_",
        "revenue":"_заработок_$_",
        "cpc":"_cpc_¢_",
        "cpm":"_cpm_$_"
     }
  }
}

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

{  
  "_dateInterval_":{  
     "_widgetId_":{  
        "impressions":"_показы_",
        "realImpressions":"_реальные показы_",
        "visibilityRate":"_% показов_",
        "clicks":"_клики_",
        "ctr":"_ctr_"
     }
  }
}

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

Метод GET
URL api.mgid.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 композита

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

{
   " _subid_": {
       "subid":  _subid_,
       "shows": "_показы_",
       "real_shows": "_реальные_показы_",
       "visibility_rate": "_видимость_",
       "clicks": "_клики_",
       "wages": "_заработок_",
       "cpm": "_cpm_",
       "cpc": "_cpc_",
       "ctr": "_ctr_"
   },
   " _subid_": {
       "subid":  _subid_,
       "shows": "_показы_",
       "real_shows": "_реальные_показы_",
       "visibility_rate": "_видимость_",
       "clicks": "_клики_",
       "wages": "_заработок_",
       "cpm": "_cpm_",
       "cpc": "_cpc_",
       "ctr": "_ctr_"
   }
}

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

Метод GET
URL api.mgid.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 композита

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

" _date_": {
       "date":  _date_,
       "shows": "_показы_",
       "real_shows": "_реальные_показы_",
       "visibility_rate": "_видимость_",
       "clicks": "_клики_",
       "wages": "_заработок_",
       "cpm": "_cpm_",
       "cpc": "_cpc_",
       "ctr": "_ctr_"
   }

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

Метод GET
URL api.mgid.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 композита

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

{
    "RU": {                               //код страны в ISO 3166-1
	"shows": "_показы_",
	"real_shows": "_реальные_показы_",
	"visibility_rate": "_показатель_видимости_",
	"clicks": "_к-во_кликов_",
	"wages": "_заработок_",
	"cpm": "_cpm_",
	"cpc": "_cpc_",
	"ctr": "_ctr_"
	}
}

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

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

Метод GET
URL api.mgid.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. Полный список кодов стран можно найти здесь

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

{
    "RU": {                               //код страны в ISO 3166-1
	"shows": "_показы_",
	"real_shows": "_реальные_показы_",
	"visibility_rate": "_показатель_видимости_",
	"clicks": "_к-во_кликов_",
	"wages": "_заработок_",
	"cpm": "_cpm_",
	"cpc": "_cpc_",
	"ctr": "_ctr_"
	}
}

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

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

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

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

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

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

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

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

{
   "_siteId_": {
       "_dateInterval_": {
           "toUsHits": _входящие_клики_,
           "fromUsHits": _исходящие_клики_,
           "exchangeRatio": "_коэффициент_обмена_"
       }
   }
}

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

Метод GET
URL api.mgid.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 [deprecated]
  • realShows [deprecated]
  • pageViews
  • impressions
  • visibilityRate
  • clicks
  • wages
  • cpm
  • vCpm [deprecated]
  • eCpm
  • cpc
  • ctr

 

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