Документация

Руководство

Всё, что нужно знать о GEO Scout

Developer API

REST API экспорта аналитики

Программно выгружайте аналитику бренда из GEO Scout — для BI, кастомных дашбордов и автоматизации.

Что вы получаете

  • —Аналитику бренда за период до 90 дней одним запросом
  • —17 датасетов: промпты, источники, ответы AI, Share of Voice, восприятие бренда, конкуренты со справочником, таймлайны, пробелы и реклама
  • —CSV-архив (zip с несколькими файлами) или JSON-bundle
  • —Те же данные, что и кнопка экспорта в дашборде

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

Эндпоинт принимает Bearer-токен. Используются те же токены, что и для MCP-интеграции — Personal Access Token (PAT) или OAuth-токен.

Сгенерировать PAT можно на странице /mcp. Требуется scope mcp:read (выдаётся по умолчанию).

Каталог датасетов

26 наборов данных: от ответов и цитирований до метрик, истории рекламы, товарных карточек и рекомендаций E-com. Выбирайте любую комбинацию.

КлючЧто в нём
promptsЗапросы бренда с per-period метриками: охват, SoV, тональность для каждого промпта.
source_domainsЦитирования, свёрнутые по домену, по убыванию — таблица доменов со страницы «Источники»: used (все появления) / cited (из них реальные цитирования), citation_share_pct, priority_score, unique_urls, brand_confirmed_urls / brand_not_found_urls / brand_unchecked_urls (сколько URL домена подтверждённо упоминают бренд на странице, прочитаны без упоминания, ещё не проверены), prompts_count, prompt_ids (джойнятся с «Запросами бренда»), группы и провайдеры.
source_pagesТо же, свёрнутое по URL: source_title, used / cited, citation_share_pct, priority_score, brand_mentioned_on_page (true — имя бренда найдено на странице, false — страница прочитана и бренда на ней нет, null — не проверялась), brand_page_check (confirmed / not_found / unverifiable / not_checked), brand_page_snippets (до 20 фрагментов страницы вокруг упоминаний бренда; пусто, если не confirmed), prompts_count, prompt_ids, группы и провайдеры.
responsesСырые строки ответов AI: prompt_id, response_id, провайдер, тональность, позиция бренда, тип цитирования, а также answered_from_memory (движок ответил из памяти, без поиска), forced_search (мы отправили запрос найти актуальные данные) и forced_search_error. Полный текст ответа и ответ до поиска добавляются только при includeResponseText: true. Дополнительно: prompt_text, cluster_id, cluster, brand_presence_level, brand_presence_reason, brand_comparison, brand_comparison_extracted, brand_argued, brand_standing_note, directly_recommended_entities и directly_recommended_entity_ids, stronger_competitors и stronger_competitor_ids, competitor_presence (массив: entity_id, entity_name, presence_level, level_reason, recommendation, comparison, comparison_extracted, argued, sentiment). Значения уровней и сравнений — как в perception_responses. Пустые ответы сохраняются; сводки их исключают. При отсутствии разметки comparison/argued равны null, а comparison_extracted=false. В CSV вложенные массивы и объекты записываются как JSON.
share_of_voiceСнапшот SoV: брэнд + конкуренты, упоминания и доли за период.
sentimentТональность упоминаний бренда: positive/neutral/negative с долями среди оценённых упоминаний. Отдельно — unassessed и not_mentioned; доля всех непустых ответов и обе базы расчёта.
brand_perceptionМатрица атрибут × компания: attribute, polarity, entity_type/id/name, market_score/rank, entities_ranked, responses_with, attribute_responses, entity_mentions. У бренда также association_score и terms. association_score — доля ответов с подтверждённым атрибутом и его знаком среди ответов с упоминанием бренда, включая ответы без характеристик в знаменателе. market_score — доля ответов с этим атрибутом и знаком, где он приписан конкретной компании. Оба показателя в процентах; каждый ответ учитывается один раз. Порядок характеристик и позиция бренда не влияют на скор. Это частота ассоциаций, не оценка качества товара.
presence_summaryУровни присутствия по группе × провайдеру × бренду или конкуренту: total_responses, mentioned_responses, comparison_extracted_responses, leader_count (эталон), primary_count (основная рекомендация), argued_count (с аргументами или при условии), alternative_count (вторичная альтернатива), mention_count (упоминание), absent_count. total_responses включает все непустые ответы на действующие промпты в группе у этого провайдера; у конкурентов absent_count = total_responses − mentioned_responses. Конкурент появляется в сводке, если хотя бы раз упомянут в этом срезе. При truncated: true сводка относится только к полным ответам, вошедшим в perception_responses.
perception_responsesОдна строка на ответ × сущность: бренд (включая отсутствие) и упомянутые активные конкуренты. response_id, prompt_id, prompt_text, cluster_id, cluster, created_at, provider_id/name, entity_id/type/name, presence_level (leader/primary/argued/alternative/mention/absent), level_reason, recommendation, comparison (reference/ahead/on_par/behind/none/null), comparison_extracted, argued, sentiment, standing_note (только бренд), directly_recommended_entities и directly_recommended_entity_ids, stronger_competitors и stronger_competitor_ids. recommendation у бренда — исходный citation_type, у конкурента — direct/conditional/другое исходное значение/null. level_reason: reference — эталон для сравнения, directAhead — прямая рекомендация и превосходство, direct — прямая рекомендация, behind — слабее, negative — негатив, conditional — выбор при условии, argued — аргументы за выбор, rivalDirect — рекомендован другой, mention — упоминание, absent — отсутствие. null comparison означает отсутствие разметки, none — сравнение извлечено, но превосходство не заявлено. Оговорки — формулировки AI, а не проверенные факты. stronger_competitors заполняется только при brand_comparison=behind и сравнении конкурента ahead/reference; прямые рекомендации могут включать несколько сущностей. Правила уровней совпадают с разделом «Восприятие бренда». Непустые ответы на действующие промпты; фильтры периода/провайдеров/промптов учитываются. Полный текст — через responses с includeResponseText по response_id.
competitorsБренд + все отслеживаемые конкуренты, бренд первой строкой. Справочная часть: id (то же пространство, что entity_id в competitor_timeline / brand_perception), name, normalized_name, aliases (все вариации написания, по которым матчатся упоминания), website, domains, is_active, discovery_source, created_at. Метрики за окно выгрузки: mention_count, mention_rate_pct, sov_pct, avg_position, domain_citation_rate_pct. 0 в метрике = посчитано, ни разу не упомянут; null = метрика не посчиталась (см. notes в манифесте).
providersКаталог AI-провайдеров (id, slug, name) — для join'ов с другими датасетами.
daily_timelineБренд-level метрики по дням: ответы, mentions, охват %, SoV %, sentiment counts.
competitor_timelinePer-day × per-entity: бренд + топ-20 конкурентов по дням (long-form). Для multi-line чартов.
provider_timelinePer-day × per-provider: total_responses, brand_mentions, mention_rate%, sov% по каждому AI-провайдеру по дням.
positionПозиция бренда: avg_position, top_1_rate%, top_3_rate%, position_4_plus_rate%.
competitive_gapsПромпты где конкуренты упомянуты, а бренд НЕТ — приоритетный список «здесь теряете долю».
adsРеклама рядом с ответами AI: response_id, prompt_id, формат и место блока, домен рекламодателя и его резолв в бренд/конкурента (advertiser_name, advertiser_type), заголовок, текст и ссылка объявления. Пока только Alice AI, сбор с 5 июля 2026 — ретроспективы нет. Дополнительно: observation_id, provider_id, prompt_text, group_id, source_group_id, source_ad_id, sitelinks (тексты). Наблюдения — обнаруженные блоки, не рекламные показы и не охват.
ad_groupsГруппы объявлений: group_id, advertiser_domain, provider_id/name, ad_type, grouping_basis (order/banner/creative), source_group_id, first_seen, last_seen, observations, days, prompts, variants, banners. Группировка совпадает с разделом «Реклама в AI»; идентификатор источника не подтверждает кампанию в рекламном кабинете.
ad_variantsВарианты объявлений внутри групп: group_id, variant_id, рекламодатель, провайдер, формат, source_group_id/source_ad_id, title, body, target_url, products (JSON-строка), sitelinks (массив текстов), observations, prompts, days.
ad_promptsПромпты по группам объявлений: group_id, рекламодатель, провайдер, формат, prompt_id/text, observations, days, prompts, variants, first_seen, last_seen.
ad_activityАктивность групп по дням (Москва): group_id, рекламодатель, провайдер, формат, date, observations, checks, status (detected/notDetected/notChecked). Не обнаружена — не доказательство отсутствия рекламы; без проверок статус notChecked.
ad_changesИзменения относительно соседнего периода той же длительности: change_id/type, group_id, рекламодатель, провайдер, формат, period (current/previous), observations, prompt_id/text, title, current_start/end, previous_start/end, coverage_changed. Типы: new_group, new_variant, new_prompt, not_seen, not_checked, new_scope. «Впервые» не означает запуск кампании. При отсутствии изменений строк нет; базы сравнения доступны в ad_periods.
ad_periodsБазы сравнения: period (current/previous), start_date/end_date, observations, checks, groups, responses_with_ads, observations_per_100_checks (null без проверок), checked_prompts, coverage_changed. Фильтры одинаковы для обоих периодов; изменение покрытия учитывается отдельно.
shopping_recommendationsТекущие ожидающие проверки, неистёкшие рекомендации Alice AI по каталогам за последние 30 дней: action_id, status, model/key, observations, first_seen/last_seen, shops, evidence_count, lookback_days. Это текущие задачи, не исторический снимок. Фильтры выбирают сохранённые доказательства; число наблюдений и даты пересчитываются по ним. Экспорт не запускает платный анализ.
shopping_evidenceДоказательства рекомендаций: action_id, model, response_id, prompt_id/text, created_at, quote, cards (массив title/title_key/shop/shop_key/url). Хранится до 20 ответов на рекомендацию; observations считает отобранные доказательства, не все наблюдения за всё время. Отсутствие карточки не доказывает отсутствие товара в продаже и не гарантирует появление после правок.
ecommerce_cardsОрганические товарные карточки Alice AI и ChatGPT: response_id, prompt_id, provider_id, created_at, position, title/key, url, shop_name/key, price_text/amount, old_price_amount, currency, rating, review_count, image_url, badge. Учитываются фильтры периода, провайдера и промпта. Рекламные подборки выгружаются отдельно в ads; цены сохранённые, не текущие.

