Внимание! Яндекс Search API работает в ограниченном режиме, проверки проходят стабильно с 00:00 до 06:00 по МСК.
В другое время советуем использовать Яндекс Live - подключить его можно в настройках проекта.

API Серпхант

  • Начало работы
  • Обработка ошибок
  • Проверки
    • Добавление задания
    • Получение результатов
  • Биллинг
    • Баланс
Начало работы

URL запроса для обращения к серверу API

Все запросы к API должны отправляться на урл вида:

https://serphunt.ru/api/версия/действие/объект[/данные]

  • Версия API ( v1 )
  • Действие, которое необходимо выполнить при обращении к api:
    add - добавление объектов
    get - получение данных
  • Объект, на который направлено выбранное действие
    check - проверка позиций, частотности, индексации, анализ страниц конкурентов
    billing - доступный баланс
  • Данные которые необходимо получить, используются при действии get ( /api/v1/get/billing/balance )

Для позиций, индексации и анализа конкурентов сейчас доступны источники 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-проверок Яндекса

Параметры запросов и примеры ответов: проверки, биллинг

Ограничение на использование API

  • Одна задача принимает до 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 этот статус сохраняется до завершения проверки.

Добавление задания для проверки

URL запроса

https://serphunt.ru/api/v1/add/check

Источник yandexlive предназначен для позиций, индексации и анализа страниц конкурентов. Сейчас Яндекс Live доступен. При временном сбое уже созданная проверка остается в обработке до получения результата.

Глубина и стоимость

Глубина позиций определяет, среди скольких первых результатов поиска проверяется адрес. Если адрес находится ниже выбранной глубины, результат содержит position: 0.

Для Яндекс Live сейчас доступны глубины 10, 20, 30, 40, 50, по умолчанию 10. Недопустимая глубина возвращает REQUEST_ERROR до создания задачи и резервирования средств.

Позиции Live оплачиваются по запрошенной глубине для каждого ключевого слова, уникального адреса, региона и устройства. Стоимость одной такой проверки равна цене по тарифу, умноженной на глубину / 10. Множитель применяется и при отсутствии адреса в выбранной глубине.

Глубина LiveМножитель стоимости
101
202
303
404
505

Для обычного Яндекса множитель равен 1. При выборе нескольких источников их стоимость складывается. Индексация оплачивается за адрес и источник, анализ конкурентов - за один анализ по действующему тарифу.

POST параметры

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

Поисковая система

yandexяндекс
yandexliveЯндекс Live
googlegoogle

Данные передаются массивом или строкой с разделителем ",". Источники можно выбирать одновременно.

"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 используются его коды регионов.

Яндекс и Яндекс Liveсоответствующий параметр "lr" из excel файла - регионы яндекса
Google"Criteria ID" из csv файла - геоцели

Передаются массивом ( один элемент и более )

"region": [ 216, 225 ]
device

Устройства

По умолчанию mobile. При выборе двух устройств выполняются две отдельные проверки.

mobileмобильные устройства
desktopнастольные компьютеры

Передаются массивом ( один элемент и более )

"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"
  }
}
Получение результатов проверки

Историю проверок можно посмотреть в кабинете пользователя.

Результаты хранятся в течение одного года.

URL запроса

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.

POST параметры

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/"
          }
        }
      }
    }
  }
}
Проверка баланса

URL запроса

https://serphunt.ru/api/v1/get/billing/balance

Запрос возвращает доступные остатки с учетом средств и проверок, зарезервированных для выполняющихся задач. Получение баланса бесплатно.

Ответ

balance - доступный денежный баланс в рублях. yandex_xml - доступный остаток XML-проверок Яндекса.

{
  "balance" : 568,
  "yandex_xml" : 454
}
Страница обновлена:
Остались вопросы? Обращайтесь!
Задать вопрос
Или позвоните нам
Что думают наши клиенты
Александр Трачум Основатель агентства по продвижению сайтов Seodev.by
Серпхант собрал в себе все инструменты, которые нужны SEO специалисту: анализ контента, проверка позиций, анализ конкурентов и многое другое. С помощью данного сервиса можно забыть о том, что такое ручной труд в работе специалиста по продвижению сайтов.
Марк Автор блога по SEO-оптимизации znet.ru
Пользуюсь проверкой индексации, снятием позиций и некоторыми другими функциями сервиса. Мало есть бесплатных инструментов, которые позволяют массово парсить данные Google, а вкупе с понятным и современным дизайном это делает Serphunt действительно востребованным в повседневной работе
Артур Чахалян SEO-оптимизатор
Очень удобно, что большой объем данных видно сразу в одном месте: страницы, ключи, позиции, тошнотность, биграммы, оценки по главреду, объем текста и даже трафик для каждой статьи за день и месяц! При чем все эти данные формируются автоматически. Достаточно указать url статей (или просто установить плагин WP) и можно получить все данные в пару кликов.
Юрий Гришаев Вебмастер
Очень удобный сервис, для информационных сайтов, т.к. в нём можно смотреть все параметры в постатейном срезе. Показываются все важные метрики, с помощью этого не надо никуда лезть, всё в 1-м месте. Сейчас активно им пользуюсь, что говорит о том, что мне всё нравится.
Александр Савин Вебмастер
Серпхант — один из лучших сервисов поисковой аналитики, который вмещает в себя необходимые инструменты для анализа продвигаемого ресурса. Главными его достоинствами являются точная проверка и семантический анализ текста.
Виктор SEO-специалист
Сервис Серпхант имеет понятный интерфейс. Он способен собрать полную информацию о вашем сайте, благодаря богатому SEO функционалу. В сервисе есть бесплатные проверки позиций, с использованием лимитов Яндекс.XML.
Наши инструменты для продвижения сайтов
  1. Проверка позиций сайта Бесплатный парсер занимаемых позиций в Яндексе и Гугл
  2. Проверка индексации страниц Контроль за наличием страниц в индексе поисковых систем Яндекс
  3. Анализ контента Комплексный семантический анализ контента
  4. Проверка частотности запросов Статистика ввода запросов в поисковых системах
  5. Анализ страниц конкурентов Глубокий, сравнительный анализ страниц конкурентов из ТОП 10 Яндекса
  6. Парсинг подсветок Анализ сниппетов в поисковой выдаче
Войти в аккаунт
 
Войти через:
Вход через Google и Facebook временно недоступен в связи с требованиями законодательства РФ. Если вы регистрировались через них, нажмите «Забыли пароль?» и восстановите доступ по тому же e-mail.
Восстановление пароля
Зарегистрируйтесь и получите бесплатно
500 проверок позиций сайта
Регистрация
Зарегистрироваться через:
Вход через Google и Facebook временно недоступен в связи с требованиями законодательства РФ. Если вы регистрировались через них, нажмите «Забыли пароль?» и восстановите доступ по тому же e-mail.
Нажимая "Зарегистрироваться", Вы принимаете Пользовательское соглашение и Политику конфиденциальности.
Загрузка ...