Geliştirici API
API Anahtarı Oluştur
REST API · v1 · Asenkron

GEO Analiz API

ChatGPT, Perplexity, Gemini ve Claude gözünden sitenizin nasıl okunduğunu API ile analiz edin. Her istekte tek AI profili seçilir.

Temel URLhttps://www.spindorai.com/api/public-geo-analysis
OpenAPI JSON

Bu sayfa ve OpenAPI dosyası AI asistanlarına verilebilir — entegrasyon kodunu otomatik üretirler.

5 Adımda Entegrasyon

  1. GEO API anahtarı oluştur

    https://www.spindorai.com/api-keys → GEO Analiz API. Format: sp_geo_…

  2. POST https://www.spindorai.com/api/public-geo-analysis/analyze — X-Spindora-Key + JSON body
  3. task_id ile poll — GET /result/{task_id} her 2–3 sn
  4. profiles[] skorlarını göster — geo_score, recommendations, vb.
  5. Attribution — Powered by Spindora linki zorunlu

Genel Bakış

GEO Analiz API, sayfanızı yapay zeka botlarının (GPTBot, PerplexityBot, GoogleOther, ClaudeBot) gözünden tarar. Her istekte tek profil seçilir; profil bazlı GEO skoru, okunabilirlik, schema kalitesi, güven sinyalleri ve iyileştirme önerileri döner. İstekler Celery kuyruğunda işlenir — önce task_id alınır, sonra sonuç poll edilir.

API key zorunlu

Harici istekler

4 AI profili

chatgpt · perplexity · gemini · claude

Attribution

Zorunlu link

AI Profilleri

Her analiz isteğinde profiles dizisine yalnızca bir profil gönderin. Modeller farklı User-Agent, skor ağırlıkları ve değerlendirme odağı kullandığı için aynı URL farklı skor/öneri üretebilir — bu beklenen davranıştır.

ProfilSimüle edilen botOdak
chatgptGPTBot (OpenAI)Sohbet alıntısı, SSS tarzı net yanıtlar
perplexityPerplexityBotKaynak, tarih, doğrulanabilir derinlik
geminiGoogleOther (Google)Schema, varlık netliği, yapılandırılmış veri
claudeClaudeBot (Anthropic)Uzun açıklama, bağlam, güven/şeffaflık

Kimlik Doğrulama

HeaderX-Spindora-Key: sp_geo_…
BearerAuthorization: Bearer sp_geo_…

Kota & Planlar

  • Aylık kota kullanıcı bazlı — tüm GEO anahtarları paylaşır.
  • Planlar: Free 50 · Starter 100 · Pro 200 · Pro+ 400 · Enterprise 800 / ay.
  • Kalan kota: GET https://www.spindorai.com/api/api-hub/status
  • API yanıtında görsel snapshot döndürülmez.

İstek Akışı

1

POST /analyze

Kuyruğa al

2

GET /result/{id}

~2.5 sn poll

3

200 OK

profiles[] hazır

202 = bekliyor · Analiz 30–120 sn sürebilir

İstek Şeması

AlanTipZorunluAçıklama
urlstring (URL)EvetAnaliz edilecek sayfa
profilesstring[] (length 1)HayırTek profil: chatgpt | perplexity | gemini | claude. Varsayılan: ["chatgpt"]
language"tr" | "en"HayırÖneri/mesaj dili
locale"tr" | "en"HayırHata mesajı dili

Uç Noktalar

POST/analyze

GEO analizini kuyruğa alır.

cURL
curl -X POST "https://www.spindorai.com/api/public-geo-analysis/analyze" \
  -H "Content-Type: application/json" \
  -H "X-Spindora-Key: sp_geo_YOUR_KEY_HERE" \
  -d '{
    "url": "https://example.com",
    "profiles": ["chatgpt"],
    "language": "tr",
    "locale": "tr"
  }'
GET/result/{task_id}

Sonuç poll — aynı API key ile.

cURL
curl "https://www.spindorai.com/api/public-geo-analysis/result/TASK_ID_HERE" \
  -H "X-Spindora-Key: sp_geo_YOUR_KEY_HERE"

JSON Yanıt Örnekleri

POST /analyze (200)

JSON
{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "GEO analiziniz sıraya alındı. Lütfen bekleyin…",
  "mode": "api",
  "attribution": {
    "text": "Powered by Spindora",
    "url": "https://www.spindorai.com",
    "required": true,
    "html": "<a href=\"https://www.spindorai.com\" target=\"_blank\" rel=\"noopener\">Powered by Spindora</a>"
  }
}

GET /result (202)

JSON
{ "status": "pending" }

GET /result (200)

