Как делать запросы к API CoMagic с помощью Python и зачем это нужно?

11 Марта 2019
Время чтения: 14 минут
logo
5 4 28

Всем привет!

Эта статья будет полезна интернет-маркетологам, которые анализируют данные при помощи Python. Сначала я покажу, как делать запросы к API CoMagic, какие параметры есть в запросах, а в конце рассмотрим небольшой пример экспорта данных в Excel.

Ограничения и получение доступа к API

Для пользователей Data API существует два лимита: ограничение на количество запросов в день и на количество запросов в минуту. Для всех пользователей ограничение количества запросов в день составляет 10000. Превышение этого лимита тарифицируется по 2 копейки за один запрос сверх лимита. Ограничение на количество запросов в минуту составляет 60 запросов. Увеличение числа запросов в минуту тарифицируется по 15 рублей в месяц за увеличение лимита на 1 запрос. Все параметры тарификации запросов и расширения лимитов задаются в разделе "Тарифы и опции" в личном кабинете CoMagic.

По умолчанию доступ к API запрещен всем. Чтобы совершать запросы, необходимо добавить в белый список IP-адрес хоста, с которого происходит запрос. Это делается через личный кабинет "Администратор -> Аккаунт -> Правила и настройки безопасности" вкладка "API".


Начало работы и запрос для получения списка сайтов

Импортируем библиотеки

01
import requests
import json
import pandas as pd
import numpy as np

Создаем переменную с токеном

02
TOKEN = 'y3iv6zsnl2pawsh4co6yk5mua6pzqj1kucra6ade'

