Все запросы к API должны отправляться на урл вида:
https://serphunt.ru/версия/действие/объект[/данные]
Все данные нужно отправлять в кодировке UTF-8 с помощью метода POST, тип остылаемых данных - JSON.
Обязательные заголовки запроса:
Content-type: application/json; charset=UTF-8 Authorization: Bearer %apikey%
Заголовок Authorization требуется для авторизации пользователя в api. Ключ %apikey% можно взять в кабинете пользователя.
Ответ приходит в кодировке UTF-8 в формате JSON.
Возможные поля ответа:
| error | отдается в случае ошибки ( см. раздел обработка ошибок ) |
| message | cервисные сообщения |
| result | результат выполнения задания / проверки |
| task_id | идентификатор задания, возвращается в при добавлении проверки |
| balance yandex_xml |
информация о балансе пользователя и xml лимитах |
Более подробную информацию смотрите в описании объектов: проверки, биллинг
В одном запросе на получение данных можно запросить не более 5 000 результатов ( ключевых слов для проверки позиций или частотности, страниц для проверки индексации ). При превышении лимита, количество заправшиваемых данных обрезается.
С одного IP не более 5 одновременных запросов, иначе будет возвращена ошибка TOO_MANY_REQUESTS и код ответа сервера 429
В случае ошибки api возвращает ответ в формате:
{
"error" : {
"error_code" : "AUTHORISATION_ERROR",
"error_code" : "Ошибочный APIKEY",
}
}
| Код ошибки | Описание ошибки | Возможные причины |
|---|---|---|
| INVALID_URL | Ошибка запрашиваемого урл API | Неверно указан URL запросов к API |
| AUTHORISATION_ERROR | Ошибка авторизации | В запросе отсутствует заголовок Authorization
Неверно задан ключ доступа к API |
| TOO_MANY_REQUESTS | Слишком большое количество запросов | Количество соединений в секунду для данного IP превышает величину заданную в лимитах |
| REQUEST_ERROR | Ошибка отсылаемых к API данных | Пропущен или неверно задан один из параметров запроса к API |
| DATA_NOT_FOUND | Запрашиваемые данные не найдены | Данные были удалены |
| BILLING_ERROR | Ошибка биллинга | Недостаточно средств на баллансе
Данный вид проверки не разрешен Для данного тарифа работа с API не разрешена |
https://serphunt.ru/api/v1/add/check
| service |
Название сервиса: positions ( передается как строка ) "service": "positions" |
||||
| page |
Список страниц, которые надо проверить Может передаваться либо как массив ( один элемент и более ) "page": [ "https://serphunt.ru/positions/", "https://serphunt.ru/indexing/", "https://serphunt.ru/frequency/" ] либо как строка (ключевые слова соединяются символом переноса строки "\n" "page": "https://serphunt.ru/positions/ https://serphunt.ru/indexing/ https://serphunt.ru/frequency/" |
||||
| subdomains |
Проверять или нет субдомены ( передается как число 0 или 1 ) "subdomains": 0 |
||||
| keywords |
Ключевые слова. Могут передаваться либо как массив ( один элемент и более ) "keywords": [ "ключевое слово 1", "ключевое слово 2", "ключевое слово 3" ] либо как строка (ключевые слова соединяются символом переноса строки "\n") "keywords": "ключевое слово 1 ключевое слово 2 ключевое слово 3" |
||||
| search_engine |
Данные передаются массивом ( один элемент и более ) "search_engine": [ "yandex", "google" ] |
||||
| region |
Список кодов регионов ( при одновременном снятии позиций в яндекс и google )
Передаются массивом ( один элемент и более ) "region": [ 216, 225 ] |
||||
| device |
Передаются массивом ( один элемент и более ) "device": [ "mobile", "desktop" ] |
||||
| language |
Язык пользователей ( передается как строка ). Список кодов языков. "language": "ru" |
Пример запроса
{
"service": "positions",
"page": [ "https://serphunt.ru/positions/", "https://serphunt.ru/indexing/", "https://serphunt.ru/frequency/" ],
"subdomains": false,
"keywords": [ "ключевое слово 1", "ключевое слово 2", "ключевое слово 3" ],
"search_engine": [ "yandex", "google" ],
"region": [ 216, 225 ],
"device": [ "mobile", "desktop" ],
"language": "ru"
}
| task_id | идентификатор задания, который необходимо использовать при получении результатов проверки |
{ "task_id" : "922f9e59ff84ea387c0748301a7cf3e5" }
Историю проверок можно посмотреть в кабинете пользователя.
Данные храняться в течении одного года.
https://serphunt.ru/api/v1/get/check/result
| task_id | идентификатор задания |
{ "task_id" : "922f9e59ff84ea387c0748301a7cf3e5" }
Если задание еще не выполнено, ответ будет следующим:
{
"message" : {
"code" : "TASK_IN_PROGRESS",
"description" : "Задание в обработке"
}
}
Примеры ответов, в случае успешного выполнения задания для проверки.
{
"result" : {
"225_mobile_ru" : {
"анализ позиций сайта" : {
"google" : {
"https://serphunt.ru/positions/" : {
"position" : 3,
"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/"
}
},
"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/"
}
},
"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/"
}
},
"yandex" : {
"https://serphunt.ru/positions/" : {
"position" : 1,
"relevance_url" : "https://serphunt.ru/positions/"
}
}
}
}
}
}
https://serphunt.ru/api/v1/get/billing/balance
{
"balance" : 568
"yandex_xml" : 454
}
