Ölçümleriniz, kendi araçlarınızda.

Anahtarınızı panelde Ayarlar → API bölümünden oluşturun. Anahtarın tamamı yalnızca oluşturulduğu anda gösterilir; biz yalnızca özetini saklarız. Anahtarı her istekte Authorization başlığında gönderin. Bir anahtar, ait olduğu çalışma alanındaki tüm markaları okuyabilir ve hiçbir veriyi değiştiremez.

curl -H "Authorization: Bearer $BIGEO_API_KEY" \
  https://bigeo.io/api/v1/brands

• Anahtarı tarayıcıda çalışan kodda ya da herkese açık depolarda tutmayın; sunucu tarafında ortam değişkeni olarak saklayın.
• Bir anahtarın sızdığından şüphelenirseniz Ayarlar → API bölümünden iptal edin; iptal anında geçerli olur.
• Her entegrasyon için ayrı anahtar kullanırsanız son kullanım zamanını entegrasyon bazında izleyebilirsiniz.

Temel adres https://bigeo.io/api/v1. Tüm uç noktalar GET ile çağrılır ve JSON döner.

• locale: okunacak seri (ör. tr-TR). Vermezseniz markanın ilk serisi kullanılır; yanıt hangi serinin döndüğünü belirtir.
• days: şu anda biten pencerenin uzunluğu; 7, 30, 90 olabilir, varsayılan 30.
• engine: chatgpt, gemini, perplexity, google_ai_mode.
• mentioned: true yalnızca markanızın anıldığı, false anılmadığı yanıtları getirir.
• limit ve cursor: yanıtlar en yeniden eskiye sayfalanır; sayfa başına varsayılan 25, en fazla 100 kayıt. Sonraki sayfa için yanıttaki next_cursor değerini cursor olarak gönderin.

Oranlar 0 ile 1 arasındadır. Her oranın yanında %95 Wilson güven aralığı (ci95) ve örneklem büyüklüğü (n) bulunur. Örneklem min_sample değerinin altındaysa sufficient_sample yanlış döner; bu sayıyı tek başına yorumlamayın. Zaman damgaları ISO 8601 biçiminde ve UTC’dir. Marka adını içeren promptların yanıtları oranlara katılmaz.

curl -H "Authorization: Bearer $BIGEO_API_KEY" \
  "https://bigeo.io/api/v1/brands/{brandId}/metrics?locale=tr-TR&days=30"

{
  "data": {
    "brand_id": "6f1c2c1e-8a4b-4f0e-9d53-2b7a51c0a911",
    "locale": "tr-TR",
    "window": { "days": 30, "from": "2026-10-11T09:00:00.000Z", "to": "2026-11-10T09:00:00.000Z" },
    "last_measured_at": "2026-11-10T06:12:44.000Z",
    "min_sample": 30,
    "visibility": {
      "rate": 0.3412,
      "ci95": { "low": 0.3107, "high": 0.3731 },
      "n": 864,
      "sufficient_sample": true
    },
    "visibility_index": { "value": 27.4, "low": 24.6, "high": 30.3, "formula_version": "v1.0" },
    "share_of_voice": { "rate": 0.2218, "ci95": { "low": 0.2011, "high": 0.2440 }, "n": 1420,
                        "sufficient_sample": true, "brand_mentions": 315, "total_mentions": 1420 },
    "average_position": { "mean": 2.31, "ci95": { "low": 2.13, "high": 2.49 }, "n": 295 },
    "citation_rate": { "rate": 0.0891, "ci95": { "low": 0.0719, "high": 0.1100 }, "n": 864, "sufficient_sample": true },
    "baseline": {
      "prompt_set_version": 1,
      "window": { "from": "2026-09-09T08:00:00.000Z", "to": "2026-09-16T08:00:00.000Z" },
      "visibility": { "rate": 0.2847, "ci95": { "low": 0.2401, "high": 0.3339 }, "n": 288, "sufficient_sample": true },
      "visibility_index": 22.9,
      "visibility_change": { "diff": 0.0565, "ci95": { "low": -0.0021, "high": 0.1118 }, "significance": "none" },
      "visibility_index_change": 4.5
    },
    "engines": [
      {
        "engine": "chatgpt",
        "name": "ChatGPT",
        "model_version": "…",
        "visibility": { "rate": 0.4074, "ci95": { "low": 0.3193, "high": 0.5019 }, "n": 108, "sufficient_sample": true },
        "average_position": 2.05,
        "citation_rate": { "rate": 0.1111, "ci95": { "low": 0.0648, "high": 0.1843 }, "n": 108, "sufficient_sample": true },
        "baseline_visibility": 0.3333,
        "change_significance": "none",
        "last_measured_at": "2026-11-10T06:12:44.000Z"
      }
    ]
  }
}

