seoGeo — SEO ve GEO denetim aracı

English · Türkçe

Bir web sitesini tarayıp teknik SEO ve GEO (Generative Engine Optimization: ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews gibi yapay zeka cevap motorlarında görünürlük) açısından inceler. Bağlanırsa PageSpeed Insights, Google Search Console ve GA4 verilerini de ekler. Sonuçta kural tabanlı, önceliklendirilmiş bir aksiyon planı ve HTML rapor üretir.

Kurulum

python3 -m venv .venv
.venv/bin/pip install -e '.[all]'      # yalnızca tarama/denetim için: pip install -e .
cp .env.example .env                    # anahtarları buraya yazın

Kullanım

# Tam denetim: tarama + (varsa) GSC/GA4/PageSpeed + aksiyon planı + HTML rapor
.venv/bin/seogeo audit ornek.com -n 100 --html rapor.html -o denetim.json --save

# Kayıtlı denetimi yeniden taramadan aç / filtrele
.venv/bin/seogeo audit -f denetim.json --only geo -s warning --all

# İki denetimi karşılaştır: yeni/çözülen sorunlar + skor değişimi
.venv/bin/seogeo diff -f denetim.json                     # önceki = geçmişteki son kayıt
.venv/bin/seogeo diff -f yeni.json -p eski.json           # açıkça karşılaştır

# Kayıtlı denetimden HTML rapor
.venv/bin/seogeo report -f denetim.json -o rapor.html

# PDF rapor (bilgisayardaki Chrome ile; --html de .pdf uzantısını tanır)
.venv/bin/seogeo report -f denetim.json -o rapor.pdf
.venv/bin/seogeo audit ornek.com --html rapor.pdf

# Denetimden düzeltme dosyaları: llms.txt, JSON-LD şemaları, meta önerileri
.venv/bin/seogeo audit ornek.com -o denetim.json && .venv/bin/seogeo fixes -f denetim.json -o fixes/

# Rakip karşılaştırma: aynı ölçütlerle yan yana
.venv/bin/seogeo compare sitem.com rakip.com -n 30

# İçerik brief: GSC sorularından yazar dosyası (rakip kıyası opsiyonel)
.venv/bin/seogeo brief -f denetim.json -c rakip.json -o briefs/

# Çok müşteri: sıralı denetim + rapor dosyaları + skor düşüşü bildirimi
.venv/bin/seogeo batch musteriler.json -o raporlar/

# Sunucu loglarında gerçek AI bot trafiği
.venv/bin/seogeo logs /var/log/nginx/access.log --days 28

# CI kapısı: SARIF/JUnit çıktısı + skor eşiği (GitHub Actions örneği aşağıda)
.venv/bin/seogeo audit ornek.com --format sarif -o denetim.sarif --fail-on warning

# Web paneli: denetim başlatma, raporlar, skor geçmişi, zamanlanmış denetim
.venv/bin/seogeo serve            # http://127.0.0.1:8000

# MCP sunucusu: Claude'a bağlayın → "sitemin GEO durumu ne?"
# claude mcp add seogeo -- /yol/.venv/bin/seogeo mcp

Önemli seçenekler (seogeo audit --help):

Periyodik takip için paneldeki "Zamanlanmış denetim" formunu kullanabilirsiniz (panel açık kaldığı sürece çalışır) ya da seogeo audit ... --save komutunu cron ile koşturabilirsiniz; panelde site sayfası skorların zaman içindeki değişimini gösterir. İki kayıt arasındaki farkı panelde rapor üstündeki "Öncekiyle farkı" bağlantısından veya seogeo diff ile görürsünüz.

Veri kaynaklarını bağlama

PageSpeed, Search Console ve GA4 entegrasyonları ücretsizdir ve faturalandırma hesabı / kredi kartı gerektirmez (PageSpeed: 25.000 sorgu/gün; Search Console ve GA4 Data API: kota dahilinde ücretsiz). Bunların dışındaki AI görünürlük testi isteğe bağlıdır ve kendi anahtarınızla ücretli bir LLM API'si kullanabilir.

Performans ölçümü (iki seçenek)