Первым методом, который мы вызовем, будет метод get.sites (https://www.comagic.ru/support/api/data-api/site/get_sites/), позволяющий получать список сайтов. Запрос представляет собой POST-запрос с параметрами, передаваемыми в виде JSON-объекта. Давайте рассмотрим, какие параметры запроса нужны для получения сайтов:

  • jsonrpc — указание на то, какая версия протокола jsonrpc используется. Data API использует версию 2, поэтому указываем "2.0",
  • id-идентификатор запроса — это служебная информация, которая поможет потом отсортировать результаты ответов, если вы отправляете несколько запросов с небольшим промежутком времени между ними,
  • method — указание вызываемого метода "get.sites",
  • params — дополнительные параметры запроса:

    access_token — токен доступа (его мы указали выше),

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

    limit — количество строк, возвращаемых в ответе от API.

03

    payload = {
      "jsonrpc":"2.0",
      "id":1,
      "method":"get.sites",
     "params":
    {
    "access_token":TOKEN,
     "offset":0,
     "limit":10000
    }
}
    url = 'https://dataapi.comagic.ru/v2.0'
    r = requests.post(url, data=json.dumps(payload))
    sites = json.loads(r.text)

В ответ от API мы получим json-объект, в котором будут следующие ключи:

04
print(sites.keys())
dict_keys(['id', 'jsonrpc', 'result'])
  • id — это тот же id, который мы указывали в отправленном запросе
  • jsonrpc — версия протокола JSON-rpc
  • result — результат ответа API

Результат ответа API result содержит в себе массив data, в котором будут непосредственно данные отчета, а также объект metadata, в котором будут представлены вспомогательные данные ответа (например, число оставшихся дневных баллов day_remaining, а также полное количество результатов в ответе на запрос total_items).

05
print(sites['result'].keys())
dict_keys(['data', 'metadata'])

06
print(sites['result']['metadata'])
{ 'limits': { 'day_limit': 10000,
'day_remaining': 9976,
'day_reset': 30477,
'minute_limit': 300,
'minute_remaining': 299,
'minute_reset': 57},
'total_items': 42}

Давайте посмотрим один из элементов из результатов:

07
print(sites['result']['data'][0])
{ 'campaign_lifetime': 90,
'connected_integrations': [],
'cookie_lifetime':90,
'creation_date': '2015-07-03 12:29:40',
'default_phone_number': '11111111111',
'default_scenario': {'scenario_id': None, 'scenario_name': None},
'domain_name': 'todolist.ala.se',
'id': 3248,
'industry_id': 1,
'industry_name': 'Авто, мото',
'replacement_dynamical_block_enabled': False,
'sales_enabled': True,
'second_communication_period': 1,
'services_enabled': True,
'show_visitor_id': { 'element_id_value': None,
'enabled': False,
'length_visitor_id': 6,
'message': None},
'site_blocks' [ { 'site_block_id': 1043,
'site_block_name': 'Номер 1 на сайте'}],
'site_key': 'PK4IbnFgSzw6MtPh_k0R5UL9GLDBUzqI',
'target_call_min_duration': 30,
'track_subdomains': 'target_call_min_duration': 30,
True, 'widget_link': {'enabled': False, 'text': None, 'url': None}}

Как видно, каждая строка ответа представляет собой один сайт со всеми параметрами, в числе которых есть сложные параметры, например, массив блоков подмены на сайте site_blocks.

Результаты запроса легко загнать в dataframe с помощью библиотеки pandas:

08
pd.DataFrame(sites['result']['data']).head(10)


Ограничение списка полей в результатах запроса

Скорее всего, в ваших задачах вам нужен будет ограниченный список полей. Чтобы оставить в результатах ответа API только заданные поля, нужно перечислить их в массиве в параметре fields.

09

    payload = {
     "jsonrpc": "2.0",
    "id": 1,
     "method": "get.sites",
     "params":
    {
     "access_token": TOKEN,
     "offset": 0,
     "limit": 10000,
     "fields": ["id","domain_name"]
    }
}
    url =  'https://dataapi.comagic.ru/v2.0'
    r =  requests.post(url, data=json.dumps(payload))
    sites =  json.loads(r.text)
    print(sites['result']['data'])
[ { 'domain_name': 'todolist.ala.se', 'id': 3248},
{ 'domain_name': 'sitedemo.web.dev.test.ru', 'id': 2784},
{ 'domain_name': 'www.testsite.ru', 'id': 2156},
{ 'domain_name': 'siteapp2.webdev.test.ru', 'id': 3242},
{ 'domain_name': 'ok.comagic.ru', 'id': 1023},
{ 'domain_name': 'cetelem.ru', 'id': 4105},
{ 'domain_name': 'app.comagic.ru', 'id': 282},
{ 'domain_name': 'testsvt.ru', 'id': 4077},
{ 'domain_name': 'rts1.ru', 'id': 3606},
{ 'domain_name': 'bubble-test.ru', 'id': 3893},
{ 'domain_name': 'www.sitename.ru', 'id': 3904},
{ 'domain_name': 'www.sitename.ru', 'id': 3922},
{ 'domain_name': 'www.testvoice.io', 'id': 3927},
{ 'domain_name': 'nettest.ru', 'id': 3928},
{ 'domain_name': 'tropic.test-dev.ru', 'id': 3960},
{ 'domain_name': 'comagic.ru', 'id': 103},
{ 'domain_name': 'lettest.ru', 'id': 3999},
{ 'domain_name': 'my-site.ru', 'id': 3908},
{ 'domain_name': 'www.test.ru', 'id': 67},
{ 'domain_name': v'11testtest.comagic.ru', 'id': 3996
}]


Фильтрация в запросе

При использовании get-методов API можно задавать в параметрах фильтр, позволяющий выдать только результаты, соответствующие заданным критериям. API CoMagic обладает очень гибким и мощным механизмом фильтрации. Это позволяет точно задать критерии выбора данных, чтобы эффективнее расходовать лимиты, а также меньше заниматься постобработкой. Примеры того, как задавать критерии фильтрации, можно найти в документации https://www.comagic.ru/support/api/data-api/#_filters. Ниже приведен пример запроса с одним критерием фильтрации, но в дальнейшем в статье будут рассмотрены и более сложные примеры фильтрации.

10

    payload = {
    "jsonrpc":"2.0",
     "id":1,
     "method":"get.sites",
     "params":
    {
     "access_token":TOKEN,
     "offset":0,
    "limit":10000,
     "fields":["id","domain_name"],
      "filter":
        {
    "field":"domain_name",
     "value":"comagic.ru",
     "operator":"="
        }
    }
}
    url = 'https://dataapi.comagic.ru/v2.0'
    r = requests.post(url, data=json.dumps(payload))
    sites = json.loads(r.text)
    print(sites['result']['data'])

[{ 'domain_name': 'comagic.ru', 'id': 103}]

Итак, мы получили id сайта, по которому затем можно получить данные по рекламным кампаниям с помощью метода get.campaigns (https://www.comagic.ru/support/api/data-api/Campaigns/).

11

    payload = {
     "jsonrpc":"2.0",
      "id":1,
     "method":"get.campaigns",
     "params":
    {
    "access_token":TOKEN,
    "offset":0,
     "limit":10000,
     "filter"
        {
    "field":"site_id",
     "value":103,
    "operator":"="
        }
    }
}
    url = 'https://dataapi.comagic.ru/v2.0'
    r = requests.post(url, data=json.dumps(payload))
    campaigns = json.loads(r.text)
    print(campaigns['result']['data'][0])

{ 'campaign_conditions': {},
'cost_ratio': None,
'cost_ratio_operator': None,
'costs': 0.0,
'creation_time': '2017-08-23 17:18:10',
'description': '',
'dynamic_call_tracking': {},
'engin: 4891,
'name': 'Тула Яндекс.Адреса (офис в Туле)',
'site_blocks: [ { 'dynamic_call_tracking_enabled': False,
'phone_number': '74872520482',
'phone_number_id': 13948,
'phone_number_type': 'call_tracking',
'redirection_phone_number': '74959663809',
'redirection_phone_number_id': 831,v 'site_block_id': 783,
'site_block_name': 'Блок 1'}],
'site_domain_name': 'comagic.ru',v 'site_id': 103,
'status': 'active',
'type': 'basic'}

