ZnajdzPlaceID API — dokumentacja

• Wersja: 2.0.0
• Ostatnia aktualizacja: 2026-10-07
• Adres bazowy: https://znajdzplaceid.pl/api/
• Ta dokumentacja jako Markdown: https://znajdzplaceid.pl/api-docs.php?format=md
• Specyfikacja maszynowa (OpenAPI 3.0): https://znajdzplaceid.pl/api-docs/openapi.yaml

API zwraca dane wizytówek Google Maps: wyszukiwanie Place ID, szczegóły wizytówki, listy opinii (z sortowaniem i filtrem gwiazdek), zdjęcia, profile autorów opinii i sprawdzanie, czy konkretna opinia jest publicznie widoczna. Nie korzysta z oficjalnego Google Places API — dane pochodzą z tych samych źródeł co strona Map.

---

Spis treści

1. Informacje ogólne
2. Identyfikatory miejsc
3. Szybki start — typowe scenariusze
4. Endpointy GET

• /search · /details · /all
• /place-reviews · /review-job
• /place-photos · /user-profile
• /review-visibility · /review-details · /info

5. Endpointy POST — /convert, /batch, /parse-*
6. Obiekt opinii
7. Obiekt wizytówki (details)
8. Błędy i limity
9. Znane ograniczenia
10. Historia zmian

---

1. Informacje ogólne

Wywołanie

Każdy endpoint jest dostępny w dwóch równoważnych postaciach:

GET https://znajdzplaceid.pl/api/details?placeid=ChIJ...
GET https://znajdzplaceid.pl/api/?endpoint=details&placeid=ChIJ...

Parametry GET przekazuje się w query stringu (kodowanie URL, UTF-8). Endpointy POST przyjmują ciało application/json.

Uwierzytelnianie

Klucz API jest obecnie opcjonalny. Jeśli został przydzielony, przekaż go jednym ze sposobów:

• nagłówek Authorization: Bearer <API_KEY>
• parametr ?api_key=<API_KEY>

Klucz rozpoznany przez serwer daje osobny licznik limitu (zamiast liczenia po adresie IP).

Format odpowiedzi

Zawsze JSON (UTF-8). Sukces:

{
  "success": true,
  "data": { "...": "..." },
  "timestamp": "2026-10-07T12:55:10+00:00",
  "execution_time": "537.8ms"
}

Błąd:

{
  "success": false,
  "error": {
    "message": "Nie znaleziono Place ID dla podanego zapytania",
    "code": 400,
    "timestamp": "2026-10-07T12:56:15+00:00"
  },
  "execution_time": "800.69ms"
}

Kod HTTP odpowiedzi odpowiada polu error.code. Niektóre odpowiedzi zawierają dodatkowe pole techniczne proxy_ip — służy do diagnostyki, klient może je ignorować.

Konwencje

• Nazwy pól: endpointy details, batch i place-photos używają polskich nazw pól (nazwa_wizytowki, srednia_ocen…). Endpointy all, search, place-reviews i user-profile — angielskich. To celowe (zgodność wsteczna) i nie zmieni się.
• Daty: ISO 8601 w UTC (2026-09-06T12:47:31.098Z) albo RRRR-MM-DD. Pola *_text / *_tekst to tekst wyświetlany przez Google po polsku („miesiąc temu”).
• Brak danych = null (nigdy pusty string w miejsce liczby). Listy bez elementów = [].
• Google zwraca treści w języku polskim (hl=pl).

---

2. Identyfikatory miejsc

CID to druga połowa fid zapisana dziesiętnie. Wszystkie formaty da się przeliczyć przez /search (zwraca place_id, fid i cid naraz) albo POST /convert.

---

3. Szybki start — typowe scenariusze

Znajdź wizytówkę po nazwie:

GET /api/search?query=Qultova Myślenice

Negatywne opinie wizytówki (1–3★), od najgorszych:

