API Description

API для анализа конкурентов

Добавление конкурента в проект

Метод позволяет добавить сайт конкурента в проект для отслеживания позиций.

Параметры

Имя	Обязательный	Описание
site_id	Да	Уникальный идентификатор проекта
url	Да	URL сайта конкурента
name	Нет	Имя сайта конкурента (если не указать, будет использован url)
subdomain_match	Нет	Учитывать сабдомены (1 – да , 0 – нет)

Формат запроса

Title of the code block

Copy

POST /competitors

{

site_id : 1,

name : "name",

url : "https://site.test.com/"

}

Результат

В случае успеха сервер возвращает HTTP 201 и id добавленного конкурента.

Имя	Обязательный	Описание
id	Да	Уникальный идентификатор добавленного конкурента в проект

Пример ответа

Title of the code block

Copy

{

"id": 123456

}

Ошибки

HTTP-код	Сообщение об ошибке
400	Invalid site url

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

Метод позволяет получить список всех конкурентов добавленных в проект.

Формат запроса

Title of the code block

Copy

GET /competitors/site/{site_id}

Результат

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

Имя	Обязательный	Описание
id	Да	ID конкурента
name	Да	Название конкурента
url	Да	URL конкурента

Пример ответа

Title of the code block

Copy

[

    {

        "id": 1,

        "name": "competitor1.com",

        "url": "competitor1.com",

    },

    {

        "id": 2,

        "name": "competitor2.com",

        "url": "https://competitor2.com/",

    },

    {

        "id": 3,

        "name": "competitor3.com",

        "url": "https://competitor3.com",

    }

]

Позиции по ключевым словам конкурентов

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

Формат запроса

Title of the code block

Copy

GET /competitors/{competitor_id}/positions?date_from=2018-07-25&date_to=2018-07-25&site_engine_id=1

Query-параметры запроса

Имя	Обязательный	Тип	Описание
date_from	Нет	yyyy-mm-dd	Дата начала периода (по умолчанию – сегодня минус неделя)
date_to	Нет	yyyy-mm-dd	Дата конца периода (по умолчанию – сегодня)
site_engine_id	Нет	yyyy-mm-dd	ID поисковой системы, для которой надо получить статистику.
with_serp_features	Нет		Специальные элементы поисковой выдачи Google, найденные в результатах поиска по ключевому слову

Результат

В случае успеха сервер возвращает массив со статистикой позиций по ключевым словам конкурента, добавленного в проект. Возвращает максимум 300000 записей позиций (positions).

Имя	Описание
id	ID ключевого слова, добавленного в проект
position	Массив позиций, содержащий статистику позиций по ключевым словам конкурента
date	Дата проверки позиций по ключевым словам
change	Изменение позиции по сравнению с предыдущей датой (может быть отрицательное) из выбранного периода. Если выбран период один день change будет равно 0
pos	Текущая позиция

Пример ответа

Title of the code block

Copy

[

    {

        "site_engine_id": 123,

        "keywords":[

            {

                "id": "123",

                "positions":[

                    {

                        "date": "2018-07-25",

                        "pos": 7,

                        "change": 1

                    }

                ]

            }

        ],

        "name": null,

        "volume": null

    },

...

]

Ошибки

HTTP-код	Сообщение об ошибке
400	Invalid site_engine_id
404	Incorrect competitor id

Удаление конкурента из проекта

Метод позволяет удалить сайт конкурента из проекта пользователя.

Формат запроса

Title of the code block

Copy

DELETE /competitors/{competitor_id}

Результат

В случае успеха сервер вернет HTTP 204.

Ошибки

HTTP-код	Сообщение об ошибке
404	Incorrect competitor id

Получение ТОП 10 по ключевому слову

Метод позволяет получить список результатов из ТОП 10 по ключевым словам, отслеживаемым в проекте.

Формат запроса

Title of the code block

Copy

GET /competitors/top10/{site_id}/?date=2018-01-01&site_engine_id=1&keyword_id=1

Query-параметры запроса

Имя	Обязательный	Тип	Описание
date	Да	yyyy-mm-dd	Дата получения списка сайтов из ТОП 10
keyword_id	Да		Идентификатор ключевого слова, добавленного в проект (для получения используйте GET /sites/{site_id}/keywords).
site_engine_id	Да		Идентификатор поисковой системы

Результат

В случае успеха сервер возвращает массив со списком сайтов из ТОП 10.

Имя	Описание
url	URL страницы
position	Позиция в поисковой выдаче
keyword_id	Уникальный идентификатор ключевого слова
backlinks	Суммарное количество бэклинков
domains	Количество ссылающихся уникальных доменов

Пример ответа

Title of the code block

Copy

[

    {

        "url": "https://www.tests.com/login",

        "position": 1,

        "keyword_id": 1,

        "da": null,

        "backlinks": "328",

        "domains": "32"

    },

    ...

]

Получение ТОП 100 по ключевому слову

Метод позволяет получить список результатов из ТОП 100 по ключевым словам, отслеживаемым в проекте.

Формат запроса

Title of the code block

Copy

GET /competitors/top100/{site_id}/?date=2018-01-01&site_engine_id=1&keyword_id=1

Query-параметры запроса

Имя	Обязательный	Тип	Описание
date	Да	yyyy-mm-dd	Дата
keyword_id	Да		Идентификатор ключевого слова, добавленного в проект (для получения используйте GET /sites/{site_id}/keywords)
site_engine_id	Да		Идентификатор поисковой системы
top	Нет	0…100	Максимальная позиция

Результат

В случае успеха сервер возвращает массив со списком сайтов из ТОП 100.

Имя	Описание
url	URL страницы
position	Позиция в поисковой выдаче
date	Дата проверки позиции

Пример ответа

Title of the code block

Copy

[

    {

        "url": "https://www.tests.com/login",

        "position": 1,

        "date": "2018-01-01"

    },

    {

        "url": "https://www.test2.com,

        "position": 2,

        "date": "2018-01-01"

    },

    ...

]

Все конкуренты

Информация о сайтах, которые были в ТОП-10 по каждому из отслеживаемых запросов. История сохраняется 14 дней.

Формат запроса

Title of the code block

Copy

GET /competitors/all/{site_id}/?date=2018-01-01&site_engine_id=1&group_id=1&tags[]=21

Query-параметры запроса

Имя	Обязательный	Тип	Описание
date	Да	yyyy-mm-dd	Дата получения списка сайтов из ТОП 10
site_engine_id	Нет		Идентификатор поисковой системы. Если не указан, вернёт данные для всех поисковых систем
group_id	Нет		Идентификатор группы ключевых слов. Если не указан, вернёт данные для всех
tags	Нет		Массив тегов

Результат

В случае успеха сервер возвращает массив со списком сайтов из ТОП 10.

Имя	Описание
domain_id	ID домена
domain	Домен сайта конкурента
visibility	Видимость конкурента
backlinks	Суммарное количество бэклинков
domains	Количество ссылающихся уникальных доменов

Пример ответа

Title of the code block

Copy

[

{

    "domain": "www.tests.com",

    "domain_id": 10,

    "visibility": 0,

    "da": null,

    "backlinks": "328",

    "domains": "32",

},

...

]