12
pd.DataFrame(campaigns['result']['data'])

Сделаем запрос более точным, указав что нам нужны только интегрированные кампании Яндекс.Директа или Google AdWords, которые сейчас активны, а также зададим список полей, исключив ненужные.

13

    payload = {
     "jsonrpc":"2.0",
     "id":1,
     "method":"get.campaigns",
     "params":
    {
     "access_token":TOKEN,
     "offset":0,
     "limit":10000,
     "fields":["id","name","creation_time","engine","status"],
    "filter":
        {
     "filters":
            [
                {
     "field":"site_id",
      "value":103,
     "operator":"="
                },
                {
    "field":"status",
     "value":"active",
     "operator":"="
                },
                {
     "field":"engine",
    "value":["yandex.direct","google.adwords"],
    "operator":"in"
                }
            ],
    "condition":"and"
        }
    }
}
    url = 'https://dataapi.comagic.ru/v2.0'
    r = requests.post(url, data=json.dumps(payload))
    campaigns = json.loads(r.text)
    print(campaigns['result']['data'])
    pd.DataFrame(campaigns['result']['data'])

[ { 'creation_time': '2017-12-14 10:51:15',
'engine': 'google.adwords',
'id': 4995,
'name': 'Google AdWords.СПБ [интегрированная]',
'status': 'active'},
{ 'creation_time': '2018-04-23 10:39:31',
'engine': 'google.adwords',
'id': 5222,
'name': 'Google AdWords Smarttag [интегрированная]',
'status': 'active'},
{ 'creation_time': '2015-01-13 18:50:37',
'engine': 'google.adwords',
'id': 2358,
'name': 'Google AdWords [интегрированная]',
'status': 'active'},
{ 'creation_time': '2014-12-29 12:49:48',
'engine': 'yandex.direct',
'id': 2355,
'name': 'Яндекс.Директ [интегрированная]',
'status': 'active'},
{ 'creation_time': '2017-12-14 10:49:20',
'engine': 'yandex.direct',
'id': 4994,
'name': 'Яндекс.Директ.СПБ [интегрированная]',
'status': 'active'},
{ 'creation_time': '2018-04-23 10:40:53',
'engine': 'yandex.direct',
'id': 5224,
'name': 'Яндекс.Директ Smarttag [интегрированная]',
'status': 'active'}]

Получим обращения по этим РК с помощью метода get.communications_report https://www.comagic.ru/support/api/data-api/Reports/. Запросы для получения отчетов предусматривают 2 параметра, позволяющих задать временной диапазон получения данных: date_from и date_till.


Получение обращений и выгрузка в Excel