baseline, prompt setiniz dondurulduktan sonraki ilk 7 günle karşılaştırmadır; significance alanı up, down, none ya da insufficient olur. Hesaplamaların tamamı metodoloji sayfasında yayımlanır.

curl -H "Authorization: Bearer $BIGEO_API_KEY" \
  "https://bigeo.io/api/v1/brands/{brandId}/answers?locale=tr-TR&mentioned=true&limit=1"

{
  "locale": "tr-TR",
  "data": [
    {
      "id": "0b9f6a52-3d0e-4f6c-a0f1-0c8a4f1d2e77",
      "created_at": "2026-11-10T06:12:44.000Z",
      "engine": "chatgpt",
      "model_version": "…",
      "access_method": "official_api",
      "prompt": { "id": "…", "text": "İstanbul'da en iyi saç ekimi kliniği hangisi?", "intent": "discovery" },
      "repetition": 2,
      "text": "İstanbul'da öne çıkan klinikler arasında …",
      "counted_in_metrics": true,
      "brand": { "mentioned": true, "position": 2, "sentiment": "positive", "own_domain_cited": false },
      "competitors_mentioned": [{ "id": "…", "name": "…", "position": 1, "sentiment": "neutral" }],
      "citations": [{ "url": "https://…", "domain": "…", "title": "…", "position": 1, "own_domain": false }]
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMS0xMFQwNjoxMjo0NC4wMDAwMDBafDBiOWY2YTUyLTNkMGUtNGY2Yy1hMGYxLTBjOGE0ZjFkMmU3Nw"
}

has_more doğruysa next_cursor değerini değiştirmeden bir sonraki isteğe ekleyin. Görev başlıkları, denetim önerileri ve prompt metinleri panelde yazıldıkları dilde döner; alan adları ve kodlar her zaman İngilizcedir.

{ "error": { "code": "not_found", "message": "Brand not found." } }

Hata mesajları İngilizcedir. Başka bir çalışma alanına ait marka kimliği, hiç var olmayan bir kimlikle aynı yanıtı (404) alır.

Sınır anahtar başınadır ve REST ile MCP istekleri birlikte sayılır. Her yanıtta kalan hakkınızı gösteren başlıklar bulunur. Sınırı aştığınızda 429 döner; Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1794300060   # pencerenin biteceği an (Unix saniyesi)

Ölçümler en sık günde bir kez yenilendiği için aynı veriyi dakikada birden fazla çekmeniz gerekmez; yanıtları kendi tarafınızda önbelleğe alın. Yanıtlar Cache-Control: no-store ile gelir.

MCP (Model Context Protocol) destekleyen asistanlar biGeo verinizi doğrudan sorgulayabilir: “Geçen ay hangi motorda görünürlüğümüz düştü?” gibi bir soruyu asistan araçları çağırarak yanıtlar. Sunucu adresi https://bigeo.io/api/mcp; aynı API anahtarı kullanılır, araçlar salt okunurdur.

{
  "mcpServers": {
    "bigeo": {
      "type": "http",
      "url": "https://bigeo.io/api/mcp",
      "headers": {
        "Authorization": "Bearer bg_live_…"
      }
    }
  }
}

Alan adları istemciden istemciye değişebilir; gereken iki bilgi sunucu adresi ve Authorization: Bearer başlığıdır. Aktarım Streamable HTTP’dir ve durumsuzdur: her mesaj ayrı bir POST isteğidir, yanıt tek bir JSON nesnesidir, oturum tutulmaz. Desteklenen protokol sürümleri: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26.

curl -X POST https://bigeo.io/api/mcp \
  -H "Authorization: Bearer $BIGEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: get_visibility" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_visibility",
      "arguments": { "brand_id": "<marka kimliği>", "locale": "tr-TR", "days": 30 },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "ornek-istemci", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Araç sonucu, REST yanıtıyla aynı JSON’u metin içeriği olarak taşır. Geçersiz parametre ya da bulunamayan marka gibi durumlar isError: true ile araç sonucu olarak, bilinmeyen yöntem ya da araç ise JSON-RPC hatası olarak döner.