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

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

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

Параметры

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

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

POST /competitors
{
site_id : 1,
name : “name”,
url : “https://site.test.com/”
}

Результат

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

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

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

{
“id”: 123456
}

Ошибки

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

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

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

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

GET /competitors/site/{site_id}

Результат

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

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

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

[
{
“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”,
}
]

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

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

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

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-ddID поисковой системы, для которой надо получить статистику.
with_serp_featuresНетСпециальные элементы поисковой выдачи Google, найденные в результатах поиска по ключевому слову

Результат

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

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

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

[
{
“site_engine_id”: 123,
“keywords”:[
{
“id”: “123”,
“positions”:[
{
“date”: “2018-07-25”,
“pos”: 7,
“change”: 1
}
]
}
],
“name”: null,
“volume”: null
},

]

Ошибки

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

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

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

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

DELETE /competitors/{competitor_id}

Результат

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

Ошибки

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

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

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

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

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.

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

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

[
{
“url”: “https://www.tests.com/login”,
“position”: 1,
“keyword_id”: 1,
“da”: null,
“backlinks”: “328”,
“domains”: “32”,
“yandex_x”: null
},

]

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

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

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

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.

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

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

[
{
“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 дней.

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

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_idID домена
domainДомен сайта конкурента
visibilityВидимость конкурента
backlinksСуммарное количество бэклинков
domainsКоличество ссылающихся уникальных доменов
yandex_xИндекс качества сайта. Показывает, насколько полезен сайт конкурента для пользователей с точки зрения Яндекса

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

[
{
“domain”: “www.tests.com”,
“domain_id”: 10,
“visibility”: 0,
“da”: null,
“backlinks”: “328”,
“domains”: “32”,
“yandex_x”: null
},

]