SEO API

Двенадцать инструментов дают приложению или агенту данные для SEO: сколько ищут ключевое слово и насколько трудно по нему подняться, какие слова и страницы приносят домену поисковый трафик, кто с ним конкурирует, кто на него ссылается, каков его Domain Rating и сколько посещений у сайта. Каждый инструмент — это один POST в /v1/seo/ с вашим API-ключом BeatAPI и результатом в одном ответе. Агентам те же инструменты доступны как возможности.

Быстрый старт

curl https://api.beatapi.io/v1/seo/keyword-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis cluster"],"country":"us"}'

{
  "object": "seo.keyword_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "monthly_searches": [{ "year": 2026, "month": 9, "search_volume": 590 }]
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Аутентификация

Передавайте ключ BeatAPI API при каждом вызове как Authorization: Bearer <key>; ключ работает и с префиксом sk-, и без него. Создать ключ можно в разделе Панель → API Keys. Все инструменты доступны на https://api.beatapi.io и списывают средства с баланса аккаунта.

Выбор инструмента

О Domain Rating и общем числе посещений сайта рассказано в разделе Domain Rating и трафик сайта.

Инструмента живой поисковой выдачи нет. Чтобы проверить позицию домена по слову, вызовите ranked-keywords с contains. Это последняя зафиксированная позиция, а не текущая.

Страна и язык

country и language выбирают рынок: поиск Google в этой стране на этом языке. Их принимают инструменты для ключевых слов, а также domain-overview, ranked-keywords, top-pages и competitors. У инструментов для обратных ссылок рынка нет, и оба поля отклоняются.

Страна или язык вне списка отклоняются с 400 bad_request, а сообщение подсказывает, что есть на этом рынке: language 'de' is not covered in us; use one of: en, es.

Лимит и смещение

keyword-ideas, ranked-keywords, top-pages, competitors и backlinks возвращают строки постранично.

Эти ответы повторяют limit и offset, а также содержат total — общее число доступных строк, если оно известно.

Ответы

Все инструменты отвечают синхронно: результат приходит в ответе на ваш POST, опрашивать нечего. Большинство вызовов занимает несколько секунд.

usage.price_usd — итоговое списание в долларах США. billing_unit всегда равно request, а quantity всегда равно 1; billed_rows показывает, сколько строк покрывает это списание.

Числа, которых нет в данных, в строку не попадают, поэтому перед использованием проверяйте наличие поля. Неизвестные поля запроса отклоняются с 400 bad_request: если бы поле с опечаткой молча игнорировалось, вы получили бы ответ на другой вопрос.

Инструменты для ключевых слов

Обзор ключевых слов

POST https://api.beatapi.io/v1/seo/keyword-overview

Объём поиска, CPC, конкуренция, сложность, интент и история по месяцам для известных слов. Слово, которое никто не ищет, в ответ не попадает и нулём не отмечается.

Ответ показан в разделе Быстрый старт. Поля каждой строки:

Идеи ключевых слов

POST https://api.beatapi.io/v1/seo/keyword-ideas

Связанные слова для ваших исходных слов, сначала самые релевантные. Поля строк те же, что в keyword-overview, но без monthly_searches.

curl https://api.beatapi.io/v1/seo/keyword-ideas \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis sentinel"],"limit":20}'

Сложность ключевых слов

POST https://api.beatapi.io/v1/seo/keyword-difficulty

Только keyword_difficulty, сразу для многих слов. Поля те же, что в keyword-overview.

{
  "object": "seo.keyword_difficulty",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    { "keyword": "redis cluster", "keyword_difficulty": 15 },
    { "keyword": "redis sentinel", "keyword_difficulty": 2 }
  ],
  "billed_rows": 2,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0186",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Инструменты для доменов

Все четыре принимают domain, например example.com, а также country и language.

Обзор домена

POST https://api.beatapi.io/v1/seo/domain-overview

Органическое и платное поисковое присутствие домена на одном рынке. Это только поисковый трафик, а не все посещения сайта.

curl https://api.beatapi.io/v1/seo/domain-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","country":"us"}'

{
  "object": "seo.domain_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "has_data": true,
  "organic": {
    "ranking_keywords": 22125,
    "search_traffic_estimate": 108626.58,
    "traffic_value_usd_estimate": 483101.98,
    "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
    "new": 18919,
    "up": 1048,
    "down": 1105,
    "lost": 4041
  },
  "paid": { "ranking_keywords": 0, "search_traffic_estimate": 0 },
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Домен, которого нет в данных, возвращается с has_data: false и без organic и paid. Это отсутствие данных, а не нулевой трафик, и вызов оплачивается.

Ключевые слова домена

POST https://api.beatapi.io/v1/seo/ranked-keywords

Слова, по которым домен занимает позиции на одном рынке, сначала с наибольшим объёмом поиска.

curl https://api.beatapi.io/v1/seo/ranked-keywords \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","contains":"cluster","limit":1}'

{
  "object": "seo.ranked_keywords",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 108,
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "position": 1,
      "absolute_position": 2,
      "url": "https://redis.io/docs/cluster/",
      "title": "Redis cluster",
      "position_seen_at": "2026-09-14 04:53:47 +00:00",
      "search_traffic_estimate": 12.35
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}

К полям keyword-ideas строки добавляют:

Топ страниц

POST https://api.beatapi.io/v1/seo/top-pages

Страницы домена, сначала с наибольшей оценкой поискового трафика. Поля: domain, limit, offset, country, language. В каждой строке есть url и поля поискового присутствия этой страницы.

{
  "object": "seo.top_pages",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 1104,
  "results": [
    {
      "url": "https://redis.io/",
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58,
      "traffic_value_usd_estimate": 483101.98,
      "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
      "new": 18919,
      "up": 1048,
      "down": 1105,
      "lost": 4041
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Конкуренты

POST https://api.beatapi.io/v1/seo/competitors

Домены, конкурирующие с указанным за те же поисковые запросы. Поля: domain, limit, offset, country, language. Сам домен и крупнейшие сайты общего назначения, такие как youtube.com и wikipedia.org, в строки не входят, а total считает только оставшиеся.

{
  "object": "seo.competitors",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 9,
  "results": [
    {
      "domain": "example.com",
      "shared_keywords": 4706,
      "avg_position": 29.6,
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Инструменты для обратных ссылок

Сводка по ссылкам

POST https://api.beatapi.io/v1/seo/backlink-summary

Ссылочный профиль домена. Единственное поле — domain.

{
  "object": "seo.backlink_summary",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "link_authority": 500,
  "backlinks": 920428,
  "referring_domains": 32647,
  "referring_main_domains": 28596,
  "referring_pages": 748383,
  "referring_ips": 19191,
  "broken_backlinks": 8482,
  "broken_pages": 2773,
  "spam_score": 28,
  "first_seen": "2019-01-15 22:56:44 +00:00",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Если домена нет в данных, has_data равно false, других полей нет, и вызов оплачивается.

Обратные ссылки

POST https://api.beatapi.io/v1/seo/backlinks

Ссылки на домен, сначала самые сильные.

{
  "object": "seo.backlinks",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 28843,
  "results": [
    {
      "source_url": "https://blog.example.com/caching",
      "source_domain": "blog.example.com",
      "source_title": "Caching notes",
      "source_authority": 493,
      "source_country": "CZ",
      "target_url": "https://redis.io/",
      "anchor": "Redis",
      "link_type": "anchor",
      "dofollow": true,
      "spam_score": 3,
      "first_seen": "2025-04-26 07:12:33 +00:00",
      "last_seen": "2026-06-18 19:14:30 +00:00",
      "is_new": false,
      "is_lost": false,
      "is_broken": false
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Как читать цифры

• Поисковый трафик. search_traffic_estimate — это оценка поискового трафика, а не всех посещений сайта.
• Оценки. Цифры трафика и его стоимости — это оценки, а не измерения сайта.
• Link authority. link_authority измеряется от 0 до 1000 по собственной шкале этого набора данных.
• Сложность ключевых слов — собственная шкала этого набора данных. Не сравнивайте её с оценками других инструментов.
• Нет значения — не ноль. Отсутствующее число означает «неизвестно» и никогда не означает ноль.
• Живой выдачи нет. Инструмента живой поисковой выдачи нет. Чтобы проверить позицию домена по слову, используйте ranked-keywords с contains. Это последняя зафиксированная позиция, а не текущая.
• Для Domain Rating и трафика сайта есть отдельные пояснения в разделе Как читать эти цифры.

Оплата

У Domain Rating и трафика сайта свои цены.

• domain-overview и backlink-summary возвращают одну запись, она считается одной строкой, а при has_data, равном false, строк нет. Вызов ranked-keywords, вернувший 100 строк, стоит $0.048.
• Вызов без результатов всё равно стоит цены за вызов. Отклонённый запрос (400) и неудачный вызов (503) не оплачиваются.
• Перед вызовом на балансе должно хватать средств на максимальную стоимость: все строки limit или все отправленные слова. Затем оплата списывается только за то, что вернулось.
• Если клиент может повторить тот же запрос, передайте заголовок Idempotency-Key. Повтор ключа с другим телом запроса отклоняется с 409 idempotency_conflict.

Агенты

Отдельного инструмента MCP для SEO-данных нет. На MCP-сервере BeatAPI https://beatapi.io/mcp агенты используют capabilities_search, capabilities_inspect и capabilities_run с такими ссылками:

Ссылки для Domain Rating и трафика сайта приведены рядом с этими инструментами.

Inspect показывает схему ввода и текущую цену. input — это тело запроса инструмента, а Run возвращает результат:

{ "reference": "data:seo.ranked_keywords", "operation": "start", "input": { "domain": "redis.io", "contains": "cluster", "limit": 20 } }

Те же три вызова доступны через REST: POST /v1/capabilities/search, /v1/capabilities/inspect и /v1/capabilities/run. См. API возможностей.

Ошибки

Ошибки используют стандартный объект ошибки BeatAPI с retryable в каждом ответе. Правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "country 'cn' is not covered; use a two-letter code such as us, gb, de or jp (China is not covered)",
    "retryable": false,
    "request_id": "req_abc123"
  }
}

Ответ 503 никогда не оплачивается. BeatAPI не возвращает 502.

Domain Rating и трафик сайта

Ещё три инструмента работают так же: тот же ключ, тот же результат в ответе, те же usage и ошибки. Они принимают domain и не имеют рынка, поэтому country и language отклоняются. Полей limit и offset нет.

Domain Rating

POST https://api.beatapi.io/v1/seo/domain-rating

curl https://api.beatapi.io/v1/seo/domain-rating \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io"}'

{
  "object": "seo.domain_rating",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "domain_rating": 90,
  "link_rank": 1927,
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}

domain_rating измеряется от 0 до 100. link_rank — мировой рейтинг домена по ссылкам; чем меньше значение, тем сильнее домен.

История Domain Rating

POST https://api.beatapi.io/v1/seo/domain-rating-history

{
  "object": "seo.domain_rating_history",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "results": [
    { "month": "2025-12", "domain_rating": 89 },
    { "month": "2026-01", "domain_rating": 89 },
    { "month": "2026-02", "domain_rating": 89 },
    { "month": "2026-03", "domain_rating": 89 },
    { "month": "2026-04", "domain_rating": 89 },
    { "month": "2026-05", "domain_rating": 89 },
    { "month": "2026-06", "domain_rating": 90 },
    { "month": "2026-07", "domain_rating": 90 },
    { "month": "2026-08", "domain_rating": 90 },
    { "month": "2026-09", "domain_rating": 90 },
    { "month": "2026-10", "domain_rating": 90 }
  ],
  "billed_rows": 11,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.044",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Для неизвестного домена возвращаются has_data: false, пустой results и billed_rows: 1.

Трафик сайта

POST https://api.beatapi.io/v1/seo/site-traffic

Оценка всех посещений сайта из всех каналов, а также источники, страны, рейтинг и вовлечённость.

curl https://api.beatapi.io/v1/seo/site-traffic \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","months":3}'

{
  "object": "seo.site_traffic",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "months": 3,
  "has_data": true,
  "site_visits_estimate": 734682,
  "monthly_visits": [
    { "month": "2026-07", "visits": 827501 },
    { "month": "2026-08", "visits": 789909 },
    { "month": "2026-09", "visits": 734682 }
  ],
  "global_rank": 66213,
  "country_rank": { "country": "IN", "rank": 19016 },
  "category": "computers_electronics_and_technology/programming_and_developer_software",
  "category_rank": 634,
  "bounce_rate": 0.4254,
  "pages_per_visit": 3.3174,
  "avg_visit_seconds": 116.2764,
  "traffic_sources": {
    "direct": 0.3293,
    "search": 0.4836,
    "paid_search": 0.0072,
    "social": 0.0435,
    "paid_social": 0.0026,
    "referrals": 0.0992,
    "mail": 0.0114,
    "display_ads": 0.0035,
    "affiliate": 0,
    "gen_ai": 0.0197
  },
  "top_countries": [{ "country": "IN", "share": 0.1995 }],
  "top_keywords": [{ "keyword": "redis", "search_volume": 193980, "cpc_usd": 2.78 }],
  "title": "Redis - Real-time data for agents & apps",
  "description": "Developers love Redis. Unlock the full potential of the Redis database with Redis Enterprise and start building blazing fast apps.",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}

Как читать эти цифры

• Два вида трафика. search_traffic_estimate — оценка поискового трафика; site_visits_estimate — все посещения из всех каналов. Это разные показатели: никогда не складывайте и не сравнивайте их. Посещения — это не уникальные посетители.
• Две оценки авторитетности. link_authority измеряется от 0 до 1000 по собственной шкале этого набора данных; domain_rating — от 0 до 100. Пересчитать одно в другое нельзя.
• Нет в данных. has_data: false означает, что домена нет в данных; это не то же самое, что нулевой рейтинг или трафик: у нового сайта рейтинг может быть 0, а link_rank при этом есть.

Цены этих инструментов

• domain-rating и site-traffic оплачиваются и при has_data, равном false. domain-rating-history для неизвестного домена не возвращает месяцев и стоит как один месяц, $0.004.
• Отклонённый запрос (400) и неудачный вызов (503) не оплачиваются.
• Перед вызовом domain-rating-history на балансе должно хватать средств на 24 месяца истории. Затем оплата списывается только за то, что вернулось.

Ссылки для агентов