SEO-проекты · token

positions Позиции запросов проекта

Метод positions/get отдаёт позиции запросов проекта за один апдейт: по строке на запрос × поисковую систему × регион, с релевантным URL, группами и точной частотой. Без update_id берётся последний завершённый апдейт. Метод синхронный, лимиты не тратит.

Адрес
/projects/api/v1/positions/get
Доступ
свои проекты и проекты с выданным доступом
Лимиты
не тратит

Позиции за апдейт

GET /projects/api/v1/positions/get

Позиции отдаются массивом без обёртки status/result. offset и limit считают запросы, а не строки: на каждый запрос приходит по строке на каждую пару «поисковая система + регион» проекта. Какие запросы попадут на страницу, решает сортировка проекта в интерфейсе; внутри страницы строки идут по ID запроса.

Параметры query

  • token string обязательный
    Ключ API из настроек аккаунта — тот же, что key у методов инструментов.
  • project_id int обязательный
    ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
  • update_id int
    ID апдейта из updates/get. Без него — последний завершённый апдейт проекта. Апдейт другого проекта даёт пустой массив.
  • group_id int
    Только запросы группы из groups/get. -1 — запросы без группы. Без параметра или 0 — все.
  • region int
    Код региона: только строки этого региона. Без параметра — все регионы проекта.
  • offset int
    Сколько запросов пропустить.
    По умолчанию 0
  • limit int
    Сколько запросов отдать. 0 или без параметра — 1000.
    По умолчанию 1000

Ответ

  • [].position string
    Позиция; 0 — сайт не найден в пределах глубины проверки.
  • [].id string
    ID запроса.
  • [].query string
    Фраза.
  • [].rel_url string|null
    Релевантная страница сайта в выдаче.
  • [].group_id string
    ID группы; если групп несколько — через запятую ("1, 22150"); "0" — без группы.
  • [].group_name string
    Названия групп в том же порядке; Без группы, если групп нет.
  • [].update_id string
    ID апдейта.
  • [].search_system_id string
    ID поисковой системы, как в search-systems/get.
  • [].search_system_name string
    Название поисковой системы.
  • [].region string
    Код региона.
  • [].region_name string
    Название региона.
  • [].frequency string|null
    Точная частота в регионе частот проекта; null, если не собрана.
  • [].deep string|null
    Глубина проверки позиций из настроек проекта.

Ошибки

КодСообщениеКогда
50 access error Токен не передан, не найден, или у его владельца нет доступа к проекту.

Пустой ответ

Пустой массив [] приходит, когда у проекта ещё нет апдейтов, update_id чужой, в группе нет запросов или offset больше числа запросов. Ошибки в этих случаях нет.

Как выгрузить все позиции

Возьмите id апдейта из updates/get и запрашивайте страницы с offset = 0, 1000, 2000… с одним и тем же update_id, пока не придёт пустой массив. Без явного update_id страницы могут попасть на разные апдейты, если между вызовами закончится новый.

Обратная связь и помощь
Если у вас есть идеи, как улучшить данный инструмент или остались вопросы по работе с ним, напишите в нашу службу поддержки, мы обязательно вам поможем.