Все запросы к API должны отправляться на урл вида:
https://serphunt.ru/api/версия/действие/объект[/данные]
Для позиций, индексации и анализа конкурентов сейчас доступны источники yandex, google, yandexlive. Частотность определяется через Wordstat.
Действие get в адресе API означает получение данных. Повторное получение статуса и результата проверки бесплатно.
Все данные нужно отправлять в кодировке UTF-8 с помощью метода POST, тип данных - JSON.
Обязательные заголовки запроса:
Content-type: application/json; charset=UTF-8 Authorization: Bearer %apikey%
Заголовок Authorization требуется для авторизации пользователя в api. Ключ %apikey% можно взять в кабинете пользователя.
Ответ приходит в кодировке UTF-8 в формате JSON.
Возможные поля ответа:
| error_code error_description |
код и описание ошибки ( см. раздел обработка ошибок ) |
| message | cервисные сообщения |
| result | результат выполнения задания / проверки |
| task_id | идентификатор задания, возвращается при добавлении проверки |
| balance yandex_xml |
доступный денежный баланс и остаток XML-проверок Яндекса |
Параметры запросов и примеры ответов: проверки, биллинг
Одна задача принимает до 1000 ключевых слов для позиций или частотности либо до 1000 адресов для индексации. Элементы сверх лимита отбрасываются при создании задачи.
Лимит обращений с одного IP - 31 запрос в секунду, включая получение статуса, результата и баланса. При превышении возвращаются TOO_MANY_REQUESTS и HTTP 429.
Максимальная глубина позиций Яндекс Live сейчас 50. Допустимые значения: 10, 20, 30, 40, 50. Превышение возвращает REQUEST_ERROR до создания задачи и резервирования средств.
Доступ к API и стоимость проверок определяются тарифом аккаунта. Информация о тарифе и остатке проверок доступна в кабинете.
В случае ошибки api возвращает ответ в формате:
{
"error_code": "AUTHORISATION_ERROR",
"error_description": "Ошибочный APIKEY"
}
| Код ошибки | Описание ошибки | Возможные причины |
|---|---|---|
| INVALID_URL | Ошибка запрашиваемого урл API | Неверно указан URL запросов к API |
| AUTHORISATION_ERROR | Ошибка авторизации | В запросе отсутствует заголовок Authorization
Неверно задан ключ доступа к API |
| TOO_MANY_REQUESTS | Слишком большое количество запросов | Частота запросов с одного IP превышает предел из раздела Ограничения |
| REQUEST_ERROR | Ошибка отсылаемых к API данных | Пропущен или неверно задан параметр запроса, превышена доступная глубина Live или выбран временно недоступный источник |
| DATA_NOT_FOUND | Запрашиваемые данные не найдены | Данные были удалены
Проверка не найдена Анализ страниц конкурентов завершен без результата. Причина передается в error_description |
| BILLING_ERROR | Ошибка биллинга | Недостаточно средств на балансе
Данный вид проверки не разрешен Для данного тарифа работа с API не разрешена |
Ответ TASK_IN_PROGRESS означает, что проверка выполняется. При временной недоступности выдачи Live этот статус сохраняется до завершения проверки.
https://serphunt.ru/api/v1/add/check
Источник yandexlive предназначен для позиций, индексации и анализа страниц конкурентов. Сейчас Яндекс Live доступен. При временном сбое уже созданная проверка остается в обработке до получения результата.
Глубина позиций определяет, среди скольких первых результатов поиска проверяется адрес. Если адрес находится ниже выбранной глубины, результат содержит position: 0.
Для Яндекс Live сейчас доступны глубины 10, 20, 30, 40, 50, по умолчанию 10. Недопустимая глубина возвращает REQUEST_ERROR до создания задачи и резервирования средств.
Позиции Live оплачиваются по запрошенной глубине для каждого ключевого слова, уникального адреса, региона и устройства. Стоимость одной такой проверки равна цене по тарифу, умноженной на глубину / 10. Множитель применяется и при отсутствии адреса в выбранной глубине.
| Глубина Live | Множитель стоимости |
|---|---|
| 10 | 1 |
| 20 | 2 |
| 30 | 3 |
| 40 | 4 |
| 50 | 5 |
Для обычного Яндекса множитель равен 1. При выборе нескольких источников их стоимость складывается. Индексация оплачивается за адрес и источник, анализ конкурентов - за один анализ по действующему тарифу.
| service |
Название сервиса: positions ( передается как строка ) "service": "positions" |
||||||
| page |
Список доменов или адресов страниц. Адрес без пути (например, https://example.org/) проверяется как домен: определяется позиция любой его страницы. Адрес с путем проверяется как отдельная страница. Может передаваться либо как массив ( один элемент и более ) "page": [ "https://serphunt.ru/positions/", "https://serphunt.ru/indexing/", "https://serphunt.ru/frequency/" ] либо как строка (адреса соединяются символом переноса строки "\n") "page": "https://serphunt.ru/positions/\nhttps://serphunt.ru/indexing/\nhttps://serphunt.ru/frequency/" |
||||||
| subdomains |
Учет поддоменов при проверке домена: 0 - отключен, 1 - включен. По умолчанию 0 "subdomains": 0 |
||||||
| keywords |
Ключевые слова. Лимит на задачу: 1000. Элементы сверх лимита отбрасываются. Могут передаваться либо как массив ( один элемент и более ) "keywords": [ "ключевое слово 1", "ключевое слово 2", "ключевое слово 3" ] либо как строка (ключевые слова соединяются символом переноса строки "\n") "keywords": "ключевое слово 1\nключевое слово 2\nключевое слово 3" |
||||||
| search_engine |
Данные передаются массивом или строкой с разделителем ",". Источники можно выбирать одновременно. "search_engine": [ "yandex", "google", "yandexlive" ] |
||||||
| yandex_live_search_depth |
Глубина позиций Яндекс Live. Допустимые значения сейчас: 10, 20, 30, 40, 50. По умолчанию 10. Применяется к источнику yandexlive. Другое значение возвращает REQUEST_ERROR до создания задачи и резервирования средств. Стоимость рассчитывается по запрошенной глубине. "yandex_live_search_depth": 30 |
||||||
| google_search_depth |
Глубина проверки Google: целое число от 1 до 100, по умолчанию 10. Стоимость на адрес, ключевое слово, регион и устройство равна цене проверки по тарифу, умноженной на глубину / 10. "google_search_depth": 10 |
||||||
| region |
Список кодов регионов ( при одновременном снятии позиций в Яндексе или Яндекс Live и Google ) Для Яндекса и Live используются коды регионов Яндекса. При добавлении Google коды берутся из общего списка выше. Для отдельного запроса Google используются его коды регионов.
Передаются массивом ( один элемент и более ) "region": [ 216, 225 ] |
||||||
| device |
По умолчанию mobile. При выборе двух устройств выполняются две отдельные проверки.
Передаются массивом ( один элемент и более ) "device": [ "mobile", "desktop" ] |
||||||
| language |
Язык пользователей ( строка, по умолчанию ru ). Список кодов языков. "language": "ru" |
Пример запроса
{
"service": "positions",
"page": [ "https://serphunt.ru/positions/", "https://serphunt.ru/indexing/", "https://serphunt.ru/frequency/" ],
"subdomains": 0,
"keywords": [ "ключевое слово 1", "ключевое слово 2", "ключевое слово 3" ],
"search_engine": [ "yandex", "google", "yandexlive" ],
"region": [ 216, 225 ],
"device": [ "mobile", "desktop" ],
"language": "ru",
"yandex_live_search_depth": 30
}
| task_id | идентификатор задания, который необходимо использовать при получении результатов проверки |
{ "task_id" : "922f9e59ff84ea387c0748301a7cf3e5" }
Для проверки позиций обычного Яндекса вне ночного окна ответ может содержать дополнительное поле warning. Задание создано и ожидает разрешенного времени проверки. Яндекс Live и Google выполняются по обычным правилам.
warning.code содержит YANDEX_NIGHT_CHECKS, warning.description содержит настраиваемый текст предупреждения. Для определения типа предупреждения используется стабильный код YANDEX_NIGHT_CHECKS. Поле отсутствует внутри окна и при отключенном уведомлении.
{
"task_id": "922f9e59ff84ea387c0748301a7cf3e5",
"warning": {
"code": "YANDEX_NIGHT_CHECKS",
"description": "Из-за сбоев в дата-центрах Яндекса Search API работает в ограниченном режиме. Проверки выполняются только с 00:00 до 06:00 по МСК. В другое время советуем использовать Яндекс Live"
}
}
Историю проверок можно посмотреть в кабинете пользователя.
Результаты хранятся в течение одного года.
https://serphunt.ru/api/v1/get/check/result
Повторное получение статуса и результата по одному task_id бесплатно. Эти запросы читают данные существующей проверки. Списание связано с выполнением самой проверки. Частота обращений ограничивается общим лимитом API.
Для позиций и индексации результат Live находится в ключе yandexlive, рядом с выбранными yandex и google. Ключ региона позиций имеет формат код_региона_устройство_язык, например 225_mobile_ru. Значение position: 0 означает, что адрес отсутствует в пределах проверенной глубины. В индексации 1 означает наличие страницы в индексе, 0 - отсутствие. Для анализа конкурентов поле search_engine содержит yandexlive.
| task_id | идентификатор задания |
{ "task_id" : "922f9e59ff84ea387c0748301a7cf3e5" }
Если задание еще не выполнено, ответ будет следующим:
{
"message" : {
"code" : "TASK_IN_PROGRESS",
"description" : "Задание в обработке"
}
}
Пока в проверке позиций остаются объекты обычного Яндекса, вне ночного окна к статусу TASK_IN_PROGRESS может добавляться поле warning. Его код YANDEX_NIGHT_CHECKS, поле description содержит настраиваемый текст предупреждения. Тип предупреждения определяется по стабильному коду YANDEX_NIGHT_CHECKS.
Предупреждение отсутствует внутри окна, при отключенном уведомлении и после завершения всех объектов обычного Яндекса. В смешанной проверке Google и Яндекс Live продолжают выполняться по обычным правилам. Готовый результат возвращается в поле result.
{
"message": {
"code": "TASK_IN_PROGRESS",
"description": "Задание в обработке"
},
"warning": {
"code": "YANDEX_NIGHT_CHECKS",
"description": "Из-за сбоев в дата-центрах Яндекса Search API работает в ограниченном режиме. Проверки выполняются только с 00:00 до 06:00 по МСК. В другое время советуем использовать Яндекс Live"
}
}
Примеры ответов, в случае успешного выполнения задания для проверки.
{
"result" : {
"225_mobile_ru" : {
"анализ позиций сайта" : {
"google" : {
"https://serphunt.ru/positions/" : {
"position" : 3,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandexlive" : {
"https://serphunt.ru/positions/" : {
"position" : 7,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandex" : {
"https://serphunt.ru/positions/" : {
"position" : 1,
"relevance_url" : "https://serphunt.ru/positions/"
}
}
},
"проверка позиций в поисковых системах" : {
"google" : {
"https://serphunt.ru/positions/" : {
"position" : 2,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandexlive" : {
"https://serphunt.ru/positions/" : {
"position" : 7,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandex" : {
"https://serphunt.ru/positions/" : {
"position" : 6,
"relevance_url" : "https://serphunt.ru/positions/"
}
}
}
},
"225_desktop_ru" : {
"анализ позиций сайта" : {
"google" : {
"https://serphunt.ru/positions/" : {
"position" : 2,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandexlive" : {
"https://serphunt.ru/positions/" : {
"position" : 7,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandex" : {
"https://serphunt.ru/positions/" : {
"position" : 4,
"relevance_url" : "https://serphunt.ru/positions/"
}
}
},
"проверка позиций в поисковых системах" : {
"google" : {
"https://serphunt.ru/positions/" : {
"position" : 3,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandexlive" : {
"https://serphunt.ru/positions/" : {
"position" : 7,
"relevance_url" : "https://serphunt.ru/positions/"
}
},
"yandex" : {
"https://serphunt.ru/positions/" : {
"position" : 1,
"relevance_url" : "https://serphunt.ru/positions/"
}
}
}
}
}
}
https://serphunt.ru/api/v1/get/billing/balance
Запрос возвращает доступные остатки с учетом средств и проверок, зарезервированных для выполняющихся задач. Получение баланса бесплатно.
balance - доступный денежный баланс в рублях. yandex_xml - доступный остаток XML-проверок Яндекса.
{
"balance" : 568,
"yandex_xml" : 454
}