• Anahtarsız — yerel Lighthouse: PAGESPEED_API_KEY yoksa araç bilgisayarınızdaki Chrome ile Lighthouse çalıştırır (Node.js gerekir; ilk kullanımda npx resmi lighthouse paketini indirir). Yalnızca laboratuvar verisi üretir. Zorlamak için: --psi-engine local.
• PageSpeed Insights API (önerilir): gerçek kullanıcı Core Web Vitals verisini de getirir. Google anahtarsız kullanım kotasını kaldırdı; ücretsiz anahtar gerekir:
  1. Google Cloud Console → yeni proje (faturalandırma gerekmez)
  2. "API'ler ve Hizmetler" → Kitaplık → PageSpeed Insights API → Etkinleştir
  3. Kimlik bilgileri → Kimlik bilgisi oluştur → API anahtarı → anahtarı yalnızca bu API ile sınırlayın → .env içinde PAGESPEED_API_KEY=

Ölçüm sayfa başına ~20-40 sn sürer. Sayfalar trafiğe (GSC/GA4) göre, yoksa ana sayfa ve sığ sayfalar arasından seçilir.

Google Search Console ve GA4

Aynı Cloud projesinde Google Search Console API ve Google Analytics Data API'yi etkinleştirin. Sonra iki yöntemden birini seçin:

A) Servis hesabı (otomasyon / sunucu için önerilir)

1. IAM → Servis hesapları → hesap oluştur → Anahtarlar → JSON indir
2. Search Console → Ayarlar → Kullanıcılar ve izinler → servis hesabının e-postasını ekleyin
3. GA4 → Yönetici → Mülk erişim yönetimi → aynı e-postayı Görüntüleyen olarak ekleyin
4. .env: SEOGEO_GOOGLE_CREDENTIALS=/yol/servis-hesabi.json

B) Kendi Google hesabınızla (OAuth) — not: OAuth izin ekranı "Test" durumundayken Google yenileme token'larını 7 günde geçersiz kılar; bu durumda haftada bir seogeo google-login gerekir. Bu yüzden düzenli kullanım için servis hesabı daha pratiktir.

1. Kimlik bilgileri → OAuth istemci kimliği → uygulama türü Masaüstü uygulaması → JSON indir
2. .env: SEOGEO_GOOGLE_CREDENTIALS=/yol/client_secret.json
3. Bir kez giriş yapın: .venv/bin/seogeo google-login (token ~/.seogeo/ altına kaydedilir)

GA4 mülk kimliği: GA4 → Yönetici → Mülk ayarları → "Mülk kimliği" → SEOGEO_GA4_PROPERTY=

AI görünürlük testi (isteğe bağlı)

Teknik GEO sinyallerinin ötesinde, sitenin cevap motorlarında gerçekten anılıp anılmadığını ölçer: sayfa başlıklarınızdan örnek sorular üretilir, her soru temiz bir oturumda sorulur ve cevapta alan adınız geçip geçmediğine bakılır. Sonuç raporda ve ai-visibility-low kuralında görünür.

OpenAI uyumlu herhangi bir sohbet API'si çalışır (OpenAI, OpenRouter, yerel sunucu…):

SEOGEO_AI_API_KEY=...
SEOGEO_AI_BASE_URL=https://api.openai.com/v1     # varsayılan
SEOGEO_AI_MODEL=gpt-4o-mini                      # varsayılan
SEOGEO_AI_QUESTIONS=3                            # anahtar varken soru sayısı (0: kapalı)

Anahtar tanımlıyken audit varsayılan olarak 3 soru sorar; --ai-visibility 0 ile kapatıp --ai-visibility 5 ile artırabilirsiniz. Test, API anahtarınız olan bir servise soru başına istek atar; maliyeti sağlayıcınız belirler.

İkinci motor — Perplexity (gerçek alıntı): PERPLEXITY_API_KEY tanımlarsanız her soru iki motora sorulur. Perplexity, cevapta hangi URL'lerin alıntılandığını birebir döndürür — raporda soru başına motor çipleri ve "alıntı ↗" bağlantıları görünür, kart üstünde motor başına görünürlük yüzdesi listelenir.

Skor düşüşü bildirimleri (isteğe bağlı)

Denetim kaydedilirken önceki kayıtla karşılaştırılır; bir alan skoru eşiği kadar düşerse webhook'a JSON gönderilir ve/veya e-posta gider:

SEOGEO_NOTIFY_WEBHOOK=https://hooks.sirket.com/seogeo     # Slack/Discord/genel webhook
SEOGEO_NOTIFY_EMAIL=duyru@example.com                     # virgülle birden çok
SEOGEO_NOTIFY_SCORE_DROP=5                                # bildirim eşiği (puan)

# E-posta için SMTP (port 465: SSL, 587: STARTTLS)
SEOGEO_SMTP_HOST=smtp.example.com
SEOGEO_SMTP_USER=...  SEOGEO_SMTP_PASS=...  SEOGEO_SMTP_FROM=...