JSON
{
  "success": true,
  "url": "https://example.com",
  "average_geo_score": 72,
  "average_ai_readability_score": 68,
  "average_expertise_score": 61,
  "visual_snapshot_data_url": null,
  "visual_snapshots_data_urls": [],
  "profiles": [
    {
      "profile": "chatgpt",
      "status_code": 200,
      "crawlable": true,
      "crawlability_reason": "Erişilebilir",
      "geo_score": 74,
      "ai_readability_score": 70,
      "expertise_score": 63,
      "schema_score": 55,
      "word_count": 842,
      "found_schemas": ["WebPage", "Organization"],
      "missing_schemas": ["FAQPage"],
      "recommendations": [
        "FAQ schema ekleyin — AI yanıtlarında alıntılanma şansını artırır."
      ],
      "headline_verdict": "İçerik okunabilir; schema derinliği geliştirilebilir.",
      "top_strengths": ["Net H1 yapısı", "Yeterli kelime sayısı"],
      "top_gaps": ["FAQ yapısı eksik", "Güven sinyalleri zayıf"],
      "quick_wins": ["Meta description güncelleyin", "Yazar bilgisi ekleyin"]
    }
  ],
  "attribution": {
    "text": "Powered by Spindora",
    "url": "https://www.spindorai.com",
    "required": true
  }
}

Attribution (Zorunlu)

<a href="https://www.spindorai.com" target="_blank" rel="noopener noreferrer">
  Powered by Spindora
</a>

Kod Örnekleri

JavaScript

const API = 'https://www.spindorai.com/api/public-geo-analysis';
const KEY = 'sp_geo_YOUR_KEY_HERE';

async function analyzeGeo(url) {
  const start = await fetch(`${API}/analyze`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Spindora-Key': KEY,
    },
    body: JSON.stringify({
      url,
      profiles: ['chatgpt'],
      language: 'tr',
      locale: 'tr',
    }),
  });
  if (!start.ok) throw new Error(await start.text());
  const { task_id } = await start.json();

  for (let i = 0; i < 90; i++) {
    await new Promise((r) => setTimeout(r, 2500));
    const res = await fetch(`${API}/result/${task_id}`, {
      headers: { 'X-Spindora-Key': KEY },
    });
    if (res.status === 202) continue;
    if (!res.ok) throw new Error(await res.text());
    return res.json();
  }
  throw new Error('Timeout');
}

Python

import time
import requests

API = "https://www.spindorai.com/api/public-geo-analysis"
KEY = "sp_geo_YOUR_KEY_HERE"
HEADERS = {"X-Spindora-Key": KEY}

def analyze_geo(url: str) -> dict:
    r = requests.post(
        f"{API}/analyze",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "url": url,
            "profiles": ["chatgpt"],
            "language": "tr",
            "locale": "tr",
        },
        timeout=30,
    )
    r.raise_for_status()
    task_id = r.json()["task_id"]

    for _ in range(90):
        time.sleep(2.5)
        poll = requests.get(f"{API}/result/{task_id}", headers=HEADERS, timeout=30)
        if poll.status_code == 202:
            continue
        poll.raise_for_status()
        return poll.json()
    raise TimeoutError("GEO analysis timed out")

Yanıt Alanları

  • average_geo_score — Profil ortalaması GEO skoru (0–100)
  • profiles[] — Profil bazlı detay: geo_score, recommendations, found_schemas, top_gaps, quick_wins…
  • visual_snapshots_data_urls — API'de her zaman []
  • attribution — Zorunlu gösterim

Hata Kodları

HTTPAnlam
401Geçersiz API key
403Plan süresi dolmuş
429Aylık kota doldu
202Analiz devam ediyor
500Analiz/kuyruk hatası

Entegrasyon Kontrol Listesi

  • ✓sp_geo_ anahtarı oluşturuldu
  • ✓POST /analyze sonrası poll döngüsü kuruldu
  • ✓202 → bekleyip 200 gelince parse ediliyor
  • ✓Snapshot beklenmiyor
  • ✓Attribution UI'da görünür
  • ✓429 için plan yükseltme mesajı

AI / LLM için özet

AI prompt
# Spindora GEO Analiz API — Entegrasyon Özeti

Base URL: https://www.spindorai.com/api/public-geo-analysis
Dokümantasyon: https://www.spindorai.com/developers/geo-analysis-api
OpenAPI JSON: https://www.spindorai.com/developers/geo-analysis-api.openapi.json
API Key: Kayıt ol → giriş yap → https://www.spindorai.com/api-keys → GEO Analiz API sekmesi (sp_geo_*)

## Kimlik doğrulama
Header: X-Spindora-Key: sp_geo_YOUR_KEY
Alternatif: Authorization: Bearer sp_geo_YOUR_KEY

## Akış (asenkron)
1. POST /analyze → body: {"url":"https://example.com","profiles":["chatgpt"],"language":"tr","locale":"tr"}
2. task_id al
3. GET /result/{task_id} — 2–3 sn aralıkla poll
4. HTTP 202 = devam, HTTP 200 = sonuç

## Profiller (tek seçim)
chatgpt | perplexity | gemini | claude — her biri farklı bot User-Agent ve skorlama odağı ile tarar; aynı sayfada farklı skor/öneri üretebilir

## Kota (aylık, kullanıcı bazlı)
Free 50 | Starter 100 | Pro 200 | Pro+ 400 | Enterprise 800
Kalan: GET https://www.spindorai.com/api/api-hub/status (JWT)

## API kısıtları
- visual_snapshots API'de boş/null
- attribution zorunlu: Powered by Spindora

## Hata kodları
401 key | 403 plan | 429 kota | 202 bekliyor | 500 hata

OpenAPI: https://www.spindorai.com/developers/geo-analysis-api.openapi.json