14

    payload = {
     "jsonrpc":"2.0",
     "id":1,
      "method":"get.communications_report",
      "params":
    {
      "access_token":TOKEN,
       "offset":0,
     "limit":10000,
     "date_from": "2019-01-01 00:00:00",
     "date_till": "2019-01-31 23:59:59",
     "filter":
        {
     "filters":
            [
                {
    "field":"site_id",
     "value":103,
      "operator":"="
                },
                {
      "field":"campaign_id",
     "value":[4995,5222,2358,2355,4994,5224],
     "operator":"in"
                },
                {
    "field":"communication_type",
    "value":["call","chat","offline_message"],
     "operator":"in"
                }
            ],
     "condition":"and"
        }
    }
}
    url = 'https://dataapi.comagic.ru/v2.0'
    r = requests.post(url, data=json.dumps(payload))
    communications = json.loads(r.text)


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

15

    print(communications['result']['data'][0])

{ 'campaign_id': 2358,
'communication_type': 'call',
'date_time': '2019-01-02 09:52:37',
'id': 6745877,
'person_id': 6872574,
'site_id': 103,
'visitor_id': 7867164,
'visitor_session_id': 15029956}

Как видно, отчет по умолчанию отображает не так уж много полей, но сам список возможных полей очень обширен (https://www.comagic.ru/support/api/data-api/Reports/). Поэтому делаем больше полей:

16

    payload = {
     "jsonrpc":"2.0",
     "id":1,
     "method":"get.communications_report",
     "params":
    {
     "access_token":TOKEN,
     "offset":0,
     "limit":10000,
     "date_from": "2019-01-01 00:00:00",
     "date_till": "2019-01-31 23:59:59",
    "fields":
        [
     "id",
    "campaign_id",
     "campaign_name",
    "communication_type",
      "date_time",
      "person_id",
    "site_id",
     "site_domain_name",
      "visitor_id",
     "visitor_session_id",
     "communication_number"
        ],
      "filter":
        {
     "filters":
            [
                {
     "field":"site_id",
     "value":103,
     "operator":"="
                },
                {
    "field":"campaign_id",
     "value":[4995,5222,2358,2355,4994,5224],
     "operator":"in"
                },
                {
     "field":"communication_type",
     "value":["call","chat","offline_message"],
     "operator":"in"
                }
            ],
    "condition":"and"
        }
    }
}
    url = 'https://dataapi.comagic.ru/v2.0'
    r = requests.post(url, data=json.dumps(payload))
    communications = json.loads(r.text)
    print(communications['result']['metadata'])

{ 'limits': { 'day_limit': 10000,
'day_remaining': 9986,
'day_reset': 43614,
'minute_limit': 300,
'minute_remaining': 299,
'minute_reset': 54},
'total_items': 447}
17
print(communications['result']['data'][0])
{ 'campaign_id': 2358,
'campaign_name': 'Google AdWords [интегрированная]',
'communication_number': 72,
'communication_type': 'chat',
'date_time': '2019-01-09 11:16:09',
'id': 2298517,
'person_id': 8392572,
'site_domain_name': 'comagic.ru',
'site_id': 103,
'visitor_id': 9387141,
'visitor_session_id': 21913856}

Заведем полученные данные в датафрейм:

18
communications_df = pd.DataFrame(communications['result']['data'])
    communications_df.head(10)

Затем экспортируем полученные данные в Excel-файл

19
communications_df.to_excel('communications.xlsx')

Таким образом, мы получили Excel-файл с обращениями по выбранным рекламным кампаниям:

Мы привели основные примеры скриптов на языке Python и рассмотрели, как формируются запросы к Data API CoMagic. В особенности методы для получения сайтов, рекламных кампаний и списка обращений. Вы можете выгружать эти данные в Excel для дальнейшего анализа в удобной для вас системе.



(9)
4/5
Оцените статью
Поделитесь с друзьями
Вы эксперт в
интернет-маркетинге?

Опубликуйте материал в нашем блоге

Читайте еще по этой теме

CoMagic и Power BI: визуализируй это!

CoMagic и Power BI: визуализируй это!

Время чтения: 6 минут
Анализ посетителей сайта

Анализ посетителей сайта

Время чтения: 9 минут
Содержание:
Будем на связи!