CLI'da audit --save --notify, panelde zamanlanmış denetimler otomatik bildirim yapar. Eşik aşılmadıysa hiçbir şey gönderilmez.

PDF raporu

--html çıktısı .pdf ile bitince rapor, bilgisayarınızdaki Chrome/Chromium ile PDF'e çevrilir (ek bağımlılık yok; Lighthouse'un kullandığı Chrome bulunur). Chrome yolu standart konumlardan değilse SEOGEO_CHROME=/yol/chrome ile verin. Panelde rapor üstünde "PDF indir" bağlantısı da aynı yöntemi kullanır.

Varlık (entity) denetimi

Marka, bilgi grafiğinde var mı? Her denetimde marka adı çıkarılıp (kurum şeması > başlık > host) Wikidata ve Vikipedi'de aranır; iki kaynakta da yoksa entity-web-missing bilgisi üretir. Kapatmak için --no-entity-probe veya SEOGEO_ENTITY_PROBE=0.

Render denetimi (diferansiyel)

AI tarayıcıları JS çalıştırmaz; Google çalıştırır. Chrome varsa ana sayfa + ilk içerik sayfaları headless render edilir ve ham HTML ile karşılaştırılır:

• js-render-empty (kritik): ham HTML'de anlamlı metin yok — AI botlar sayfayı boş görüyor
• js-render-gap (uyarı): render edilmiş DOM belirgin şekilde daha zengin — ana içerik JS'e bağımlı

Raporda sayfa sayfa "ham kelime vs render kelime" tablosu çıkar. Kapatmak için --no-render-probe veya SEOGEO_RENDER_PROBE=0; Chrome yolu için SEOGEO_CHROME, sayfa başına JS bekleme süresi için SEOGEO_RENDER_WAIT (ms).

Düzeltme üreteci

seogeo fixes -f denetim.json -o fixes/ denetimden uygulanabilir dosyalar üretir: llms.txt (tarama verisinden), eksik Organization/Article/FAQPage JSON-LD taslakları (veriyle doldurulur, kalanlar yer tutucu) ve meta-onerileri.md (uzun/kısa/eksik title ve description için sayfa sayfa somut öneriler). Yer tutucuları doldurup uygulayın.

Rakip karşılaştırma

seogeo compare sitem.com rakip.com -n 30 aynı kural motoruyla birden çok siteyi tarayıp yan yana tablo verir: skorlar, AI bot engelleri, llms.txt, kurum şeması, şemasız sayfa %, soru başlığı olmayan sayfa %. Panelde /compare sayfası kayıtlı sitelerin son durumunu listeler.

CI kapısı (SARIF / JUnit / GitHub Actions)

# .github/workflows/geo.yml
- run: pip install -e '.[all,dev]'
- run: seogeo audit example.com -n 100 --format sarif -o denetim.sarif --fail-on warning
- uses: github/codeql-action/upload-sarif@v3   # isteğe bağlı: SARIF'i Security sekmesine yükle
  with: { sarif_file: denetim.sarif }

--fail-on critical|warning bu önemde sorun varsa, --fail-under 60 herhangi bir alan skoru düşükse komut 1 ile çıkar; --format junit Jenkins/GitLab'a, --format github Actions günlüğüne ::error/::warning satırları yazar.

MCP sunucusu

seogeo mcp stdio üzerinden MCP konuşur; Claude gibi istemcilere üç araç verir: run_audit (hızlı denetim), list_audits, get_audit. Kurulum: claude mcp add seogeo -- /yol/.venv/bin/seogeo mcp → "sitemin GEO durumu ne, en üst aksiyon ne?" sorularını doğrudan asistana sorabilirsiniz.

Çok dil desteği (i18n)

SEOGEO_LANG=en ile tüm kural başlıkları, çözüm önerileri, kategoriler, önem etiketleri, CLI durum/ilerleme mesajları ve rapor başlıkları İngilizce üretilir (103 kuralın tamamı çevrilidir); varsayılan Türkçe'dir. Panel şablonları bu sürümde Türkçe kalır.

Depolama: SQLite (ajans ölçeği)

Onlarca müşteri × haftalık denetimlerde JSON dosyaları yerine tek veritabanı:

SEOGEO_STORAGE=sqlite   # geçmiş ~/.seogeo/seogeo.db dosyasına yazılır

API/panel/diff/tüm komutlar aynı şekilde çalışır; JSON indirme ucu her iki modda da aynı biçimi döndürür.

