TEKNİK YAZI / API Tasarımı ve Entegrasyonlar

Google Custom Search API: Kullanım, Kotalar ve 2027 Kapanışı

Google Custom Search JSON API 1 Ocak 2027'de kapanıyor: mevcut entegrasyon için Node.js ve Python örnekleri, parametreler, kotalar ve geçiş seçenekleri.

Yayınlandı: Güncellendi:

Google Custom Search JSON API, çoğu zaman Google Search API olarak da anılır ve bir Programmable Search Engine (PSE) üzerinden arama sonuçlarını JSON olarak döndüren bir REST API’dir. Google’ın geliştirici belgelerine göre API yeni müşterilere kapalıdır; mevcut müşterilerin 1 Ocak 2027’ye kadar başka bir çözüme geçmesi gerekir.

Bu yazı, mevcut bir entegrasyonu kapanışa kadar güvenli ve izlenebilir biçimde çalıştırmak ve geçişi planlamak için hazırlandı. İstek yapısı, anahtarın sunucuda tutulması, Node.js ve Python örnekleri, parametreler, kotalar ve Google’ın önerdiği alternatifler ele alınıyor.

Güncel durum (Ekim 2026)

İstek yapısı

Her istek iki kimlik bilgisi taşır: Google Cloud Console’da oluşturulan API anahtarı (key) ve arama motoru kimliği (cx). Arama metni q parametresindedir:

GET https://www.googleapis.com/customsearch/v1?key=API_KEY&cx=SEARCH_ENGINE_ID&q=QUERY

Yanıttaki items dizisi sonuçları taşır; her öğede title, link ve snippet alanları bulunur. Sonuç olmadığında items alanı yanıtta yer almayabilir, bu yüzden kod onu boş liste gibi ele almalıdır.

Anahtarı sunucuda tutmak

API anahtarı tarayıcıya giden JavaScript koduna yazılırsa sayfayı açan herkes onu görebilir ve kotanızı kullanabilir. İstekleri sunucuda yapın ve sonuçları kendi endpoint’inizden döndürün; sonuçları sunucuda HTML’e gömmek de bir seçenektir (bkz. Server-Side Rendering yazısı).

Anahtarı kodda değil, sunucunun ortam değişkeninde tutun. Frontend projelerinde VITE_ ya da NEXT_PUBLIC_ önekli bir ortam değişkeni de build sırasında JavaScript paketine yazılır; bu yolları frontend’de API anahtarı yazısı ayrıntılı anlatıyor. Google Cloud Console’da anahtara bir API kısıtlaması (API restriction) ekleyerek yalnız Custom Search API’yi çağırabilmesini sağlayın; anahtar sızarsa başka Google API’lerinde kullanılamaz.

Node.js örneği

Aşağıdaki örnek Node.js 18+ sürümündeki yerleşik fetch ile çalışır. Parametreler URLSearchParams ile kodlanır, 10 saniyelik bir zaman aşımı (timeout) uygulanır ve HTTP hataları “sonuç yok” durumundan ayrılır:

// search.mjs
const API_KEY = process.env.GOOGLE_API_KEY;
const SEARCH_ENGINE_ID = process.env.GOOGLE_CSE_ID;

async function searchGoogle(query, { num = 10, start = 1 } = {}) {
  const params = new URLSearchParams({
    key: API_KEY,
    cx: SEARCH_ENGINE_ID,
    q: query,
    num: String(num),
    start: String(start),
    safe: "active",
  });

  const response = await fetch(
    `https://www.googleapis.com/customsearch/v1?${params}`,
    { signal: AbortSignal.timeout(10_000) }
  );
  const data = await response.json().catch(() => ({}));

  // Geçersiz anahtar, kota ve parametre hataları HTTP durum koduyla döner
  if (!response.ok) {
    throw new Error(
      `Custom Search hatası ${response.status}: ${data.error?.message ?? "bilinmiyor"}`
    );
  }

  // Sonuç yoksa items alanı bulunmayabilir
  return (data.items ?? []).map(item => ({
    title: item.title,
    link: item.link,
    snippet: item.snippet ?? "",
  }));
}

const results = await searchGoogle("php proc_open", { num: 5 });
results.forEach((r, i) => console.log(`${i + 1}. ${r.title}\n   ${r.link}`));

Python örneği

import os

import requests

API_KEY = os.environ["GOOGLE_API_KEY"]
SEARCH_ENGINE_ID = os.environ["GOOGLE_CSE_ID"]


def search_google(query, num=10, start=1):
    params = {
        "key": API_KEY,
        "cx": SEARCH_ENGINE_ID,
        "q": query,
        "num": num,
        "start": start,
        "safe": "active",
    }
    response = requests.get(
        "https://www.googleapis.com/customsearch/v1",
        params=params,
        timeout=10,
    )
    # 4xx ve 5xx yanıtlarda HTTPError fırlatır; kota hatası "sonuç yok" ile karışmaz
    response.raise_for_status()
    data = response.json()
    return [
        {"title": i["title"], "link": i["link"], "snippet": i.get("snippet", "")}
        for i in data.get("items", [])
    ]


