seo/
ranked-keywords

Находите ключевые слова, по которым ранжируется домен, поддомен или страница на поисковом рынке, и получайте URL, позиции, поисковые метрики, намерение и оценку трафика.

Ranked Keywords API

Домен или страница
Связь запросов с URL
Контекст позиций
0,1 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

Ranked Keywords

Ранжируемые ключевые слова — это поисковые запросы, связанные с доменом, поддоменом или страницей через подходящий URL результата, с позицией в группе, абсолютной позицией и номером страницы выдачи, а также доступными показателями спроса, сложности, намерения и трафика. Такие связи между запросами и страницами помогают составлять опись видимости, сопоставлять запросы с посадочными страницами, оценивать возможности и сравнивать снимки по целевым сайтам.

Возможности Ranked Keywords API

  • Домен, поддомен или страницаОбрабатывает одну правильно оформленную веб-цель в нужном охвате: весь домен, поддомен или один полный URL страницы.
  • Связи ключевых слов с URLСвязывает каждое возвращенное ключевое слово с соответствующим целевым URL из ранжируемого элемента выдачи.
  • Позиции и метрики ключевых словВозвращает доступные позиции в группе, абсолютные позиции и номера страниц выдачи вместе с объемом поиска, CPC, конкуренцией, сложностью, помесячной историей и намерением.
  • Полный элемент выдачиСохраняет keyword_data и ranked_serp_element в extra, чтобы тип результата, расчетный трафик и детали источника, не вынесенные на верхний уровень, оставались доступными.

Параметры Ranked Keywords API

ПараметрыОбязательныйОписание
targetОбязательныйОбязательная цель: домен, поддомен или страница. Для домена уберите https:// и www., для поддомена уберите протокол, а для одной страницы используйте полный URL.
location_codeНеобязательныйПоложительный числовой код поискового рынка. В песочнице по умолчанию используется 2840.
location_nameНеобязательныйНеобязательное название поискового рынка вместо location_code. Если оно заполнено, оно имеет приоритет над location_code.
language_codeНеобязательныйКод языка поиска длиной от 2 до 10 символов. В песочнице по умолчанию используется en.
languageНеобязательныйНеобязательное название языка поиска вместо language_code. Если оно заполнено, оно имеет приоритет над language_code.
results_limitНеобязательныйЗапрошенный максимум от 1 до 1 000 строк ранжируемых ключевых слов. Строк может вернуться меньше.
offsetНеобязательныйЧисло строк источника (отсчет от нуля), которые нужно пропустить перед сбором запрошенного окна результатов.

Как использовать Ranked Keywords API

Отправьте одну цель с правильным охватом, настройками рынка и ограниченным окном результатов, а затем читайте каждое ранжируемое ключевое слово из завершенной асинхронной задачи.

  1. Выберите один target, location_code, language_code, results_limit от 1 до 1 000 и offset не меньше 0.
  2. Отправьте данные методом POST на /v1/seo/ranked-keywords и сохраните возвращенный task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой.
  4. Читайте data.results.items, а затем запрашивайте возвращенный next_cursor, пока has_more равно true.
curl -X POST "https://api.socq.ai/v1/seo/ranked-keywords" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"microsoft.com","location_code":2840,"language_code":"en","results_limit":5}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Сценарии использования Ranked Keywords API

  • Опись органической видимости: Используйте текст возвращенных ключевых слов и соответствующие URL, чтобы каталогизировать, где домен или поддомен появляется на выбранном поисковом рынке.
  • Карта позиций посадочных страниц: Сочетайте каждое ключевое слово, целевой URL и объект rank, чтобы определить, какая страница связана с каждой возвращенной позицией.
  • Оценка возможностей по ключевым словам: Сравнивайте позицию с доступными полями объема, CPC, конкуренции, сложности и намерения, чтобы сформировать очередь на проверку.
  • Сравнение снимков видимости: Сохраняйте одинаковые входные цели, collected_at, ключевые слова, URL и позиции из повторных задач, чтобы сравнивать отдельно собранные снимки.

Практические советы по Ranked Keywords API

  • Убирайте https:// и www. из цели-домена и протокол из цели-поддомена, чтобы нужный охват был интерпретирован правильно.
  • Используйте полный URL страницы, если нужны результаты на уровне страницы: путь страницы без протокола может быть воспринят как цель для всего домена.
  • Увеличивайте offset на число строк источника, которые нужно пропустить, и не меняйте цель, рынок, язык и лимит при получении последовательных окон.
  • Считайте rank.page номером страницы выдачи; используйте offset для окон источника, а next_cursor — отдельно для сохраненных страниц результатов SocQ.
  • Сначала читайте нормализованные позиции и метрики ключевых слов, а затем проверяйте extra.ranked_serp_element на наличие расчетного etv и других полей источника, не вынесенных на верхний уровень.
  • Стройте исторические сравнения по повторным задачам и удаляйте дубли окон по ключевому слову, соответствующему URL, рынку и языку, потому что порядок в источнике может меняться.

Помимо Ranked Keywords API, используйте эти API, когда нужен другой тип публичных данных SEO.

  • Google Organic SERP API — Получайте одну актуальную страницу выдачи Google по запросу и рынку: нормализованные целевые URL, позиции, типы элементов и полные данные результатов.
  • Keyword Difficulty API — Сравнивайте сложность продвижения в органической выдаче для пакета ключевых слов и получайте нормализованную оценку для каждого доступного слова.
  • Keyword Overview API — Дополняйте пакет ключевых слов доступными данными о спросе, конкуренции в платной выдаче, сложности, ежемесячной частотности и интенте.
  • Keyword Search Volume API — Измеряйте известные ключевые слова: доступная частотность, CPC, конкуренция в платной выдаче и история частотности по месяцам.
  • Keywords for Site API — Подбирайте ключевые слова, релевантные одному сайту, с доступными данными о спросе, помесячной историей, контекстом рынка и полными исходными строками.
  • Relevant Pages API — Составляйте перечень проиндексированных страниц одного домена с распределением позиций в органической и платной выдаче, расчетным трафиком и оценкой стоимости.

Другие платформы

Объединяйте данные SEO с публичными данными других поддерживаемых соцсетей.

Ranked Keywords API — FAQ

Ranked Keywords API — это программный интерфейс для поиска запросов, связанных с одним доменом, поддоменом или страницей на выбранном рынке и языке. Он возвращает соответствующие URL, позиции, метрики ключевых слов, помесячную историю, намерение и полные элементы источника.

Используйте голый домен без https:// и www., поддомен без протокола или полный URL для одной страницы. Путь страницы без протокола может расширить охват до всего домена.

Нет. Позиции описывают выбранный поисковый индекс и рынок, а не одинаковую актуальную выдачу для каждого пользователя, поэтому при сравнении повторных снимков используйте collected_at.

rank.page — номер страницы выдачи, offset пропускает строки ключевых слов в источнике, а next_cursor листает результаты, уже сохраненные для задачи SocQ. Эти значения не взаимозаменяемы.

Нет. etv — это расчетное значение, сохраняемое в extra.ranked_serp_element, а не закрытые данные о трафике или конверсиях целевого сайта.

Каждое возвращенное ранжируемое ключевое слово стоит 0,1 кредита SocQ. За пустой набор результатов плата не взимается, а results_limit задает предварительную оценку, а не гарантированное итоговое число.