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_timeline | Per-day × per-entity: бренд + топ-20 конкурентов по дням (long-form). Для multi-line чартов. |
| provider_timeline | Per-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
Поля запроса
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| brandId | string (uuid) | ✓ | UUID бренда. Должен принадлежать владельцу токена. |
| datasets | string[] | ✓ | Массив. Допустимые ключи: 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. |
| includeResponseText | boolean | Опционально. Если true и выбран датасет responses, добавляет полный текст ответа AI в колонку response_text, а исходный ответ до поиска — в memory_response_text. По умолчанию false. | |
| includeInactivePrompts | boolean | Опционально. Если true и выбран датасет prompts, добавляет в него отключённые промпты (status = inactive) с их метриками за период. По умолчанию false — только активные. | |
| filters.startDate | string (ISO) | ✓ | ISO-дата начала периода (UTC). Период ≤ 90 дней. |
| filters.endDate | string (ISO) | ✓ | ISO-дата конца периода (UTC). |
| filters.timeZone | string (IANA) | Часовой пояс IANA для дат в имени файла. По умолчанию UTC. Не сдвигает временные фильтры; рекламная активность по дням всегда считается по Москве. | |
| filters.providerIds | string[] (uuid) | Опционально. UUID провайдеров (фильтр). | |
| filters.promptIds | string[] (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/jsonContent-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_request | 400 | Невалидный JSON или Zod-валидация не прошла (см. поле detail) |
| unauthorized | 401 | Токен отсутствует, неверного формата или не найден |
| token_expired | 401 | Срок действия токена истёк |
| token_revoked | 401 | Токен отозван владельцем |
| insufficient_scope | 403 | Токен не имеет scope mcp:read |
| forbidden | 403 | Бренд не принадлежит владельцу токена |
| rate_limited | 429 | Превышен лимит 10 запросов в час |
| internal | 500 | Внутренняя ошибка. Подробности в логах сервера, не в ответе |
Пример ответа на ошибку
{
"error": "rate_limited"
}Лимиты
- —Период экспорта: до 90 дней
- —Строк на датасет: зависит от датасета (например, source_pages до 50 000, responses до 100 000, а с полным текстом ответов — до 10 000). Превышение → данные обрезаны, см. X-Export-Truncated
- —Rate-limit: 10 запросов в час на пользователя (PAT и OAuth-токены одного юзера разделяют квоту)
- —Тяжёлые экспорты могут занять 10-30 секунд — таймаут клиента ставьте от 60 секунд