GET /api/place-reviews?placeid=ChIJBQyGzddtFkcRLnmqsFHqdYU&max_stars=3&count=100

Przy max_stars ≤ 3 API samo sortuje od najniższych ocen i kończy pobieranie, gdy dalej są już tylko lepsze oceny — dostajesz komplet negatywnych w 1–3 s.

Tylko nowe opinie od ostatniego sprawdzenia:

GET /api/place-reviews?placeid=...&sort=najnowsze&count=50

i odrzuć po swojej stronie opinie starsze niż poprzedni odczyt (porównuj date_created).

Pełna lista dużej wizytówki (setki/tysiące opinii) — tryb asynchroniczny:

GET /api/place-reviews?placeid=...&count=5000&sort=najnowsze&async=1   → job_id
GET /api/review-job?id=<job_id>                                        → stan
GET /api/review-job?id=<job_id>&wynik=1                                → opinie

Czy konkretna opinia jest widoczna publicznie:

GET /api/review-visibility?url=https://www.google.com/maps/contrib/<ID autora>/place/<Place ID>/

---

4. Endpointy GET

/search

Zamienia nazwę, URL, CID albo Place ID na Place ID. Przy wyszukiwaniu po nazwie zwraca też dane najlepszego trafienia i do 4 alternatyw — zawsze sprawdź name/address, zanim użyjesz wyniku (dla nazw sieciowych pierwszy wynik może być inną placówką).

GET /api/search?query=<tekst>

Pole type mówi, co rozpoznano: search_result (wyszukanie po nazwie/URL), cid_converted (podano CID), direct_place_id (podano Place ID — zwracany bez sprawdzania).

{
  "success": true,
  "data": {
    "query": "Qultova Myślenice",
    "place_id": "ChIJBQyGzddtFkcRLnmqsFHqdYU",
    "type": "search_result",
    "name": "Qultova | Restauracja & Bar",
    "address": "Zdrojowa 1, 32-400 Myślenice",
    "fid": "0x47166dd7cd860c05:0x8575ea51b0aa792e",
    "cid": "9616850215896774958",
    "categories": ["Restauracja", "Bar", "Pizzeria"],
    "rating": 4.5,
    "alternatives": [
      { "place_id": "ChIJ...", "name": "...", "address": "..." }
    ]
  }
}

Pola name, address, fid, cid, categories, rating, alternatives występują przy type = search_result dla wyszukiwania po nazwie. Czas: ~0,5–1 s. Brak wyniku → HTTP 400.

---

/details

Pełne dane wizytówki (≈60 pól) w jednym żądaniu, ~0,5–1 s.

GET /api/details?placeid=<Place ID lub fid>

{
  "success": true,
  "data": {
    "place_id": "ChIJBQyGzddtFkcRLnmqsFHqdYU",
    "details": { "nazwa_wizytowki": "Qultova | Restauracja & Bar", "srednia_ocen": 4.5, "...": "..." },
    "uslugi": { "liczba_pozycji": 102, "liczba_kategorii": 22, "pozycje": [ ] }
  }
}

Opis wszystkich pól details: rozdział 7. Nieistniejący lub usunięty Place ID → HTTP 400 „Nie znaleziono miejsca dla podanego Place ID”.

---

/all

Jedno wywołanie dla dowolnego wejścia (URL, nazwa, CID, Place ID): rozpoznaje miejsce i zwraca jego dane pod angielskimi nazwami pól.

GET /api/all?url=<URL | nazwa | CID | Place ID>

