Search Console API Rehberi

TL;DR — Search Console API, Google Search Console verilerinizi arayüzde tıklamak yerine kodla çekmenizi sağlar. Arayüzün sunduğundan daha fazlasını alırsınız: arayüzdeki dışa aktarma yaklaşık 1 000 satırla sınırlıyken API istek başına 25 000 satıra kadar verir. Google ile OAuth üzerinden giriş yaparsınız; basit bir API anahtarı yeterli değildir ve yalnızca doğruladığınız sitelerin verilerini alabilirsiniz.

Search Console API nedir

Search Console, sitenizin Google’daki durumunu — hangi sorgularda sıralandığınızı, kaç tıklama ve gösterim aldığınızı, sayfalarınızın dizine eklenip eklenmediğini — gösterir. API, aynı verilerin ve kontrollerin çoğuna programatik erişim verir; böylece bunları bir e-tabloya, panoya veya zamanlanmış çalışan bir betiğe aktarabilirsiniz. Ancak arayüzle tam eşdeğer değildir: örneğin bir URL’yi canlı test etmek yalnızca arayüzde bulunur; API erişimi veya otomasyon tek başına dizine eklenmeyi, sıralamaları, trafik teşhisini ya da AI arama görünürlüğünü garanti etmez.

Dört parçası vardır:

1. Search Analytics API — Performance raporundaki tıklama, gösterim, CTR ve ortalama konum verilerini sorgu, sayfa, ülke, cihaz ve tarihe göre ayrıştırır.
2. URL Inspection API — tek bir URL’nin dizin durumunu verir. Google dizinindeki sürümü raporlar; arayüzdeki URL Inspection aracı ayrıca canlı test yapabilir, API bunu yapamaz.
3. Sitemaps API — site haritalarınızı listeler, gönderir veya siler.
4. Sites API — hesabınızdaki mülkleri listeler, ekler veya kaldırır.

Platform mülkleri sınırı: Search Console artık Instagram, TikTok, X ve YouTube için ayrı platform mülklerine sahip; ancak Google’ın güncel platform dokümantasyonu arayüz raporlarını ve rapor dışa aktarımını açıklar, eski uç noktalar için bir siteUrl tanımlayıcısı veya destek sözleşmesi belirtmez. Bu nedenle bu makaledeki API iş akışı yalnızca web sitesi mülklerini kapsar. LinkedIn desteklenen bir platform mülkü değildir.

Neden arayüz yerine bunu kullanmalı

En büyük fark satırlardır. Search Console arayüzünden Performance raporunu dışa aktarırsanız yaklaşık 1 000 satır alırsınız. API, istek başına 25 000 satıra kadar döndürür ve daha fazlası için sayfalama yapabilirsiniz. Binlerce sorgusu veya sayfası olan bir sitede arayüz verilerin büyük bölümünü göstermez.

Diğer neden otomasyondur. Bir kez API çağrısına dönüştürdüğünüzde her sabah çalıştırabilir, bir panoya aktarabilir veya tıklamalar düştüğünde kendinize uyarı gönderebilirsiniz.

Bedeli

Yalnızca Search Console’da doğruladığınız mülklerin verilerini çekebilirsiniz. API’yi sahibi olmadığınız bir siteye yöneltirseniz sonuç alamazsınız — yeni başlayanların en sık takıldığı nokta budur.

API size her şeyi de vermez. Tam listeyi değil, üst sıralardaki satırları döndürür ve Google’ın gizlilik için anonimleştirdiği sorguları hiçbir zaman göstermez. Eksiksiz bir görünüm isteyen büyük bir site için daha iyi araç bulk data export to BigQuery — more on that in the Advanced version.

TL;DR — Search Console API, webmaster-tools/v1 altında dört REST API’sidir: Search Analytics, URL Inspection, Sitemaps ve Sites. Hepsi OAuth 2,0 kullanır ve yalnızca doğrulanmış mülklerle çalışır. Search Analytics istek başına 1–25 000 satır döndürür (varsayılan 1 000), ancak “does not guarantee to return all data rows but rather top ones”; ölçek büyüdüğünde eksiksizlik için BigQuery toplu veri dışa aktarımına geçersiniz. URL Inspection her mülk için günde 2 000 sorgu / dakikada 600 sorgu ile kesin olarak sınırlıdır; büyük ölçekli dizin izlemesini bu aritmetik belirler.