Запрос

Метод и URL

POST /api/v1/analytics/export

Поля запроса

ПолеТипОбяз.Описание
brandIdstring (uuid)✓UUID бренда. Должен принадлежать владельцу токена.
datasetsstring[]✓Массив. Допустимые ключи: prompts, source_domains, source_pages, responses, share_of_voice, sentiment, brand_perception, competitors, providers, daily_timeline, competitor_timeline, provider_timeline, position, competitive_gaps, ads. Минимум один. См. «Каталог датасетов» ниже. Дополнительно доступны presence_summary и perception_responses. В API каждая таблица запрашивается явно.
format"csv" | "json"✓csv или json. Для csv с >1 датасетом будет возвращён zip.
includeResponseTextbooleanОпционально. Если true и выбран датасет responses, добавляет полный текст ответа AI в колонку response_text, а исходный ответ до поиска — в memory_response_text. По умолчанию false.
includeInactivePromptsbooleanОпционально. Если true и выбран датасет prompts, добавляет в него отключённые промпты (status = inactive) с их метриками за период. По умолчанию false — только активные.
filters.startDatestring (ISO)✓ISO-дата начала периода (UTC). Период ≤ 90 дней.
filters.endDatestring (ISO)✓ISO-дата конца периода (UTC).
filters.timeZonestring (IANA)Часовой пояс IANA для дат в имени файла. По умолчанию UTC. Не сдвигает временные фильтры; рекламная активность по дням всегда считается по Москве.
filters.providerIdsstring[] (uuid)Опционально. UUID провайдеров (фильтр).
filters.promptIdsstring[] (uuid)Опционально. UUID промптов (фильтр).