for n, r in enumerate(search_google("php proc_open", num=5), 1):
    print(f"{n}. {r['title']}\n   {r['link']}")

Python’da params sözlüğü URL kodlamasını requests kütüphanesine bırakır; sorguyu dizeye elle eklemek gerekmez.

Parametreler

Kotalar ve maliyet

Google’ın yayımladığı fiyatlandırma yalnız mevcut müşteriler için ve 1 Ocak 2027’ye kadar geçerlidir:

Sayfalama her sayfa için ayrı sorgu harcar. 100 sonucun tamamını çekmek 10 istek demektir.

Hata ile boş sonucu ayırmak

Eski örneklerde sık görülen hata, items alanı olmayan her yanıtı “sonuç bulunamadı” diye göstermektir. Oysa geçersiz anahtar, aşılmış kota veya hatalı parametre HTTP hata koduyla döner; ayrıntı JSON gövdesindeki error nesnesindedir. Durum kodunu ve error.message alanını loglayın, hata oranındaki artışa uyarı kurun. Hizmet 1 Ocak 2027’de sona erdiği için o tarihten sonra isteklerin başarılı olması beklenmemelidir; arama kapalıyken de uygulamanın geri kalanı çalışmaya devam edebilmelidir.

Geçiş seçenekleri

Doğru hedef, arama kapsamına bağlıdır:

  1. 50 alan adına kadar site araması: Vertex AI Search. Google’ın JSON API için önerdiği alternatiftir. Google Cloud belgelerine göre Vertex AI Search, Agent Search adıyla yeniden adlandırılıyor ve Discovery Engine API’si (discoveryengine.googleapis.com) üzerinden çalışıyor. Site kısıtlı Custom Search API’si için yayımlanan geçiş rehberi, bir web sitesi veri deposu (data store) oluşturmayı ve API anahtarıyla servingConfigs.searchLite yöntemini çağırmayı anlatıyor; OAuth 2.0 kullanılırsa servingConfigs.search yöntemi kullanılıyor. Bu yol tüm web aramasının yerine geçmez.
  2. Tüm web araması: Google, tüm indeksine erişim gerektiren kullanımlar için ayrı bir “full web search” çözümü sunuyor. Erişim, Google’ın duyurusundaki ilgi formuyla başlıyor; yetenek ve fiyat bilgisi bu süreçte veriliyor.
  3. Gömülü arama kutusu: Yalnız kendi sitelerinizde arama yapacaksanız ve sonuçları API ile işlemeniz gerekmiyorsa Programmable Search Element, 50 alan adına kadar ücretsiz bir seçenektir.
  4. Kendi indeksiniz: Aranan şey yalnız kendi içeriğinizse, tam metin araması veya vector database ile anlamsal arama dış bir arama API’sine bağımlılığı tamamen kaldırır.
  5. Bing Search API’leri seçenek değildir: Microsoft, Bing Search API’lerini 11 Ağustos 2025’te kullanımdan kaldırdı. Önerdiği “Grounding with Bing Search”, Azure AI Agents içinde bir LLM’in yanıt üretirken güncel web verisi kullanmasını sağlar; ham sonuç listesi döndüren bir arama API’sinin doğrudan yerine geçmez.

Geçiş planı

  1. API’nin çağrıldığı tüm yerleri ve kullanılan parametreleri listeleyin.
  2. Gerçek kullanımdan temsilî bir sorgu seti çıkarın ve mevcut sonuçları kaydedin.
  3. Arama kapsamına göre hedefi seçin: 50 alan adına kadar site, tüm web veya yalnız kendi içeriğiniz.
  4. Aynı sorgu setini yeni çözümde çalıştırıp sonuç kalitesini, gecikmeyi ve maliyeti karşılaştırın.
  5. Arama katmanını tek bir arayüzün arkasına alın; sağlayıcı değişikliği tek yerde yapılsın.
  6. Geçişi 1 Ocak 2027’den önce tamamlayın ve eski API anahtarını devre dışı bırakın.

Sonuç

Custom Search JSON API’yi bugün kullanan bir proje kapanışa kadar çalışmaya devam edebilir, ancak yeni bir proje bu API’ye dayanamaz. Mevcut entegrasyonda anahtar sunucuda ve kısıtlı tutulmalı, hata ile boş sonuç ayrılmalı ve kota izlenmelidir. Geçiş hedefi arama kapsamına göre seçilir: 50 alan adına kadar Vertex AI Search (Agent Search), tüm web için Google’ın ayrı çözümü, yalnız kendi içeriğiniz için kendi indeksiniz.

Birincil kaynaklar