Bu API rehberi web sitesi mülkleriyle sınırlıdır. Google tanımlayıcıyı ve uç nokta sözleşmesini belgeleyene kadar Sites, Search Analytics, URL Inspection veya Sitemaps uç noktalarının Instagram, TikTok, X ya da YouTube platform mülklerini desteklediğini varsaymayın.

Dört API’ye hızlı bakış

Google’ın API’nin ne yaptığına dair kendi çerçevesi şudur: “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” — “Mülkleri ve site haritalarını görüntülemenizi, eklemenizi veya kaldırmanızı; Search Console’da yönettiğiniz mülkler için Google Arama sonuçları verilerine gelişmiş sorgular çalıştırmanızı ve tek tek sayfaları test etmenizi sağlar.” Bu, tamamı webmaster-tools/v1 altında bulunan dört kaynağa temiz biçimde karşılık gelir:

• Search Analytics API — Performance raporunu programatik biçimde sunar: boyuta göre (sorgu, sayfa, ülke, cihaz, arama görünümü, tarih, saat) tıklama, gösterim, CTR ve konum.
• URL Inspection API — tek bir URL’nin dizin durumu; URL Inspection aracının programatik kardeşidir.
• Sitemaps API — site haritalarını listeler, getirir, gönderir ve siler.
• Sites API — doğrulanmış mülkleri listeler, ekler ve kaldırır.

Arayüzde zaten kullandığınız şeylerin çoğunu — Performance raporunu ve URL Inspection aracını — betik yazabileceğiniz uç noktalar olarak sunar. Ancak 1:1 ayna değildir: API tam arayüz eşdeğerliğini garanti etmez (örneğin URL Inspection canlı testi yalnızca arayüzdedir); API erişimi veya otomasyon da tek başına dizine eklenmeyi, sıralamaları, trafik teşhisini ya da AI arama görünürlüğünü garanti etmez.

Kimlik doğrulama: OAuth 2,0, iki kapsam, yalnızca doğrulanmış mülkler

API anahtarı yoktur. Her çağrı OAuth 2,0 kullanır — Google açıkça “all requests to the Google Search Console API must be authorized by an authenticated user.” — “Google Search Console API’sine yapılan tüm istekler kimliği doğrulanmış bir kullanıcı tarafından yetkilendirilmelidir.” der. Google Cloud’da bir uygulama kaydeder, bir kapsam ister ve kısa ömürlü erişim belirteci alırsınız. İki kapsam vardır:

• https://www.googleapis.com/auth/webmasters — okuma/yazma.
• https://www.googleapis.com/auth/webmasters.readonly — yalnızca okuma.

Sunucudan sunucuya otomasyon için (gece çalışan raporlama işi veya dizin izleyicisi) bir service account hesabına mülke erişim vererek etkileşimli izin akışını atlayabilirsiniz.