{
  "success": true,
  "data": {
    "query": "Qultova Myślenice",
    "place_id": "ChIJBQyGzddtFkcRLnmqsFHqdYU",
    "source": "search_result",
    "cid": "9616850215896774958",
    "maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJBQyGzddtFkcRLnmqsFHqdYU",
    "maps_cid_url": "https://www.google.com/maps?cid=9616850215896774958",
    "details": {
      "name": "Qultova | Restauracja & Bar",
      "address": "Zdrojowa 1, 32-400 Myślenice",
      "category": "Restauracja",
      "categories": ["Restauracja", "Bar"],
      "subtypes": ["restaurant", "bar"],
      "rating": 4.5,
      "reviews_count": 282,
      "rating_breakdown": { "5_stars": 230, "4_stars": 10, "3_stars": 13, "2_stars": 11, "1_star": 18 },
      "cid": "9616850215896774958",
      "business_status": "otwarte",
      "claimed": true,
      "manager_id": "108146735889097402943",
      "website": "https://qultova.pl/",
      "phone": "511 335 417",
      "phone_raw": "511335417",
      "hours": [ { "dzien": "środa", "godziny": ["12:00–21:00"] } ],
      "description": "...",
      "has_description": true,
      "attributes": [ { "grupa": "Dostępne opcje", "pozycje": ["Ogródek", "Na wynos"] } ],
      "also_searched": [ { "nazwa": "...", "ocena": 4.9, "liczba_opinii": 844, "odleglosc_m": 1894 } ],
      "photos_preview_count": 4,
      "photo_thumbnails": ["https://lh3.googleusercontent.com/..."],
      "entity_id": "/g/11z5w5pv87",
      "street": "Zdrojowa 1",
      "postal_code": "32-400",
      "city": "Myślenice",
      "lat": 49.8216022,
      "lng": 19.9463146,
      "source": "place_details_parser"
    }
  }
}

Znaczenie pól jak w rozdziale 7 (business_status = status_dzialalnosci, claimed = przejeta, manager_id = zarzadca_id, also_searched = inni_wyszukiwali). source w data: search_result (nazwa lub URL) | direct_place_id | direct_cid.

---

/place-reviews

Lista opinii wizytówki z sortowaniem, filtrem gwiazdek i paginacją po stronie serwera.

GET /api/place-reviews?placeid=<ID>[&count=N][&sort=...][&min_stars=X][&max_stars=Y][&async=1]

Wartości sort:

Nieznana wartość sort jest traktowana jak trafnosc (bez błędu).

Automatyczne sortowanie: gdy podasz max_stars ≤ 3 i nie podasz sort, API użyje najnizsze i zwróci "sort_auto": true. Przy kolejności „trafność” negatywne opinie giną wśród pozytywnych (przykład: wizytówka z 15 tys. opinii — 1 negatywna wśród pierwszych 30 według trafności, 30 z 30 przy najnizsze). Żeby wymusić trafność, podaj jawnie sort=trafnosc.

Przy sortowaniu po ocenie serwer kończy paginację, gdy dalsze strony zawierają już tylko oceny spoza zakresu min_stars/max_stars, więc count można ustawić z zapasem bez kosztu czasu.

Odpowiedź:

{
  "success": true,
  "data": {
    "place_id": "ChIJBQyGzddtFkcRLnmqsFHqdYU",
    "place_info": {
      "name": "Qultova | Restauracja & Bar",
      "address": "Zdrojowa 1, 32-400 Myślenice",
      "rating": 4.5,
      "reviews_count": 282
    },
    "sort": "najnizsze",
    "sort_auto": true,
    "reviews": [ { "...": "obiekt opinii, rozdział 6" } ],
    "total_fetched": 42,
    "error": null,
    "performance": {
      "execution_time": 2.41,
      "reviews_returned": 42,
      "service_ms": 1850,
      "zrodlo": "boq"
    }
  }
}

total_fetched = liczba opinii w reviews po filtrze gwiazdek. reviews_count w place_info = całkowita liczba opinii wizytówki według Google.

Czas: 10 opinii ~1 s; 100 opinii ~2–3 s; kolejne strony po ~0,3–0,6 s (pierwsza strona to 10 opinii, następne po 20). Dla kilkuset i więcej opinii używaj async=1 — połączenie synchroniczne trzyma klienta przez cały czas pobierania.

