Данные KleoGEO в ваших системах

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

1. 1

   Создайте ключ

   Откройте API-ключи в кабинете и создайте ключ с нужными правами. Ключ показывается один раз — сохраните его в хранилище секретов, а не в коде.

2. 2

   Передайте ключ в запросе

   Передавайте ключ в заголовке каждого запроса. Принимаются только API-ключи: пароль и вход через браузер здесь не работают.

   Authorization: Bearer geo_live_…

3. 3

   Сделайте первый запрос

   Проверьте ключ: GET /v1/me вернёт организацию, лимиты тарифа и права ключа.

   curl https://api.kleogeo.ru/v1/me \
     -H "Authorization: Bearer $KLEOGEO_API_KEY"

Примеры

curl https://api.kleogeo.ru/v1/projects \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

curl "https://api.kleogeo.ru/v1/projects/$PROJECT_ID/metrics/visibility?granularity=week&from=2026-09-01" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

{
  "analyzer_version": "0.4.0",
  "series": [
    {
      "brand_id": "0199e8a4-1f6b-7c2e-9a41-3d5b7f0c2a11",
      "brand_name": "Acme",
      "is_primary": true,
      "points": [
        {
          "t": "2026-10-06", "provider": "all",
          "n": 150, "mentioned": 63,
          "share": 0.42, "ci_low": 0.344, "ci_high": 0.5
        }
      ]
    }
  ]
}

curl -fSL -o mentions.csv \
  "https://api.kleogeo.ru/v1/projects/$PROJECT_ID/exports/mentions.csv?from=2026-09-01" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

curl -X POST "https://api.kleogeo.ru/v1/projects/$PROJECT_ID/runs" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

# then check the status
curl "https://api.kleogeo.ru/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $KLEOGEO_API_KEY"

Права ключа

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

GET /v1/me доступен любому действующему ключу. Не хватает права — ответ 403 insufficient_scope.

Лимиты и повторы

• 10 запросов в секунду на ключ (кратковременно до 20) и общий лимит организации 20 в секунду.
• Каждый ответ показывает лимит ключа: RateLimit-Policy: "api-key";q=20;w=2 и RateLimit: "api-key";r=17;t=1 — сколько запросов осталось (r) и через сколько секунд лимит восстановится (t).
• Сверх лимита — 429 rate_limited с заголовком Retry-After (секунды). Подождите указанное время и повторите.
• 503 server_busy и 503 upstream_timeout тоже несут Retry-After: GET-запросы безопасно повторять, POST — с тем же Idempotency-Key.
• Тело запроса — не больше 1 МБ. Повторяющиеся GET-ответы можно не скачивать заново: отправьте If-None-Match со значением ETag и получите 304.

Ошибки

Все ошибки приходят в одном формате. Опирайтесь на code — он не меняется; message — пояснение на английском для логов. Иногда в объекте есть детали, например limit и current.

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests, slow down"
  }
}

Соглашения