Ajans modu (white-label)

Raporlarda "seoGeo" yerine kendi markanız: SEOGEO_REPORT_BRAND=Ajans Adı, alt nota ek metin: SEOGEO_REPORT_FOOTER=.... HTML ve PDF çıktıları bunu kullanır.

Lead magnet API (başka sistemle entegrasyon)

Panelde /lead sayfası ve programatik uç nokta: potansiyel müşterinin sitesine 10 sayfalık hızlı denetim (~40 sn) attırıp satışa hazır özet alın — harf notu, skorlar, ilk 3 hızlı kazanç ve tek cümlelik değerlendirme:

curl -s http://localhost:8000/api/lead-audit \
  -H 'Content-Type: application/json' \
  -d '{"url": "musteri.com", "max_pages": 10}'

{
  "url": "https://musteri.com/", "host": "musteri.com", "grade": "C",
  "scores": {"seo": 72, "geo": 41, "perf": null, "traffic": null},
  "critical": 2, "warning": 11, "pages": 10,
  "quick_wins": [{"title": "llms.txt yok", "effort": "Düşük", "affected": "site geneli",
                  "recommendation": "llms.txt, sitenin özetini…"}],
  "ai_bots": {"allowed": 9, "blocked": 4, "total": 13},
  "summary": "Siteniz teknik SEO'da iyileştirmeye açık (72/100) ama AI cevap motorlarında …",
  "audit_id": "musteri.com_20261006-…", "report_url": "/audits/musteri.com_20261006-…"
}

• GET /api/lead-audit?url=… varyantı no-code araçlar için; save: false ile geçmişi işgal etmez
• SEOGEO_API_TOKEN tanımlarsanız uç nokta X-Api-Token başlığı ister
• Eşzamanlı denetim 2 ile sınırlı, sayfa sayısı 5–25 aralığına sıkıştırılır
• /lead sayfası form + sonuç kartı biçiminde hazır landing demosudur; kendi landing sayfanıza POST /api/lead-audit çağrısıyla gömebilirsiniz

Ayrıca CLI'ı subprocess ile çalıştırıp --format json çıktısını kendi sisteminizde işleyebilir, skor düşüşü webhook'larını CRM'inize bağlayabilirsiniz.

REST API

Panelin tüm işlevleri JSON uç noktalarıyla da vardır (panelde /api-docs sayfası):

GET    /api/audits?host=&limit=    kayıtlı denetimler (meta)
GET    /api/audits/{id}            skorlar, sayılar, üst aksiyonlar
POST   /api/jobs                   arka planda denetim başlat → 202 {job_id}
GET    /api/jobs/{id}              iş durumu (running|done|error, audit_id)
GET    /api/sites                  her sitenin son denetim özeti
GET    /api/schedules              zamanlanmış denetimler
POST   /api/schedules              ekle/güncelle {"url", "interval_hours", ...}
DELETE /api/schedules/{id}         sil