Web sitesi mülklerinde iki mülk tanımlayıcı biçimi önemlidir: URL-prefix mülkü tam mülk URL’siyle (Google’ın örneği http://www.example.com/) gönderilir; Domain mülkü sc-domain:example.com biçimini kullanır. Search Console’da mülkün nasıl doğrulandığına uygun biçimi göndermelisiniz. Service account (veya kullanıcı) tam olarak o mülke erişim kazanmalıdır; bu, sahiplik kontrolünü aşmaz ve hesaptaki her mülke toplu izin vermez.

Herkesin takıldığı kapı şudur: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” — “API ile erişmek istediğiniz her Google Search Console hesabında uygun erişime (owner, full veya read) sahip olmalısınız.” Doğrulanmadığınız bir mülk için API’yi çağırırsanız hiçbir şey döndürmez; fark etmeyebileceğiniz bir hata yerine yalnızca boş veri alırsınız.

Search Analytics API — Performance raporu, ölçekli

Kolaylıktan önce tavanı bilin: Google’ın kendi uyarısı şudur: “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” — “API, Search Console’un iç sınırlamalarıyla bağlıdır ve tüm veri satırlarını değil, üst sıradakileri döndürmeyi garanti eder.” Sayfalama, bu üst satır listesinin daha derinine gitmenizi sağlar; tavanı ortadan kaldırmaz. Her satıra ihtiyacınız olduğunda daha büyük bir rowLimit değil, aşağıdaki BigQuery toplu dışa aktarımını seçin.

Bu tavanın içinde bile çoğu kişinin API’ye gelme nedeni budur. Arayüzü aşmasını sağlayan rowLimit parametresi şudur: “[Optional; Valid range is 1–25,000; Default is 1,000].” Arayüz dışa aktarımı yaklaşık 1 000 satırda kesilir; API istek başına 25 000 satıra kadar verir ve startRow ile bunun ötesine sayfalarsınız. Uzun kuyruklu sorguları olan bir sitede fark, verinin yalnızca başını görmekle daha büyük bir bölümünü görmek arasındadır — yine de tamamı değildir.

Gelen sonucu iki unsur daha biçimlendirir. İlk olarak dataState tazeliği denetler: final (varsayılan) yalnızca kesinleşmiş verileri döndürür, all yeni toplanan verileri dahil eder, hourly_all ise açıkça kısmi olan saatlik ayrıntılar verir — yanıt metadatası first_incomplete_date veya first_incomplete_hour alanını gösterir ve Google bu noktadan sonraki değerlerin değişebileceğini belirtir. İkinci olarak Search Analytics kotaları tek bir sayı değildir: kullanım limitleri sayfası bunları yük limitlerine (10 dakikalık ve 1 günlük dilimlerle ölçülen kaynak-temelli izin; daha geniş tarih aralıkları, daha fazla boyut ve ağır filtreler bunu daha hızlı tüketir) ve aşağıda ele alınan QPS/QPM/QPD istek hızı limitlerine ayırır. İstek hızı tavanına ulaşmadan önce yük tavanına çarpabilirsiniz.

URL Inspection API — gerçekten sınırlayan kota

URL Inspection API, “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” — “Verilen URL’nin dizine eklenmiş veya dizine eklenebilir durumunu görüntüler. Şu anda yalnızca Google dizinindeki sürümün durumu kullanılabilir; canlı bir URL’nin dizine eklenebilirliğini test edemezsiniz.” der. Son cümle teknik ayrıntı değil gerçek bir kapsam sınırıdır: arayüzdeki URL Inspection aracı sayfaya şu anki hâliyle canlı test uygulayabilir; API yalnızca Google’ın zaten dizine eklediği sürümü raporlar. API’yi çok sayıda URL’de dizin kapsamı izlemek için kullanın; arayüzün canlı testinin yerine koymayın.

Matematiğin önem kazandığı yer burasıdır. Site başına günde 2 000 sorgu ve dakikada 600 sorgu alırsınız. (Proje başına tavan çok daha yüksektir — günde 10 000 000 ve dakikada 15 000 — ancak sizi zorlayan site başına sınırdır.) 50 000 URL’lik bir sitenin dizin durumunu izlemek istiyorsanız hepsini bir günde inceleyemezsiniz; günlere bölüp zamanlarsınız veya önceliklendirirsiniz. Çok az yazı bu hesabı yapar ve büyük ölçekli dizin izlemesindeki en büyük planlama kısıtı budur.

Buna karşılık Search Analytics cömerttir — site ve kullanıcı başına dakikada 1 200 istek — diğer kaynaklar (Sitemaps, Sites) kullanıcı başına saniyede 20 / dakikada 200 istekle sınırlıdır. Sıkı olan URL Inspection’dır.

Sitemaps ve Sites API’leri

Sitemaps API, site haritalarınızın yönetim katmanıdır: “submits a sitemap for a site,” — “bir site için site haritası gönderir”; “deletes a sitemap from this site,” — “bu siteden bir site haritasını siler”; belirli bir site haritası hakkında bilgi “retrieves” eder ve bu site için gönderilen ya da site haritası dizininde bulunan site haritası girdilerini “lists” eder. Döndürdüğü site haritası kaynağında path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors ve contents dizisi gibi alanlar bulunur; bunlar geniş ölçekte site haritası sağlığını denetlemek için kullanışlıdır.

Sites API, doğrulanmış mülkleri listeler, ekler ve kaldırır — birçok mülkü programatik biçimde hazırlıyor veya denetliyorsanız yararlıdır.

BigQuery toplu dışa aktarımı ne zaman kullanılmalı

Büyük sitelerde API’nin istek başına 25 000 satır ve yalnızca üst satırlar modeli tavana dönüşür. Google’ın yanıtı aynı biçimde veri döndüren beşinci bir API kaynağı değil, zamanlanmış ayrı bir dışa aktarma hattıdır: BigQuery’ye toplu veri dışa aktarımı. Seçimi “API A mı API B mi” diye değil, çekme ile zamanlanmış itme arasındaki tercih olarak düşünün. Google’ın kendi çerçevesi şöyledir: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” — “Search Console Performance verilerinizi BigQuery’ye günlük dışa aktaracak şekilde zamanlayın; verileriniz üzerinde karmaşık sorgular çalıştırabilir veya verileri harici bir depolama hizmetine aktarabilirsiniz. Toplu veri dışa aktarma özelliğiyle, anonimleştirilmiş sorgular dışında mülkünüz için Search Console’da bulunan tüm Performance verilerini görürsünüz.”

Karar kuralı budur:

• Arayüz dışa aktarımı — yaklaşık 1 000 satır, hızlı tek seferlik görünüm.
• Search Analytics API — istek başına 25 000 satıra kadar, sayfalı ve betiklenebilir; orta ölçekli istekler ve panolar için iyi.
• BigQuery toplu dışa aktarımı — günlük tüm kullanılabilir Performance verileri, satır tavanı yok; on binlerce sayfa veya sorguya ulaştığınızda doğru araç.

Hiçbirinin vermediği bir şey anonimleştirilmiş sorgulardır — Google’ın gizlilik için sakladığı terimler. Bu, çevresinden dolaşabileceğiniz bir hata değil, gerçek bir boşluktur. Ölçeğini ilk elden biliyorum: Ahrefs Brand Ambassador olarak çok büyük bir site örneğinden API’de bulunan tüm verileri çektiğimiz bir çalışmanın ortaya çıkmasına yardımcı oldum ve Google’ın tıklamaların büyük bir bölümünde anahtar kelime terimini gizlediğini bulduk. Daha sonra bunu Ahrefs Rank Tracker’a — GSC verilerinizin tam geçmişi, anonimleştirilmiş sorgulara giden tıklamaların yüzdesi ve kendi sayılarınızdan oluşturulan özel CTR eğrisi — olarak ekledik. Birisi API’nin “tüm verilerinizi” döndürdüğünü söylediğinde dürüst dipnot bu anonimleştirilmiş bölümdür.

Yaygın kullanım alanları

• Otomatik raporlama — Sheets’e veya bir veri ambarına zamanlanmış çekimler.
• BI panoları — Performance verilerinin üzerinde Looker Studio veya BigQuery.
• Büyük ölçekli dizin/kapsam izleme — 2 000/gün kotası içinde gruplanmış URL Inspection.
• CTR eğrisi oluşturma — kendi verilerinizden konuma göre beklenen CTR’yi modelleme.
• Anomali uyarıları — tıklama/gösterim düşüşlerini otomatik işaretleme.

Üçüncü taraf araçlar da böyle çalışır: Ahrefs veya bir Looker Studio bağlayıcısı “Search Console’u entegre ettiğinde” bu API’leri (ve giderek BigQuery dışa aktarımını) sizin adınıza çağırır.

Yapay zekâ özeti

Advanced sürümünün kısaltılmış özeti:

• Search Console API = dört REST API: webmaster-tools/v1 altında Search Analytics (Performance verileri), URL Inspection (dizin durumu), Sitemaps ve Sites. Tam arayüz eşdeğeri değildir; URL Inspection canlı testi gibi bazı şeyler yalnızca arayüzde vardır ve API erişimi tek başına dizine eklenmeyi, sıralamaları veya trafik teşhisini garanti etmez.
• Kimlik doğrulama OAuth 2,0’dır, API anahtarı yoktur. İki kapsam (webmasters, webmasters.readonly) bulunur; sunucudan sunucuya kullanım için service account hesapları vardır, ancak bunların da tam mülke açıkça erişimi olmalıdır. siteUrl, URL-prefix mülkünü veya sc-domain:example.com Domain mülkünü alır; doğrulama biçimiyle eşleştirin. API yalnızca doğruladığınız mülkler için veri döndürür — yeni başlayanların bir numaralı tuzağı.
• Search Analytics önce üst satırları döndürür, tam dökümü değil — sayfalama ne olursa olsun “does not guarantee to return all data rows but rather top ones”. Bu tavanın içinde istek başına 1–25 000 satır (varsayılan 1 000) döndürür; arayüz dışa aktarımında yaklaşık 1 000 satır vardır ve kotalar yük limitleri ile QPS/QPM/QPD istek hızı limitlerine ayrılır.
• URL Inspection: site başına günde 2 000, dakikada 600 sorgu ve yalnızca dizine eklenmiş sürümü raporlar; canlı test yapamaz. Büyük ölçekli dizin izlemesindeki gerçek kısıt budur — buna göre gruplayın ve zamanlayın.
• Sitemaps API site haritalarını listeler/getirir/gönderir/siler; Sites API mülkleri listeler/ekler/kaldırır.
• Büyük sitelerde BigQuery toplu veri dışa aktarımını kullanın — beşinci bir API kaynağı olmayan, günlük zamanlanmış ayrı bir hat; anonimleştirilmiş sorgular dışında tüm kullanılabilir Performance verilerini satır tavanı olmadan verir.
• Anonimleştirilmiş sorgular gerçek bir boşluktur; hiçbir API veya dışa aktarım bunu doldurmaz. Patrick’in Ahrefs çalışması bu gizli bölümün ölçeğini sayısallaştırdı.

Resmî dokümantasyon

Google’ın birincil kaynak dokümantasyonu.

Search Console API başvurusu

• Search Console API — Overview / about — API’nin ne yaptığı ve doğrulanmış mülk gereksinimi.
• Search Analytics: query reference — rowLimit (1–25 000) ve boyut parametreleri.
• URL Inspection API reference — inspect metodunun döndürdüğü dizin durumu verisi.
• Sitemaps API reference — list, get, submit, delete.
• Sites API reference — doğrulanmış mülkleri listeler, ekler, kaldırır.
• Usage limits — site, kullanıcı ve proje başına tam kota tablosu.
• Authorizing requests (OAuth 2,0) — kapsamlar ve kimlik doğrulama akışı.

Toplu veri dışa aktarımı

• About bulk data export (Search Console Help) — anonimleştirilmiş sorgular dışında tüm Performance verilerinin BigQuery’ye günlük dışa aktarımını zamanlama.
• Bulk data export announcement (Search Central blog) — büyük siteler için toplu dışa aktarımı konumlandıran lansman yazısı.

Kaynaktan alıntılar

Google’ın dokümantasyonunda kayda geçmiş ifadeler. Her bağlantı, kaynak sayfadaki alıntıya atlayan bir derin bağlantıdır.

Google — API ne yapar ve kim kullanabilir

• “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” — Google Search Console API docs (Overview). Jump to quote — “Mülkleri ve site haritalarını görüntüleyin, ekleyin veya kaldırın; yönettiğiniz mülkler için gelişmiş sorgular çalıştırın ve tek tek sayfaları test edin.”
• “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” — Google Search Console API docs (Overview). Jump to quote — “API ile erişmek istediğiniz her Google Search Console hesabında uygun erişime sahip olmalısınız.”
• “All requests to the Google Search Console API must be authorized by an authenticated user.” — Authorizing requests guide. Jump to quote — “Google Search Console API’sine yapılan tüm istekler kimliği doğrulanmış bir kullanıcı tarafından yetkilendirilmelidir.”

Google — Search Analytics API

• “[Optional; Valid range is 1–25,000; Default is 1,000]” — rowLimit parametresi. — Search Analytics: query reference. Jump to quote
• “The URL of the property as defined in Search Console.” — siteUrl parametresi; örneklerde hem URL-prefix biçimi (http://www.example.com/) hem Domain mülkü biçimi (sc-domain:example.com) bulunur. — Search Analytics: query reference. Jump to quote
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” — Search Analytics: query reference. Jump to quote

Google — URL Inspection API

• “View the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” — URL Inspection API reference. Jump to quote — “Verilen URL’nin dizine eklenmiş veya dizine eklenebilir durumunu görüntüler. Şu anda yalnızca Google dizinindeki sürüm kullanılabilir; canlı bir URL’nin dizine eklenebilirliğini test edemezsiniz.”

Google — Sitemaps API

• “Submits a sitemap for a site.” / “Deletes a sitemap from this site.” / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” — Sitemaps API reference. Jump to quote — “Bir site için site haritası gönderir; bu siteden bir site haritasını siler; bu site için gönderilen veya site haritası dizinine dahil edilen girdileri listeler.”

Google — toplu veri dışa aktarımı

• “Schedule a daily export of your Search Console performance data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” — Search Console Help: About bulk data export. Jump to quote — “Search Console Performance verilerinizi BigQuery’ye günlük dışa aktaracak şekilde zamanlayın… anonimleştirilmiş sorgular dışında mülkünüz için bulunan tüm Performance verilerini görürsünüz.”

OAuth kurulumu ve ilk çağrı kontrol listesi

Sıfırdan çalışan bir Search Console API çağrısına ulaşmak:

• Search Console’da mülke doğrulanmış erişiminiz (owner, full veya read) olduğunu onaylayın — doğrulanmamış mülklerde API hiçbir şey döndürmez.
• Google Cloud Console’da bir proje oluşturun.
• Bu proje için Search Console API’yi etkinleştirin.
• Kimlik bilgileri oluşturun: etkileşimli/kullanıcı uygulamaları için OAuth 2,0 client veya sunucudan sunucuya otomasyon için service account.
• Service account kullanıyorsanız Search Console ayarlarında mülke erişim verin.
• Doğru kapsamı isteyin: raporlama için webmasters.readonly, site haritası göndermek veya mülkleri yönetmek için webmasters.
• OAuth akışı (veya service-account anahtarı) üzerinden erişim belirteci alın.
• siteUrl biçiminin mülkün doğrulanma biçimiyle eşleştiğini onaylayın: URL-prefix mülkü için tam URL, Domain mülkü için sc-domain:example.com.
• Verinin döndüğünü doğrulamak için küçük bir tarih aralığı ve searchAnalytics.query ile rowLimit: 10 test çağrısı yapın.
• Kotaları planlayın: Search Analytics istek hızları cömerttir, ancak ayrı bir yük kotasını da tüketir; URL Inspection site başına günde 2 000, dakikada 600 ile sınırlıdır — buna göre gruplayın. URL Inspection’ın canlı test yapmasını beklemeyin; bu yalnızca arayüzdedir.
• On binlerce satır için sayfalama yerine BigQuery toplu dışa aktarımını kurun.

Zihinsel modeller

1. Dört API, tek kimlik doğrulama. Search Analytics (Performance verilerinizi okur), URL Inspection (bir URL’nin dizin durumunu okur), Sitemaps (site haritalarını yönetir), Sites (mülkleri yönetir). Dördü de aynı OAuth 2,0 kapısından geçer ve aynı doğrulanmış mülk kuralına uyar.

2. Veri ölçeği merdiveni. Aracı hacme göre seçin:

• Hızlı bakış → arayüz dışa aktarımı (yaklaşık 1 000 satır).
• Betiklenebilir, orta ölçekli → Search Analytics API (istek başına 25 000’e kadar, sayfalı).
• Büyük site, eksiksiz → BigQuery toplu dışa aktarımı (günlük tüm veri, satır tavanı yok). Alt basamak verinize sığmamaya başladığında bir üst basamağa çıkın.

3. Tüm satırlar değil, üst satırlar. API’nin her şeyi değil “top ones”ı döndürdüğünü ve anonimleştirilmiş sorguların hem API’den hem dışa aktarımdan çıkarıldığını aklınızda tutun. Eksiksizlik önemliyse BigQuery buna daha yakındır; ancak anonimleştirilmiş bölüm her durumda yoktur.

4. Kurmadan önce kota hesabı. Dizin izleyicisi tasarlamadan önce hesabı yapın: URL Inspection site başına günde 2 000 sorgudur. 50 000 URL’lik bir site her gün incelenemez; gruplara ayırın, önceliklendirin veya günlere yayın. Tavanı üretimde keşfetmek yerine tasarımı buna göre kurun.

Search Console API — hızlı başvuru

Dört API ve temel limitleri

Kimlik doğrulama

• Yalnızca OAuth 2,0 — API anahtarı yok.
• Kapsamlar: webmasters (okuma/yazma), webmasters.readonly (okuma).
• Sunucudan sunucuya kullanım için service account (mülk erişimi verin).
• Yalnızca doğrulanmış mülkler veri döndürür.

Hızlı bilgiler

• API yalnızca üst satırları döndürür — sayfalama ne olursa olsun tam olması garanti değildir.
• Arayüz dışa aktarımı yaklaşık 1 000 satırda kesilir; API istek başına 25 000’e kadar verir ve startRow ile sayfalarsınız.
• Search Analytics kotaları yük limitlerine (kaynak-temelli, 10 dakikalık / 1 günlük dilimler) ve yukarıdaki QPS/QPM/QPD istek hızı limitlerine ayrılır.
• siteUrl, URL-prefix mülkünü (http://www.example.com/) veya Domain mülkünü (sc-domain:example.com) alır — doğrulama biçimiyle eşleştirin.
• URL Inspection yalnızca dizine eklenmiş sürümü raporlar — canlı test yapamaz; bu yalnızca arayüzdedir.
• Anonimleştirilmiş sorgular hem API’den hem BigQuery dışa aktarımından çıkarılır.
• On binlerce satır için → beşinci bir API kaynağı olmayan, ayrı zamanlanmış bir hat olan BigQuery toplu veri dışa aktarımı.
• Performance raporunun (Search Analytics) ve URL Inspection aracının çoğunu sunar, ancak arayüzle tam eşdeğer değildir.

Basit bir Search Analytics isteği

Bu açıklayıcıdır, kopyala-yapıştır için hazır değildir — kendi OAuth kimlik bilgilerinizi bağlamanız ve tarihleri/mülkü ayarlamanız gerekir. Bir searchAnalytics.query çağrısının biçimini, tarih aralığı, istediğiniz boyutlar ve rowLimit içeren istek gövdesini gösterir:

İstek gövdesi (önemli olan bölüm)

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

Python taslağı (google-api-python-client kütüphanesiyle)

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

25 000 satırı aşmak için döngü kurun ve bir istek satır döndürmeyene kadar startRow değerini 25 000 artırın. Sonuç hâlâ “top rows”dır, tam döküm değildir — tam döküm için BigQuery toplu dışa aktarımını kullanın.

Search Console API’yi kullanan (veya saran) araçlar

• Google Cloud Console — projeyi oluşturduğunuz, API’yi etkinleştirdiğiniz ve OAuth/service-account kimlik bilgilerini aldığınız yer.
• Resmî client kütüphaneleri — Python, Java, JavaScript/Node, PHP ve .NET için Google API client kütüphaneleri REST çağrılarını sarar.
• BigQuery — toplu dışa aktarımın hedefi; tüm Performance verilerinizi SQL ile sorgulayın.
• Looker Studio — aynı verilerle panolar için Search Console’a (ve BigQuery’ye) bağlanır.
• Ahrefs — Search Console API’sini entegre eder; Rank Tracker tam GSC geçmişini, anonimleştirilmiş sorgulara giden tıklama payını ve kendi verilerinizden özel CTR eğrisini gösterir.
• Search Console arayüzü — Performance raporu ve URL Inspection aracı, Search Analytics ve URL Inspection API’lerinin manuel karşılıklarıdır; API’nin kapatamadığı boşluk şudur: URL’de canlı test yalnızca arayüz aracıyla yapılabilir.

Search Console API çalışmasını planlama istemleri

Bu istemleri kod veya analiz planı oluşturmak için kullanın. Kimlik bilgilerini, refresh token’ları ve service-account anahtarlarını herhangi bir sohbet girdisine koymayın.

Search Analytics isteği tasarlama

Mülk URL’nizi, tarih aralığını, boyutları, filtreleri ve raporlama hedefini yapıştırın.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

Kota güvenli URL Inspection zamanlaması planlama

Gizli token’lar yerine URL önceliğine göre gruplanmış bir CSV özeti veya sayımları yapıştırın.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

API ile BigQuery dışa aktarımı arasında seçim

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

Vakit ayırmaya değer kaynaklar

İlgili çalışmalarım

• Ahrefs blog — yazılarım — GSC verilerini ölçekli kullanma ve anonimleştirilmiş sorgular üzerine çalışmalar da dahil.
• Now in Ahrefs Rank Tracker: full GSC history + anonymized-query share — duyurduğum CTR eğrisi ve GSC geçmişi özelliği.

Google dokümanları

• Search Console API overview ve usage limits sayfası — önce yer imlerine eklemeniz gereken iki sayfa.
• About bulk data export — BigQuery’ye ne zaman ve nasıl geçileceği.

Diğer kaynaklar

• Hidden keywords in GSC — the Ahrefs study (Search Engine Journal coverage) — anonimleştirilmiş sorgu bulgularının üçüncü taraf yazısı.
• Enhanced Search Console analytics with BigQuery (SEJ) — toplu dışa aktarım yoluna pratik bakış.
• Bulk data export: a new and powerful way to access your Search Console data (Google Search Central blog) — büyük siteler için toplu dışa aktarımı konumlandıran Şubat 2023 lansman yazısı.
• google-api-python-client (PyPI) — Search Console API’sini çağırmak için kullanılan resmî Python client kütüphanesi; Google APIs client ailesiyle Node, Java, PHP ve .NET için de kullanılabilir.
• r/TechSEO — API ve veri çekme sorunlarının tartışıldığı topluluk.

Alıntılanmaya değer istatistikler

• Search Analytics satır limiti: istek başına 25 000 (varsayılan 1 000) — arayüz dışa aktarımının yaklaşık 1 000 satırlık sınırına karşılık. API’yi kullanmanın temel nedeni budur. Source
• URL Inspection kotası: site başına günde 2 000 sorgu ve dakikada 600 sorgu — büyük ölçekli dizin izlemesindeki kesin tavan (proje başına günde 10 milyon, dakikada 15 000). Source
• Anonimleştirilmiş sorgular, en eksiksiz yol olan BigQuery toplu dışa aktarımından bile çıkarılır — sorgu verilerinizde gerçek ve kaçınılmaz bir boşluk. Source
• Google, tıklamaların büyük bir bölümünde anahtar kelime terimini gizler — ortaya çıkmasına yardımcı olduğum Ahrefs çalışmasının çok büyük bir site örneğinde API’de bulunan tüm verileri çekmesinden elde edilen bulgu. Coverage

Kendinizi test edin: Search Console API

API’ler, kimlik doğrulama, veri limitleri ve ölçek hakkında beş kısa soru. Her biri için bir yanıt seçin, sonra sonucunuzu kontrol edin.

Değişiklik günlüğü