Custom Search API krok po kroku: od klucza API po Programmable Search Engine

Co to jest Custom Search API?

Custom Search JSON API (w skrócie Custom Search API) to usługa Google umożliwiająca programistyczne pobieranie wyników wyszukiwania przy użyciu tzw. Programmable Search Engine. Technicznie rzecz biorąc, jest to REST API wywoływane za pomocą prostych zapytań HTTP GET, które zwraca odpowiedzi w formacie JSON zgodnym ze specyfikacją OpenSearch 1.1. Zastosowań tego API jest mnóstwo, jednak nas interesować będzie przede wszystkim uzyskiwanie wyników wyszukiwania w sieci. Pozwala to bowiem na automatyczne sprawdzanie rezultatów wpisania konkretnego zapytania, a co za tym idzie – uzyskanie wiedzy interesującej z punktu widzenia SEO.

Każde zapytanie do Custom Search API to w praktyce wywołanie jednego adresu URL z odpowiednimi parametrami. Pełna struktura takiego zapytania wygląda następująco:

https://www.googleapis.com/customsearch/v1?key=TWÓJ_KLUCZ_API&cx=TWÓJ_SEARCH_ENGINE_ID&q=ZAPYTANIE

Trzy wymagane parametry to:

• key – klucz API, który identyfikuje Twoją aplikację wobec Google (tworzony w Google Cloud Console),
• cx – Search Engine ID, czyli identyfikator niestandardowej wyszukiwarki utworzonej w Programmable Search Engine,
• q – fraza, którą chcesz wyszukać.

Wyniki zwracane przez Custom Search API w formacie JSON można w ramach przygotowanego skryptu (np. w Pythonie lub JavaScripcie) natychmiast obrabiać do pożądanej formy. Jeżeli regularnie sprawdzamy dane zapytania i interesują nas konkretne informacje dotyczące SERP-ów, raz przygotowany kod sprawi, że wykonanie powtarzalnej pracy stanie się kwestią jednego kliknięcia. Zastosowań znaleźć można zresztą mnóstwo, więc w praktyce ograniczać może nas tylko ewentualny brak use case’ów 🙂

Jak uzyskać dostęp do Custom Search API?

Uzyskiwanie dostępu do Custom Search API podzielić można na dwa etapy.

Pierwszym z nich jest standardowe dla API z Google Cloud uzyskiwanie dostępu do usługi. Cały proces odbywa się w ramach tzw. Google Cloud Project – kontenera zasobów w Google Cloud, który grupuje klucze API, włączone usługi i rozliczenia. Początek wraz z rejestracją oraz tworzeniem projektu opisałem krok po kroku w poradniku API z Google Cloud. Tutaj zamieszczam zaś instrukcję przeznaczoną właśnie dla Custom Search API. Aby aktywować tę usługę, należy:

1. W otwartym projekcie w konsoli Google Cloud kliknąć w „Interfejsy API i usługi”.

   

2. Kliknąć „Włącz interfejsy API i usługi”.

   

3. Wpisać w wyszukiwarkę „custom search api” i kliknąć w wynik.

   

4. W szczegółach usługi kliknąć „Włącz”.

   

5. I to tyle, resztę danych potrzebnych do odpalenia Custom Search API uzyskamy z Programmable Search Engine.

Jak stworzyć wyszukiwarkę w Programmable Search Engine?

Drugi etap polega na skonfigurowaniu niestandardowej wyszukiwarki w Programmable Search Engine, czyli platformie Google pozwalającej stworzyć własny silnik wyszukiwania oparty na technologii Google Search. To właśnie z tego silnika Custom Search API pobiera wyniki. Aby go skonfigurować, należy:

1. Wejść na stronę Programmable Search Engine.
2. Kliknąć „Dodaj”.

   

3. Wpisać opcję, zaznaczyć interesujące nas opcje i kliknąć „Utwórz”.

   

4. W następnym oknie kliknąć „Dostosuj”.

   

5. Wybrać wszelkie interesujące nas opcje i zawężenia (w tym przypadku dla prostoty ograniczyłem się do ustawienia regionu „Polska”).
6. Skopiować Search Engine ID (parametr cx) – unikalny identyfikator niestandardowej wyszukiwarki, który będziemy przekazywać w każdym zapytaniu do Custom Search API.

   

7. Wejść do przewodnika Programmable Search Engine w Google for Developers i kliknąć „Get a Key”.

   

8. W okienku, które wyskoczy, wybrać projekt Google Cloud i kliknąć „Next”.

   

9. W następnym okienku kliknąć „Show key” i skopiować klucz API.

   

Mając klucz API (key) oraz Search Engine ID (cx), dysponujemy wszystkim, co potrzebne do wysyłania zapytań do Custom Search JSON API.