Kompletność: sortowanie trafnosc pomija część opinii bez tekstu (tak samo jak widok Map — ok. 10–12%). Pełną listę daje sort=najnowsze.

---

/review-job

Odbiór zadania zgłoszonego przez place-reviews&async=1.

Zgłoszenie (odpowiada od razu, ~0,5–1 s):

GET /api/place-reviews?placeid=<ID>&count=5000&sort=najnowsze&async=1

{
  "success": true,
  "data": {
    "place_id": "ChIJ...",
    "place_info": { "name": "...", "address": "...", "rating": 4.8, "reviews_count": 1173 },
    "async": true,
    "job_id": "6c59b407-9ed4-4741-8ce2-40a187857429",
    "stan": "oczekuje",
    "w_kolejce": 1,
    "szacowany_czas_s": 360,
    "sort": "najnowsze",
    "sort_auto": false,
    "odbior": "/api/review-job?id=6c59b407-9ed4-4741-8ce2-40a187857429&wynik=1"
  }
}

Stan i wynik:

GET /api/review-job?id=<job_id>[&wynik=1]

{
  "success": true,
  "data": {
    "job_id": "6c59b407-...",
    "stan": "gotowe",
    "gotowe": true,
    "total_fetched": 32,
    "pages": 3,
    "elapsed_ms": 1912,
    "error": null,
    "reviews": [ ]
  }
}

• stan: oczekuje → trwa → gotowe albo blad (wtedy powód w error).
• Filtr min_stars/max_stars z zgłoszenia jest stosowany do wyniku (total_fetched = po filtrze).
• Wynik jest przechowywany 6 godzin; potem HTTP 404.
• Zadania przerwane restartem serwisu wznawiają się automatycznie.
• Naraz wykonują się 2 zadania; kolejka do 50 — przy pełnej kolejce zgłoszenie dostaje HTTP 429 (ponów po chwili).
• job_id jest jedynym zabezpieczeniem wyniku — nie udostępniaj go publicznie.

---

/place-photos

Zdjęcia wizytówki z rozbiciem na właściciela i klientów, źródłem (urządzeniem) i statystykami aktywności właściciela. ~0,4–1 s.

GET /api/place-photos?placeid=<ID>[&count=N]

Element listy zdjęć:

{
  "id": "CIABIhBtelQPmF1uoSQ5H6DQddtB",
  "url": "https://lh3.googleusercontent.com/...",
  "szerokosc": 8192,
  "wysokosc": 5464,
  "od_wlasciciela": true,
  "zrodlo": "bizbuilder:gmb_on_local_universal_desktop",
  "urzadzenie": "desktop",
  "system": null,
  "data": "2026-05-04"
}

urzadzenie: mobile | desktop | null; system: android | ios | null. Uwaga: udział zdjęć z desktopu zależy głównie od wieku zdjęć (starsze częściej z komputera), nie od autentyczności.

---

/user-profile

Profil autora opinii (kontrybutora Map). ~0,5 s.

GET /api/user-profile?id=<ID autora>

Wskazówka: różnica review_count − review_count_visible to opinie autora ukryte przez Google. Wysoki odsetek ukrytych opinii u autorów danej wizytówki to najmocniejszy znany sygnał fałszywych opinii.

---

/review-visibility

Sprawdza, czy konkretna opinia jest publicznie widoczna. ~0,3–1 s.

GET /api/review-visibility?url=<URL opinii>

Obsługiwane formaty url:

• https://www.google.com/maps/contrib/<ID autora>/place/<Place ID>/ — zalecany
• link „Udostępnij opinię” (https://maps.app.goo.gl/...)
• https://www.google.com/maps/reviews/data=...

{
  "success": true,
  "data": {
    "review_url": "https://www.google.com/maps/contrib/.../place/.../",
    "is_visible": false,
    "visibility_reason": "no_rating",
    "checked_at": "2026-10-07 13:06:12"
  }
}

Traktuj rate_limited_by_google, failed_to_fetch i unknown jako „brak odpowiedzi”, a nie „niewidoczna”.

---

/review-details

Szczegóły pojedynczej opinii z linku (autor, ocena, tekst, miejsce) wraz z widocznością.

GET /api/review-details?url=<URL opinii>

Zwraca data.review_details z polami: name, profile_name, review_text, date, date_unix, rating, place_name, place_id, place_address, place_coordinates, place_types, place_country, reviewer_id, reviewer_avatar, reviewer_profile_url, reviewer_total_reviews, reviewer_total_photos, reviewer_level, reviewer_points, review_id, review_language, review_length, photos_count, review_likes, is_visible, visibility_reason, review_url. Pola, których nie udało się odczytać, mają wartość null. Do samej widoczności używaj szybszego /review-visibility.

---

/info

Nazwa, wersja i lista endpointów. GET /api/info.

---

5. Endpointy POST

Ciało: Content-Type: application/json.

/convert

{ "cid": "9616850215896774958" }

→ { "cid": "...", "place_id": "ChIJBQyGzddtFkcRLnmqsFHqdYU", "conversion_type": "cid_to_place_id" }

{ "place_id": "ChIJBQyGzddtFkcRLnmqsFHqdYU" }

→ { "place_id": "...", "cid": "9616850215896774958", "conversion_type": "place_id_to_cid" }

/batch

Szczegóły kilku wizytówek naraz (pola jak w details).

{ "place_ids": ["ChIJ...", "ChIJ..."], "max_concurrent": 3 }

• do 10 Place ID na żądanie, max_concurrent 1–5 (domyślnie 3);
• data.results to obiekt { "<place_id>": { ...pola details... } | null } — null oznacza, że tej pozycji nie udało się pobrać (ponów ją pojedynczo przez /details);
• data.performance: processed_count, success_count, execution_time.

/parse-review, /parse-place, /parse-user

Parsują surowy APP_INITIALIZATION_STATE ze strony Map, jeśli pobierasz HTML samodzielnie. Ciało: { "app_state": <tablica JSON> }. Odpowiedzi odpowiadają odpowiednio review-details, details i user-profile.

---

6. Obiekt opinii

Element listy reviews w place-reviews i review-job.

{
  "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2xoek5EQkNlVFV0VXpSSVNXSjRiRUZWV1V...",
  "review_url": "https://www.google.com/maps/reviews/data=!4m8!14m7!...",
  "stars": 3,
  "review_text": "Zacznę od wystroju lokalu...",
  "review_language": "pl",
  "review_text_length": 1288,
  "likes_count": 1,
  "date_text": "miesiąc temu",
  "date_created": "2026-09-06T12:47:31.098Z",
  "date_created_ms": 1788698851098,
  "date_created_micros": 1788698851098000,
  "review_edited": false,
  "date_edited": null,
  "date_edited_micros": null,
  "review_source": "Google",
  "relevance_score": null,
  "author_name": "Jan K.",
  "author_id": "104085176304769949774",
  "author_profile_url": "https://www.google.com/maps/contrib/104085176304769949774/reviews",
  "author_avatar_url": "https://lh3.googleusercontent.com/a-/...",
  "author_review_count": 124,
  "author_photo_count": 406,
  "author_is_local_guide": true,
  "author_level": null,
  "photos_count": 1,
  "photos": [
    { "url": "https://lh3.googleusercontent.com/...", "id": "CIABIhByQXuC...", "proporcje": 1.333, "data_tekst": "miesiąc temu" }
  ],
  "owner_response_text": "Dziękujemy za opinię...",
  "has_owner_response": true,
  "owner_response_date": null,
  "owner_response_date_micros": null,
  "owner_response_date_text": "3 tygodnie temu",
  "owner_response_length": 270,
  "source": "boq"
}

Pola zachowane dla zgodności, obecnie zawsze null: relevance_score, author_level (poziom Local Guide — pobierz z /user-profile), owner_response_date, owner_response_date_micros (Google podaje tylko tekst daty — użyj owner_response_date_text).

---

7. Obiekt wizytówki (details)

Pola obiektu data.details w /details i elementów data.results w /batch.

Identyfikacja i podstawy

Kategorie

Oceny

Kontakt i status

Właściciel i zarządzanie

Zdjęcia (podgląd)

Pozostałe

Cennik usług (uslugi=1) — obiekt data.uslugi: liczba_pozycji, liczba_kategorii, pozycji_z_cena, pozycji_z_opisem, kategorie (lista nazw), pozycje (lista { kategoria, nazwa, opis, cena, czas, link }, np. "cena": "49,00 zł", "czas": "1 godz. 15 min"). Występuje u ok. 25% wizytówek.

---

8. Błędy i limity

Kody HTTP

Limity

Licznik jest per klucz API (gdy podany i rozpoznany), w przeciwnym razie per adres IP. Nagłówki odpowiedzi: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (znacznik czasu Unix).

Zalecenia dla integracji

• Timeout klienta: ≥ 30 s dla place-reviews synchronicznie (100 opinii), ≥ 60 s dla batch. Dla większych pobrań — async=1.
• Ponawiaj przy 429/500/503 z rosnącym odstępem (np. 5 s, 15 s, 60 s); przy 400 nie ponawiaj.
• Opinie deduplikuj po review_id.
• Nie wysyłaj kilku dużych pobrań tej samej wizytówki równolegle — dostaniesz te same dane.

---

9. Znane ograniczenia

• Pytania i odpowiedzi (Q&A) — Google wyłączył tę funkcję (XI–XII 2025); API ich nie zwraca.
• Tematy opinii („Klienci wspominają…”) — Google ich nie udostępnia; brak w API.
• owner_response_date, relevance_score, author_level w opiniach — zawsze null (rozdział 6).
• Dla opinii edytowanej date_created jest czasem edycji.
• status_dzialalnosci = zamkniete (bez rodzaju) bywa nietrafny — zweryfikuj godziny.
• Liczniki zdjęć w details są z podglądu; dokładne — /place-photos.
• Wyniki zależą od Google i mogą się zmienić bez zapowiedzi. Przy nagłej zmianie formatu dane przejściowo mogą być niepełne — zgłoś to, podając zapytanie i czas.

---

10. Historia zmian

2.0.0 — 2026-10-07

• /review-visibility — naprawa po zmianie strony Map (07.10, 00:00–13:05 UTC wszystkie sprawdzenia zwracały unknown; wyniki z tego okna należy powtórzyć).
• /search, POST /convert — naprawione wyszukiwanie po nazwie i konwersja CID → Place ID. /search zwraca dodatkowo name, address, fid, cid, categories, rating, alternatives.
• Dokumentacja przepisana; dodana specyfikacja OpenAPI.

2026-09-30

• /place-reviews — nowe źródło danych (duże wizytówki znów zwracają komplet opinii).
• Nowe wartości sort: najnizsze/lowest, najwyzsze/highest, trafnosc/relevance.
• Automatyczne sort=najnizsze przy max_stars ≤ 3 bez sort (pole sort_auto).
• Tryb async=1 stosuje filtr min_stars/max_stars; zadania przeżywają restart.
• Pole performance.zrodlo. W opiniach nowe pola date_text, owner_response_date_text, date_created_ms; relevance_score, author_level, owner_response_date = null.

2026-08

• /place-photos (zdjęcia właściciela/klientów, urządzenie, statystyki), /user-profile (liczniki widocznych/ukrytych opinii), tryb async=1 z /review-job, rozszerzone pola details (kategoria_gcid, gbp_id, posty, rezerwacje, popularne godziny, uslugi=1).

2026-01-02

• Endpoint /place-reviews.