Wstęp

API do pobierania danych z Google Maps: szczegółów wizytówek, opinii wraz z profilami recenzentów oraz statystyk kont użytkowników. Dane pochodzą z wewnętrznych endpointów Google, dzięki czemu zawierają pola niedostępne w oficjalnym Places API (m.in. status działalności, przejęcie wizytówki, atrybuty, popularne godziny, rezerwacja online, posty właściciela).

Adres bazowy

Wszystkie odpowiedzi są w formacie JSON i mają wspólną kopertę:

{
  "success": true,
  "data":    { ... },
  "timestamp": "2026-07-25T18:00:00+00:00",
  "execution_time": "624.31ms"
}

Limity i obsługa błędów

Klucz API nie jest wymagany. Obowiązują limity zapytań na godzinę (nagłówki X-RateLimit-* w każdej odpowiedzi): /batch 1000, /all 2000, pozostałe 5000.

Kod	Znaczenie
200	Sukces
400	Błędny parametr lub miejsce/profil nieznalezione
429	Przekroczony limit zapytań
503	API wyłączone

{
  "success": false,
  "error": { "message": "Nie znaleziono miejsca dla podanego Place ID", "code": 400 }
}

Parametry

Parametr	Wymagany	Opis
placeid	tak	Place ID w formacie ChIJ… lub feature id 0x…:0x…

Cennik usług — parametr uslugi=1

Dokładany tylko na żądanie: blok potrafi mieć 50 kB i powiększa odpowiedź o ok. 85%, a details obsługuje dziesiątki tysięcy wywołań na dobę. Bez parametru kształt odpowiedzi jest niezmieniony. Ma go ok. 58% wizytówek.

uslugi.liczba_pozycji	int	Ile usług łącznie
uslugi.liczba_kategorii	int	Ile grup usług
uslugi.kategorie	array	Nazwy grup, np. MASAŻE RELAKSACYJNE
uslugi.pozycji_z_cena	int	Ile pozycji ma podaną cenę — cennik bywa bez cen, sama lista usług też występuje
uslugi.pozycji_z_opisem	int	Ile pozycji ma opis (np. kancelarie opisują zakres spraw)
uslugi.pozycje[]	array	Pozycje: kategoria, nazwa, opis, cena, czas, link

Zwracane pola

Identyfikacja i podstawy

cid	string	Identyfikator CID
place_id_chij	string	Place ID w formacie ChIJ
entity_id	string	Stabilny identyfikator Knowledge Graph (/g/…)
nazwa_wizytowki	string	Nazwa firmy
kategoria	string	Kategoria główna
kategorie	array	Pełna lista kategorii
kategoria_gcid	string	Identyfikator kategorii głównej wg Google, np. gcid:dental_clinic — niezależny od języka, więc nadaje się do dopasowywania kategorii między wizytówkami
podtypy	array	Maszynowe klucze typów, np. skin_care_clinic
czy_znaleziono	bool	Czy miejsce faktycznie istnieje

Adres i kontakt

adres	string	Adres pełny
adres_ulica	string	Ulica z numerem
adres_kod	string	Kod pocztowy
adres_miasto	string	Miasto
lat / lng	float	Współrzędne
strefa_czasowa	string	Strefa czasowa miejsca, np. Europe/Warsaw — potrzebna do poprawnego liczenia „czy teraz otwarte"
kraj / jezyk	string	Kod kraju i języka wizytówki
telefon	string	Telefon w formacie wyświetlanym
telefon_raw	string	Telefon bez separatorów
strona_www	string	Adres strony
domena	string	Sama domena

Oceny

srednia_ocen	float	Średnia ocena
liczba_opinii	int	Liczba opinii
liczba_5_gwiazdek … liczba_1_gwiazdka	int	Rozkład ocen — ile opinii na każdą liczbę gwiazdek. Nienaturalny rozkład (same piątki, brak środka) to przesłanka do analizy anomalii
liczba_5_gwiazdek … liczba_1_gwiazdka	int	Histogram ocen

Status i własność przydatne w lead-gen