Struktura zapytania i format odpowiedzi JSON

Jak wspomniałem wyżej, zapytanie do Custom Search API to zwykłe żądanie HTTP GET pod adres endpointa z odpowiednimi parametrami. Podstawowe zapytanie o frazę „pozycjonowanie stron” wyglądałoby tak:

https://www.googleapis.com/customsearch/v1?key=AIza...&cx=a1b2c3...&q=pozycjonowanie+stron

W odpowiedzi API zwraca obiekt JSON zgodny ze specyfikacją OpenSearch 1.1. Najważniejsze elementy tej odpowiedzi to:

{
  "searchInformation": {
    "totalResults": "1250000",
    "searchTime": 0.45
  },
  "items": [
    {
      "title": "Pozycjonowanie stron – kompletny poradnik SEO",
      "link": "https://example.com/pozycjonowanie-stron",
      "displayLink": "example.com",
      "snippet": "Pozycjonowanie stron internetowych to proces..."
    },
    {
      "title": "Kolejny wynik...",
      "link": "https://example2.com/seo",
      "displayLink": "example2.com",
      "snippet": "Opis kolejnego wyniku..."
    }
  ]
}

Kluczowe pola w tablicy items, które są najbardziej przydatne z perspektywy SEO, to:

• title – tytuł strony wyświetlany w SERP (znacznik <title>),
• link – pełny adres URL wyniku,
• displayLink – domena wyświetlana w wynikach,
• snippet – fragment opisu (meta description lub wygenerowany przez Google).

Domyślnie API zwraca 10 wyników na jedno zapytanie i nie da się tego obejść.

Zaawansowane parametry wyszukiwania

Poza trzema podstawowymi parametrami (key, cx, q) Custom Search API obsługuje szereg parametrów zaawansowanych, dzięki którym możemy precyzyjnie dostosować wyniki do naszych potrzeb. Oto najważniejsze z perspektywy SEO:

Parametry te można łączyć w ramach jednego zapytania. Przykładowo, żeby sprawdzić wyniki dla frazy „content marketing” ograniczone do polskich stron z ostatnich 6 miesięcy, wystarczy:

...&q=content+marketing&gl=pl&cr=countryPL&dateRestrict=m6

Pełna dokumentacja wszystkich parametrów dostępna jest w referencji Custom Search API w Google for Developers.

Limity, koszty i bezpieczeństwo

Custom Search API jest usługą darmową tylko do pewnego poziomu. Bezpłatnie sprawdzić możemy maksymalnie 100 zapytań dziennie, a po wykorzystaniu tego limitu zapłacimy 5 dolarów za dodatkowe 1000 zapytań, z maksymalnym limitem 10 000 zapytań na dzień. Każde zapytanie z parametrem start (paginacja) liczy się jako osobne zapytanie – pobranie TOP 30 dla jednej frazy to zatem 3 zapytania z puli.

Zużycie limitu można monitorować na dwa sposoby: podstawowy monitoring jest dostępny w API Dashboard w Google Cloud Console (sekcja „Interfejsy API i usługi” → „Dashboard”), a bardziej zaawansowany – w Google Cloud Operations (dawniej Stackdriver), gdzie można ustawiać alerty i tworzyć niestandardowe dashboardy.

Warto też zadbać o bezpieczeństwo klucza API, zwłaszcza jeśli udostępniamy kod innym osobom lub korzystamy z niego w aplikacjach webowych. W sekcji „Dane logowania” (Credentials) w Google Cloud Console możemy nałożyć na klucz ograniczenia:

• Ograniczenia aplikacji – np. dozwolone adresy IP lub domeny HTTP referrer, z których klucz może być używany,
• Ograniczenia API – zawężenie klucza wyłącznie do Custom Search API, żeby w przypadku wycieku nie można go było użyć do innych usług Google Cloud.

Jeśli darmowy limit 100 zapytań dziennie nie wystarczy, a koszt $5/1000 zapytań jest zbyt wysoki przy dużej skali, warto rozważyć komercyjne alternatywy takie jak SerpApi, Tavily lub DataForSEO. Oferują one dedykowane API do pobierania wyników wyszukiwania Google z wyższymi limitami i dodatkowymi funkcjami (np. parsowanie featured snippets czy People Also Ask). Mimo iż musimy uiszczać opłatę za każde zapytanie, odpada konieczność ustawiania Programmable Search Engine czy dostosowywania zapytań.

Prosty skrypt do Custom Search API

Standardowo dla moich poradników skorzystamy z Pythona. Przykładowy skrypt wyciągnie adresy URL znajdujące się w TOP 10 dla wybranego zestawu zapytań oraz podliczy, jakie domeny pojawiają się tam najczęściej. Aby skorzystać w ten sposób z Custom Search API, skorzystaj z poniższej instrukcji:

1. Otwórz przygotowany przeze mnie skrypt Custom Search API w Google Colab.
2. Skopiuj skrypt na swój dysk Google.

   

3. Przygotuj plik Excel ze słowami kluczowymi do sprawdzenia w kolumnie „keyword”.

   

4. Wczytaj plik Excel ze słowami kluczowymi do pamięci wirtualnej Google Colab.

   

5. W skrypcie wpisujemy nazwę pliku, uzyskany wcześniej klucz API oraz Search Engine ID (cx), po czym odpalamy kod.

   

6. Otrzymujemy podsumowanie wyników w konsoli, a dodatkowo z pamięci wirtualnej możemy pobrać plik z konkretnymi adresami URL na poszczególnych pozycjach w TOP 10.

   

To oczywiście prosty przykładowy i bardzo prosty skrypt. Do konkretnych use case’ów warto przystosowywać kod przy pomocy ChataGPT. Po wklejeniu go wystarczy tylko wskazać, jakie chcemy zmiany, a następnie cieszyć się z kodu. Wynik pokazanego poniżej prompta z listą keywordów po uzupełnieniu danych skrzynki e-mail był natychmiast gotowy do automatyzacji za pomocą prostego sposobu, jaki prezentowałem przy okazji ustawiania automatycznych testów SEO.

Oczywiście pomysłów na wykorzystanie Custom Search API jest tyle, ile bardzo specyficznych przypadków. Ot, chociażby szybkiej potrzeby porównania performance’u dwóch zestawów adresów URL na konkretne frazy:

Nic tylko przetestować Custom Search API wtedy, gdy pojawi się taka potrzeba 🙂

Przyszłość Custom Search API – migracja do Vertex AI Search

Na koniec informacja, którą warto mieć na uwadze planując długoterminowe wykorzystanie Custom Search API. Google zamknęło Custom Search JSON API dla nowych klientów – nie jest już możliwe utworzenie nowego dostępu do tej usługi. Istniejący użytkownicy mogą z niej korzystać do 1 stycznia 2027 roku, po czym będą musieli przejść na alternatywne rozwiązanie.

Rekomendowanym przez Google następcą jest Vertex AI Search – usługa z ekosystemu Google Cloud, wykorzystująca zaawansowane modele NLP i machine learning do wyszukiwania. Vertex AI Search pozwala przeszukiwać do 50 domen i jest częścią platformy Vertex AI Agent Builder. Dla osób, które potrzebują pełnego wyszukiwania w całym webie (tak jak oferowało to Custom Search API), Google sugeruje kontakt bezpośredni w celu omówienia dostępnych opcji.

Co to oznacza w praktyce? Jeśli dopiero zaczynasz korzystać z Custom Search API – warto mieć świadomość, że to rozwiązanie z ograniczonym horyzontem czasowym. Jeśli już z niego korzystasz – masz czas do początku 2027 roku, żeby przetestować Vertex AI Search lub rozważyć komercyjne alternatywy takie jak SerpApi. W każdym przypadku wiedza o Custom Search API pozostaje przydatna, bo fundamenty (klucz API, parametry zapytań, format JSON) są zbliżone w nowszych rozwiązaniach Google.

Te artykuły powinny Cię zainteresować

1. Google Sheets API krok po kroku
2. Jak korzystać z API z Google Cloud?
3. Knowledge Graph Search API krok po kroku
4. PageSpeed Insights API krok po kroku
5. Poradnik Natural Language API krok po kroku

O autorze

Nazywam się Michał Małysa i od wielu lat zajmuję się zawodowo SEO oraz analizą treści, a od 2023 roku w zakres moich obowiązków i zainteresowań dość naturalnie weszło AI. Na stronie MałySEO porządkuję wiedzę o pozycjonowaniu stron internetowych, AI Search oraz działaniu LLM-ów. Prowadzę również MałySEO Newsletter, do którego subskrypcji serdecznie Cię zachęcam na podstronie najlepszego w Polsce newslettera SEO.

Jako że przygotowanie materiałów do MałySEO Newslettera oraz na bloga zajmuje nieco czasu, może zaświtać Ci w głowie dość miły z mojej perspektywy pomysł drobnego rewanżu. Jeżeli uznasz, że lektura tego wpisu była dla Ciebie czymś więcej, niż tylko szybkim odklepaniem randomowej internetowej treści, możesz postawić mi kawkę na buycoffee.to. Z góry dziękuję!

Jeżeli z jakiegoś powodu potrzebujesz się ze mną skontaktować, wyślij mail na adres kontakt[at]michalmalysa.pl