Tümü SEOGEO_API_TOKEN tanımlıysa X-Api-Token başlığı ister (panel token'ından ayrıdır).

AI görünürlük geçmişi

--ai-visibility ile çalıştırılan her denetim, soru bazlı alıntılanma sonucunu saklar. Site geçmişi sayfasında soru × tarih matrisi (✓/✗) ve kolon başına görünürlük yüzdesi gösterilir — müşteriye "3 ayda ş sorunlarında alıntılanmaya başladık" diyebileceğiniz kanıt grafiği budur.

Neler denetleniyor?

Skorlar dört alanda ayrı ayrı hesaplanır. Dış veriye dayanan alanlar ancak o veri bağlıysa puanlanır.

Aksiyon planı: her sorun için etki = önem × etkilenen sayfaların trafik ağırlığı, öncelik = etki ÷ efor hesaplanır. Böylece çok trafik alan sayfalardaki kolay düzeltilebilir kritik sorunlar en üste çıkar. Rapor ayrıca "hızlı kazanımlar" ve sayfa bazında yapılacaklar listesi içerir.

Proje yapısı

seogeo/
  crawler.py, parser.py, sitefiles.py   tarama, HTML ayrıştırma, robots/sitemap/llms.txt, AI bot testi
  aibots.py                             AI tarayıcı listesi (token, sahibi, amacı)
  checks/                               kurallar: technical, geo, performance, traffic (+ base: altyapı/skor)
  integrations/                         pagespeed, google_auth, search_console, analytics,
                                        ai_visibility (GSC sorulu), entity (Wikidata/Vikipedi),
                                        rendering (ham vs render DOM)
  pipeline.py                           tarama → varlık → GSC/GA4 → PageSpeed → AI görünürlük → kurallar
  plan.py                               önceliklendirme
  diff.py                               iki denetim arasındaki fark
  fixes.py                              düzeltme dosyaları: llms.txt, JSON-LD, meta önerileri
  compare.py                            rakip/site karşılaştırma tablosu
  ci.py                                 SARIF / JUnit / GitHub Actions çıktıları + skor kapısı
  mcp.py                                MCP sunucusu (run_audit, list_audits, get_audit)
  notify.py                             skor düşüşü bildirimleri (webhook + e-posta)
  pdf.py                                HTML raporu Chrome ile PDF'e çevirme
  report.py + templates/                HTML rapor ve panel şablonları
  storage.py, web/app.py                denetim geçmişi, işler/zamanlama ve FastAPI paneli

Yeni kural eklemek için checks/ altındaki bir modülde rule(...) ile tanımlayıp @page_check, @content_check veya @site_check ile kontrol fonksiyonu yazmanız yeterli.

Testler

.venv/bin/pytest        # testler
.venv/bin/ruff check seogeo tests   # lint
.venv/bin/mypy seogeo   # tip kontrolü

Üçü de CI'da (GitHub Actions, .github/workflows/ci.yml) Python 3.11 ve 3.13 için koşar.

Kurulum ve yayınlama

Docker ile kurulum

docker compose up -d          # http://localhost:8000 (chromium dahil: PDF + render denetimi çalışır)
docker compose logs -f

İmaj otomatik yayınlanır: ghcr.io/mujo5/seogeo:latest (main push) ve sürüm tag'lerinde sürüm numaralı imaj. Kalıcı veri seogeo-data volume'ünde (/data = ~/.seogeo karşılığı).

Kurulum sihirbazı

Anahtarları elle .env'e yazmak yerine:

.venv/bin/seogeo setup          # etkileşimli: sorar → canlı doğrular → .env'e yazar
.venv/bin/seogeo setup --test   # mevcut ayarları sormadan canlı doğrular (durum tablosu)

Sihirbaz her anahtarı kaydetmeden önce gerçek API çağrısıyla test eder; geçersiz anahtar uyarısıyla devam edip etmeme size kalmıştır. PageSpeed anahtarı için: Google Cloud Console → yeni proje (faturalandırma gerekmez) → "PageSpeed Insights API" etkinleştir → Kimlik bilgileri → API anahtarı. Google (GSC+GA4) için servis hesabı JSON'u önerilir (adımlar README'de "Google" bölümünde). AI testi için OpenAI/OpenRouter anahtarı.

Kaynak koddan kurulum yukarıda. PyPI'dan kurulum (yayınladıktan sonra):

pip install seogeo            # temel tarama/denetim
pip install 'seogeo[all]'     # Google + web paneli dahil

Yeni sürüm yayınlamak için (Trusted Publishing — PyPI token'ı gerekmez):

1. pypi.org → hesap → Publishing → pending publisher ekle: mujo5/seoGeo, workflow release.yml, environment pypi, project seogeo
2. git tag v0.2.1 && git push --tags → build + PyPI otomatik
3. Haftalık GEO denetimi: .github/workflows/geo.yml (cron/manuel, --fail-on critical --fail-under 60)

Sınırlar

• JavaScript çalıştırılmaz; sayfa ham HTML'i üzerinden değerlendirilir. Bu, çoğu AI tarayıcısının gördüğüyle aynıdır, ancak tamamen JS ile render edilen sitelerde SEO kontrolleri eksik kalır.
• AI bot erişim testi bot kimliği taklit edilerek yapılır; botları IP ile doğrulayan sistemler gerçek botlara farklı davranabilir.
• Alıntılanabilirlik ve CTR eşikleri sezgiseldir (genel rehberlere dayanır); bu yüzden çoğu "bilgi" düzeyindedir ve site bağlamında yorumlanmalıdır.
• AI görünürlük testi cevapta alan adının geçmesine bakar; cevabın içeriği değil "hatırlanma" ölçülür ve tek koşuda rastlantısal değişkenlik olabilir.
• Web paneli tek kullanıcılı panel güvenliği için tasarlandı: SEOGEO_PANEL_TOKEN ile korunur, ama yine de yalnızca güvenilir ağlarda çalıştırın. Zamanlanmış denetimler panel açık kaldığı sürece çalışır (kalıcı değildir); kesintisiz takip için cron + audit --save kullanın.