Пример: curl

Замените brandId и токен на свои.

curl -X POST https://geoscout.pro/api/v1/analytics/export \
  -H "Authorization: Bearer gs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "00000000-0000-0000-0000-000000000000",
    "datasets": ["prompts", "responses", "brand_perception", "presence_summary", "perception_responses"],
    "format": "csv",
    "includeResponseText": true,
    "filters": {
      "startDate": "2026-04-01T00:00:00Z",
      "endDate": "2026-04-30T23:59:59Z"
    }
  }' -o export.zip

Ответ

200 OK — тело файла. Файл-имя в заголовке Content-Disposition (RFC 5987).

Полезные заголовки

  • Content-Type — MIME-тип: text/csv, application/zip или application/json
  • Content-Disposition — attachment + UTF-8 имя файла
  • X-Export-Truncated — Список датасетов, где данные были обрезаны своим лимитом строк (CSV-строка ключей). Пусто = всё выгружено целиком.
  • Retry-After — Секунды до сброса rate-limit (только при 429)

Пример: формат JSON

{
  "manifest": {
    "exported_at": "2026-05-24T10:15:00.000Z",
    "brand_id": "...",
    "brand_name": "Acme",
    "format": "json",
    "filters": { ... },
    "datasets": ["prompts", "responses"],
    "include_response_text": true,
    "include_inactive_prompts": false,
    "row_counts": { "prompts": 59, "responses": 640 },
    "truncated": {},
    "notes": {
      "responses": "one row per response; join on prompt_id to the prompts dataset for prompt-level metrics"
    }
  },
  "datasets": {
    "prompts": { "rows": [ ... ], "truncated": false },
    "responses": { "rows": [ ... ], "truncated": false }
  }
}

Коды ошибок

КодHTTPКогда возвращается
invalid_request400Невалидный JSON или Zod-валидация не прошла (см. поле detail)
unauthorized401Токен отсутствует, неверного формата или не найден
token_expired401Срок действия токена истёк
token_revoked401Токен отозван владельцем
insufficient_scope403Токен не имеет scope mcp:read
forbidden403Бренд не принадлежит владельцу токена
rate_limited429Превышен лимит 10 запросов в час
internal500Внутренняя ошибка. Подробности в логах сервера, не в ответе

Пример ответа на ошибку

{
  "error": "rate_limited"
}

Лимиты

  • —Период экспорта: до 90 дней
  • —Строк на датасет: зависит от датасета (например, source_pages до 50 000, responses до 100 000, а с полным текстом ответов — до 10 000). Превышение → данные обрезаны, см. X-Export-Truncated
  • —Rate-limit: 10 запросов в час на пользователя (PAT и OAuth-токены одного юзера разделяют квоту)
  • —Тяжёлые экспорты могут занять 10-30 секунд — таймаут клиента ставьте от 60 секунд