status_dzialalnosci	string	otwarte / zamkniete_tymczasowo / zamkniete_na_stale
przejeta	bool|null	Czy wizytówka jest przejęta przez właściciela. false = nikt się nią nie opiekuje
link_przejecia	string	Gotowy link „zgłoś prawo do firmy" (tylko gdy nieprzejęta)
zarzadca_id	string	Identyfikator konta zarządzającego wizytówką
gbp_id	string	Identyfikator konta Google Business Profile. Dwie wizytówki z tym samym gbp_id lub zarzadca_id są prowadzone przez to samo konto — pozwala wykrywać sieciówki i agencje obsługujące wiele wizytówek

Treść i aktywność

opis / ma_opis	string / bool	Opis od właściciela i flaga jego obecności
godziny	array	Godziny otwarcia dla każdego dnia
atrybuty	array	Udogodnienia pogrupowane, np. dostępność dla wózków, płatności, rezerwacje
rezerwacja_online	bool	Czy da się umówić wizytę online
rezerwacja_dostawca	string	System rezerwacji, np. Booksy
rezerwacja_url	string	Bezpośredni link do rezerwacji
liczba_postow	int	Liczba postów właściciela
ostatni_post_data	string	Data ostatniego posta (ISO 8601)
ostatni_post_dni_temu	int	Ile dni temu ukazał się ostatni post
ostatni_post_tekst_daty	string	Data opisowo, np. „7 godzin temu"
ostatni_post_tresc	string	Początek treści ostatniego posta

Ruch i otoczenie

popularne_godziny	array	Obciążenie procentowe dla każdej godziny w 7 dniach tygodnia
szczyt_dzien / szczyt_godzina / szczyt_obciazenie	string / string / int	Moment największego ruchu
inni_wyszukiwali	array	Konkurenci z sekcji „Inni wyszukiwali również" (zawsze 5, dobór Google). Każdy: nazwa, ocena, liczba_opinii, kategoria, kategorie (pełna lista), lat, lng, odleglosc_m (dystans od tej wizytówki w metrach), fid
odznaki	array	Odznaki tożsamości firmy, np. „Przyjazne dla osób LGBTQ+". Właściciel zaznacza je świadomie, więc obecność jest sygnałem zaangażowania — ma je ok. 33% wizytówek
liczba_zdjec_podglad	int	Liczba zdjęć w podglądzie (nie jest to liczba wszystkich zdjęć)
zdjecia_miniatury	array	Adresy miniatur

Przykładowa odpowiedź (fragment)

{
  "success": true,
  "data": {
    "place_id": "ChIJ30f3sHaZBUcRSdmw0rjcnVA",
    "details": {
      "nazwa_wizytowki": "Perfect Look Clinic Leszno",
      "adres_ulica": "17 Stycznia 90",
      "adres_kod": "64-100",
      "adres_miasto": "Leszno",
      "srednia_ocen": 4.8,
      "liczba_opinii": 48,
      "status_dzialalnosci": "otwarte",
      "przejeta": true,
      "rezerwacja_online": true,
      "rezerwacja_dostawca": "Booksy",
      "liczba_postow": 10,
      "ostatni_post_dni_temu": 0,
      "szczyt_dzien": "sobota",
      "szczyt_godzina": "09:00",
      "szczyt_obciazenie": 100,
      "atrybuty": [
        { "grupa": "Ułatwienia dostępu", "pozycje": ["Wejście dostępne dla osób na wózkach"] }
      ],
      "inni_wyszukiwali": [
        { "nazwa": "Centrum Estetyki Your Beauty", "ocena": 4.8, "liczba_opinii": 71 }
      ]
    }
  }
}

Parametry

Parametr	Wymagany	Opis
placeid	tak	ChIJ… lub 0x…:0x…
count	nie	Liczba opinii, 1–2000. Domyślnie 10 — Google zwraca 10 opinii na stronę, więc to najtańsze zapytanie (~1 s; każda kolejna strona +0,55 s). Powyżej 2000 potrzebny byłby model asynchroniczny — 3000 opinii to ~296 s, czyli tyle, ile wynosi limit czasu proxy