Spis treści
ten Interfejs API Miejsc Google obsługuje wyszukiwanie miejsc, autouzupełnianie, wyszukiwanie obiektów w pobliżu, informacje o firmach oraz inne funkcje oparte na lokalizacji. Prawdziwym wyzwaniem jest podjęcie decyzji, która usługa Places najlepiej nadaje się do danego zadania, o które pola warto poprosić oraz jak te wybory wpływają na koszty.
Przejście Google na Places API (nowa wersja) zmienia sposób, w jaki programiści obsługują żądania, wybór pól, dane odpowiedzi oraz rozliczenia. Starsze wzorce implementacji nie zawsze da się bezproblemowo przenieść, zwłaszcza gdy w grę wchodzą maski pól i cennik oparty na kodach SKU.
Odpowiednia konfiguracja zależy od tego, co tworzysz. Wyszukiwanie lokalizacji w aplikacji może wymagać jedynie niewielkiego zestawu informacji o miejscu. Zespół korzystający z Interfejs API Google Places do pozyskiwania potencjalnych klientów W wielu miastach może być konieczne zastosowanie innego schematu działania. Traktowanie obu przypadków użycia w ten sam sposób może generować niepotrzebne koszty i wymagać dodatkowej pracy nad interfejsem API.
Przed wyborem punktu końcowego lub oszacowaniem miesięcznego zużycia warto zapoznać się z tym, jak Google organizuje wyszukiwanie w Places, wybór pól, rozliczenia i limity. Wiedza ta ułatwia również ocenę, kiedy oficjalny interfejs API Places nadaje się do danego zadania, a kiedy bardziej sensowne jest zastosowanie odrębnego procesu przetwarzania danych biznesowych.
Krótka odpowiedź: Jak działa interfejs API Google Places
- Wyszukuj miejsca za pomocą funkcji wyszukiwania tekstowego lub wyszukiwania w pobliżu.
- Uzyskaj szczegółowe informacje, zdjęcia i identyfikatory miejsc dla konkretnych lokalizacji.
- Skorzystaj z funkcji autouzupełniania, aby wyświetlać propozycje miejsc w trakcie wpisywania przez użytkowników.
- Skonfiguruj projekt w Google Cloud, rozliczenia oraz klucz API z ograniczonymi uprawnieniami.
- Wykorzystaj maski pól do kontrolowania zwracanych danych i rozliczeń.
- Koszty zależą od rodzaju usługi, wybranych pól oraz sposobu użytkowania.
- W przypadku dużych zbiorów danych biznesowych lub dodatkowych pól kontaktowych lepszym rozwiązaniem może być inny proces przetwarzania danych.
Czym jest interfejs API Google Places?
Interfejs API Google Places stanowi część platformy Google Maps Platform. Zapewnia on programistom programowy dostęp do informacji o firmach, punktach orientacyjnych, adresach, lokalizacjach geograficznych i innych miejscach wymienionych w bazie danych miejsc Google.
Google obecnie podaje, że Interfejs API „Miejsca” (nowość) udostępnia dane lokalizacyjne dotyczące ponad 200 milionów miejsc. Programiści mogą z nich korzystać, aby dodawać do stron internetowych, aplikacji mobilnych i innego oprogramowania funkcje wyszukiwania miejsc, odkrywania obiektów w pobliżu, autouzupełniania, szczegółowych informacji o miejscach oraz zdjęć.
Typowe zapytanie zaczyna się od frazy wyszukiwania, obszaru geograficznego lub znanego identyfikatora miejsca (Place ID). Google zwraca ustrukturyzowane informacje o miejscu w oparciu o rodzaj zapytania oraz pola wybrane przez programistę.
Na przykład aplikacja służąca do wyszukiwania restauracji mogłaby wykorzystać funkcję „Wyszukiwanie w pobliżu”, aby znaleźć restauracje w okolicy lokalizacji użytkownika. Gdy użytkownik wybierze restaurację, aplikacja mogłaby wysłać żądanie o szczegóły miejsca, aby uzyskać takie informacje, jak adres, ocena, godziny otwarcia, numer telefonu czy recenzje.
Jakie dane może zwrócić interfejs API Google Places?
Dostępne pola zależą od żądania oraz od pól zawartych w masce pól. Interfejs API Places (nowy) może zwracać takie informacje, jak:
| Typ danych | Przykładowe pola | Co opisuje |
|---|---|---|
| Tożsamość | Nazwa miejscowości, identyfikator miejscowości, typ miejscowości | Określa lokalizację oraz jej kategorię. |
| Lokalizacja | Adres, współrzędne geograficzne | Pokazuje, gdzie znajduje się to miejsce. |
| Dane firmy | Informacje o firmie, numer telefonu, strona internetowa, godziny otwarcia | Zawiera informacje operacyjne i kontaktowe. |
| Informacje o kliencie | Oceny, recenzje, informacje o cenie | Zawiera dane dotyczące ocen, recenzji i cen. |
| Media | Zdjęcia | Zwraca dostępne zdjęcia powiązane z danym miejscem. |
| Dostępność | Informacje dotyczące dostępności | Opisuje obsługiwane funkcje ułatwień dostępu. |
| Opcje usług | Dostawa, posiłki na miejscu, odbiór przy lokalu | Wyświetla dostępne opcje usług, o ile są one obsługiwane. |
Google dzieli te pola na różne poziomy cenowe. Niektóre podstawowe pola należą do tańszych pozycji asortymentowych (SKU), natomiast pola takie jak oceny, godziny otwarcia i recenzje mogą powodować naliczanie opłat za droższe pozycje asortymentowe (SKU). Google wyjaśnia związek między polami a rozliczeniami w swoim Dokumentacja pól danych interfejsu API Places. Należy żądać wyłącznie tych pól, które są potrzebne aplikacji, ponieważ wybór pól może wpłynąć na kod SKU rozliczeniowy.
Interfejs API Places (nowy) wymaga również podania maski pól w żądaniach dotyczących szczegółów miejsca, wyszukiwania tekstowego oraz wyszukiwania w pobliżu. Należy określić co najmniej jedno pole. Żądanie bez maski pól powoduje zwrot błędu.
Jak interfejs API Places wpisuje się w platformę Google Maps
Interfejs API Places obsługuje informacje o miejscach, ale stanowi jedynie jedną z części platformy Google Maps.
Programista może skorzystać z interfejsu API Places, aby znaleźć firmę, a następnie użyć innej usługi z platformy Google Maps do wykonania innego zadania. Na przykład interfejs API geokodowania może przekształcić adres na współrzędne, natomiast usługi wyznaczania tras mogą obliczyć trasę lub czas podróży między lokalizacjami.
W ramach samego interfejsu API Places główne usługi obsługują różne etapy procesu wyszukiwania miejsc:
- Wyszukiwanie tekstowe wyszukuje miejsca na podstawie wpisanych zapytań.
- Wyszukiwanie w pobliżu wyszukuje miejsca na określonym obszarze geograficznym.
- Szczegóły dotyczące miejsca pobiera informacje o znanym miejscu.
- Autouzupełnianie podpowiada lokalizacje w miarę wpisywania tekstu przez użytkownika.
- Umieść zdjęcia pobiera dostępne zdjęcia powiązane z danym miejscem.
Google zaleca stosowanie Szczegóły dotyczące miejsca gdy identyfikator miejsca jest już znany, ponieważ nie ma potrzeby wysyłania kolejnego zapytania dotyczącego tego samego miejsca.
Wyszukiwanie firm w całym mieście, pole autouzupełniania oraz zapytanie o szczegóły dotyczące jednej znanej lokalizacji wymagają zastosowania różnych metod interfejsu API Places.
Jak działa interfejs API Google Places
Interfejs API Google Places wykorzystuje różne metody w zależności od posiadanych już danych wejściowych oraz rodzaju potrzebnych danych dotyczących miejsc.
Zapytanie tekstowe, zestaw współrzędnych oraz znany identyfikator miejsca wymagają zastosowania różnych metod. Interfejs API miejsc (nowy) udostępnia obecnie funkcje wyszukiwania tekstowego, wyszukiwania w pobliżu, szczegółów miejsca, autouzupełniania oraz zdjęć miejsca, które służą do realizacji tych zadań.
Wyszukiwanie tekstowe
Funkcja wyszukiwania tekstowego pozwala znaleźć miejsca na podstawie wpisanego zapytania, takiego jak nazwa firmy, kategoria, adres lub fraza, np. pizza in New York.
Funkcja „Wyszukiwanie tekstowe (nowość)” wykorzystuje żądanie HTTP POST i zwraca pasujące obiekty typu „Miejsce”. Opcjonalne parametry pozwalają zawęzić wyniki według lokalizacji, rodzaju miejsca, statusu otwarcia, oceny lub przedziału cenowego.
Google wyświetla obecnie do 60 wyników na wszystkich stronach i zaznacza, że identyczne zapytania nie zawsze zwracają tę samą listę wyników.
Wyszukiwanie w pobliżu
Funkcja „Wyszukiwanie w pobliżu” pozwala znaleźć miejsca w obrębie określonego obszaru geograficznego.
W zapytaniu podaje się szerokość geograficzną, długość geograficzną i promień, a następnie filtruje wyniki według jednego lub kilku typów miejsc. Na przykład aplikacja może wyszukać restauracje znajdujące się w określonej odległości od hotelu.
Funkcja „Wyszukiwanie w pobliżu” (nowość) również wykorzystuje metodę HTTP POST i wymaga maski pola dla zwracanych danych.
Szczegóły dotyczące miejsca
Funkcja „Szczegóły miejsca” pobiera informacje o jednym znanym miejscu na podstawie jego identyfikatora miejsca.
Typowy przebieg procesu wygląda następująco:
- Znajdź miejsce, korzystając z wyszukiwania tekstowego, wyszukiwania w pobliżu lub autouzupełniania.
- Zachowaj jego identyfikator miejsca.
- Proszę żądać wyłącznie tych danych, które są niezbędne dla działania aplikacji.
Dzięki temu nie trzeba przeprowadzać kolejnego wyszukiwania, gdy miejsce zostało już zidentyfikowane.
Autouzupełnianie
Funkcja autouzupełniania podpowiada lokalizacje w trakcie wpisywania tekstu przez użytkownika w polu wyszukiwania.
Token sesji pozwala pogrupować żądania użytkownika w jedną sesję wyszukiwania na potrzeby rozliczeń. Każde nowe wyszukiwanie powinno wykorzystywać nowy token, a sesja powinna zakończyć się zgodnym żądaniem typu „Szczegóły miejsca” lub „Weryfikacja adresu”.
Zdjęcia miejsc i identyfikatory miejsc
Funkcja „Zdjęcia związane z miejscem” pobiera zdjęcia powiązane z danym miejscem, gdy photos Pole to jest zwracane przez funkcję „Wyszukiwanie tekstowe”, „Wyszukiwanie w pobliżu” lub „Szczegóły miejsca”.
Identyfikatory miejsc służą do identyfikacji konkretnych lokalizacji, dzięki czemu można się do nich odwoływać w różnych obsługiwanych usługach platformy Google Maps.
Na przykład aplikacja może znaleźć firmę za pomocą wyszukiwania tekstowego, zapisać jej identyfikator miejsca (Place ID), a następnie uzyskać szczegółowe informacje o tym miejscu bez konieczności ponownego przeprowadzania pierwotnego wyszukiwania.
Interfejs API Places (nowy) a interfejs API Places (starsza wersja)
1 marca 2025 r. firma Google nadała pierwotnemu interfejsowi API Places status „Legacy”. Istniejące projekty mogą nadal z niego korzystać, ale w nowych projektach w chmurze nie można włączać usług typu „Legacy”.
Interfejs API Places (nowa wersja) jest obecnie wersją zalecaną przez Google do nowych projektów. Zmiany dotyczą metod żądań, wyboru pól, struktury odpowiedzi, uwierzytelniania oraz rozliczeń.
Co się zmieniło w Places API (nowości)?
Wyszukiwanie tekstowe i wyszukiwanie w pobliżu wykorzystują teraz metodę HTTP POST zamiast schematu opartego na metodzie GET, z którego korzystała starsza wersja.
Interfejs API „Miejsca” (nowy) obsługuje również klucze API i protokół OAuth, zwraca odpowiedzi w formacie JSON oraz wymaga podania masek pól w przypadku funkcji „Szczegóły miejsca”, „Wyszukiwanie tekstowe” i „Wyszukiwanie w pobliżu”.
Aplikacja „Find Place” nie ma bezpośredniej nowej wersji. Google przekierowuje takie wyszukiwania do funkcji „Wyszukiwanie tekstowe”.
Maska pól i zmiany w reakcjach
Maska pól stanowi jedną z głównych różnic między interfejsem API Places (nowym) a starszą wersją tego interfejsu.
W przypadku funkcji „Szczegóły miejsca”, „Wyszukiwanie tekstowe” i „Wyszukiwanie w pobliżu” żądanie musi określać co najmniej jedno pole, które ma zostać zwrócone. Pominięcie maski pola spowoduje niepowodzenie żądania.
Wybór pól ma również wpływ na rozliczenia, ponieważ Google przypisuje pola danych dotyczących lokalizacji do różnych jednostek SKU. W sekcji poświęconej cenom, znajdującej się w dalszej części tego artykułu, wyjaśniono tę zależność bardziej szczegółowo.
Zmieniły się również obiekty odpowiedzi. Interfejs API Places (nowy) wykorzystuje nazwy pól zapisane w formacie camelCase zamiast wielu nazw w formacie snake_case, które występowały w starych odpowiedziach.
Przykłady to między innymi:
adres sformatowanystaje sięadres sformatowanystan_przedsiębiorstwastaje sięstatus firmysformatowany_numer_telefonicznystaje sięnumer telefonu krajowegogeometria.lokalizacjastaje sięlokalizacja
Funkcje „Wyszukiwanie tekstowe” i „Wyszukiwanie w pobliżu” również zwracają wyniki w postaci miejsca tablica zamiast starszej wersji wyniki tablica. Informacje o stanie i błędach wykorzystują teraz standardowe kody odpowiedzi HTTP i komunikaty zamiast starszych pól, takich jak status oraz komunikat o błędzie.
Zmiany te mają znaczenie w przypadku, gdy istniejące aplikacje analizują odpowiedzi w formacie Legacy lub opierają się na starszych nazwach pól.
Co użytkownicy starszej wersji API powinni wiedzieć o migracji
Migracja zazwyczaj wymaga czegoś więcej niż tylko zmiany punktu końcowego. Firma Google udostępnia Przewodnik po migracji interfejsu API Places przedstawiające główne różnice między interfejsem API Legacy a interfejsem API Places (nowym).
Najpierw sprawdź następujące obszary:
- Przenieś wyszukiwanie „Znajdź miejsce” do funkcji „Wyszukiwanie tekstowe (nowość)”.
- Zmień metodę żądań wyszukiwania tekstowego i wyszukiwania w pobliżu z GET na POST.
- Dodaj wymagane maski pól.
- Zaktualizuj kod odczytujący pola odpowiedzi w formacie Legacy.
- Sprawdź numer SKU użyty w każdym żądaniu.
Sprawdź również, czy w projekcie włączono interfejs API Places (nowy) i czy jest on dozwolony w ramach ograniczeń klucza API.
Jeśli podczas testów konieczne jest jednoczesne uruchamianie żądań typu „Legacy” i „New”, należy rozdzielić te dwa przepływy. Firma Google zaleca stosowanie oddzielnych kluczy API podczas migracji.
Dotychczasowe integracje typu „Legacy” mogą na razie nadal działać, ale w nowych projektach należy korzystać z Places API (nowa wersja).
Samouczek dotyczący interfejsu API Google Places: konfiguracja i pierwsze żądanie
Aby korzystać z Places API (nowa wersja), należy najpierw utworzyć projekt w Google Cloud powiązany z kontem rozliczeniowym. Przed wysłaniem uwierzytelnionych żądań należy włączyć obsługę Places API (nowa wersja) w tym projekcie.
W przypadku podstawowego żądania do usługi internetowej konfiguracja przebiega w pięciu krokach: wybierz projekt w chmurze, włącz API, utwórz klucz API, ogranicz uprawnienia klucza oraz wyślij żądanie zawierające pola, których wyniki chcesz otrzymać.
Utwórz lub wybierz projekt Google Cloud
Każde żądanie wysyłane do platformy Google Maps należy do projektu w Google Cloud.
Możesz utworzyć nowy projekt lub skorzystać z już istniejącego. Wybrany projekt musi również posiadać aktywne konto rozliczeniowe. Firma Google wykorzystuje projekt do śledzenia dostępu do interfejsu API, wykorzystania, limitów oraz opłat.
Prowadzenie oddzielnych projektów może mieć sens również wtedy, gdy środowiska programistyczne, testowe i produkcyjne wymagają różnych danych uwierzytelniających lub różnych mechanizmów kontroli dostępu.
Po wybraniu odpowiedniego projektu można włączyć usługę Places API (Nowa) w konsoli Google Cloud.
Włącz interfejs API Places (nowość)
Aby aplikacja mogła wywoływać metody usługi internetowej Places API (nowość), należy najpierw włączyć tę usługę dla danego projektu.
W konsoli Google Cloud:
- Wybierz projekt, z którego chcesz skorzystać.
- otwarty Interfejsy API i usługi.
- Znajdź Interfejs API „Miejsca” (nowość) w bibliotece API.
- Włącz tę opcję dla projektu.
To rozróżnienie ma znaczenie w przypadku starszych projektów, ponieważ Places API (Legacy) i Places API (New) to odrębne usługi. W projekcie, w którym wcześniej korzystano z interfejsu API Legacy, może być konieczne włączenie Places API (New), aby nowsze punkty końcowe działały poprawnie.
Konfiguracja klucza API i ograniczenia
Klucz API identyfikuje projekt Google Cloud, z którego pochodzi żądanie.
Google wymaga, aby rozliczenia były włączone, zanim będzie można korzystać z interfejsu API Places (nowy) w ramach rzeczywistych żądań. Jeśli dopiero przechodzisz przez proces konfiguracji i nie chcesz jeszcze podłączać konta rozliczeniowego, możesz zatrzymać się przed utworzeniem klucza i wrócić do tego kroku później.
Jeśli rozliczenia są włączone, utwórz klucz API w Google Cloud Console i ogranicz jego uprawnienia przed użyciem go w aplikacji.
W przypadku żądań kierowanych do interfejsu Places API po stronie serwera ograniczenie dotyczące adresów IP może sprawić, że klucz będzie działał wyłącznie na zatwierdzonych serwerach. Można również ograniczyć zakres działania klucza tak, aby działał on wyłącznie z interfejsem Places API (New) oraz innymi usługami Google Maps Platform, które są faktycznie potrzebne aplikacji.
Google wymaga również, aby żądania kierowane do usługi internetowej Places API były wysyłane za pomocą protokołu HTTPS. Brak klucza, nieprawidłowe ograniczenie lub nieobsługiwana konfiguracja mogą spowodować zwrot komunikatu REQUEST_DENIED odpowiedź.
Przykłady korzystania z interfejsu API Google Places: Wyślij swoje pierwsze zapytanie tekstowe
„Wyszukiwanie tekstowe” to prosty przykład wykorzystania interfejsu API Google Places, który pozwala zapoznać się z formatem żądania, nagłówkiem klucza API oraz maską pól.
Interfejs API Places (nowy) wysyła żądania wyszukiwania tekstowego do:
https://places.googleapis.com/v1/places:searchText
Żądanie wykorzystuje metodę HTTP POST. Tekst wyszukiwania należy umieścić w treści JSON, natomiast klucz API i maska pola mogą być przesłane w nagłówkach żądania.
Podstawowe zapytanie może wyglądać następująco:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress" \
-d '{ "textQuery": "dentists in Chicago" }' \
"https://places.googleapis.com/v1/places:searchText"
To zapytanie wyszukuje dentists in Chicago i prosi Google o wyświetlenie wyłącznie:
- Identyfikator miejsca
- nazwa wyświetlana
- adres w formacie
Pomyślna odpowiedź zwraca pasujące obiekty typu Place w obrębie places tablica. Pola zawarte w każdym wyniku zależą od maski pól użytej w żądaniu.
Zastosowanie maski ograniczającej zakres danych sprawia, że wynik jest bardziej czytelny i pozwala uniknąć pobierania danych, które nie są potrzebne aplikacji.
Aby zapoznać się z aktualnymi parametrami żądań, obsługiwanymi polami, limitami oraz zmianami w API, zajrzyj na oficjalną stronę Dokumentacja interfejsu API Google Places.
Przykład wykorzystania interfejsu API Google Places: Pobieranie szczegółowych informacji o miejscu
Wynik wyszukiwania tekstowego może zawierać identyfikator miejsca (Place ID) dla każdej pasującej lokalizacji. Gdy aplikacja pozna identyfikator miejsca, może skorzystać z funkcji „Szczegóły miejsca” (Place Details), aby uzyskać informacje o tym konkretnym miejscu bez konieczności przeprowadzania kolejnego wyszukiwania.
Żądanie ma następujący format:
https://places.googleapis.com/v1/places/PLACE_ID
Na przykład:
curl -X GET -H "Content-Type: application/json" -H "X-Goog-Api-Key: YOUR_API_KEY" -H "X-Goog-FieldMask: id,displayName,formattedAddress" "https://places.googleapis.com/v1/places/PLACE_ID"
Zastąp PLACE_ID z identyfikatorem zwróconym przez funkcję wyszukiwania tekstowego, wyszukiwania w pobliżu lub inną obsługiwana metodę usługi „Miejsca”.
Zwróć uwagę, że maska pola „Szczegóły miejsca” wykorzystuje id, displayNameoraz formattedAddress zamiast places.id, places.displayNameoraz places.formattedAddress. Metoda „Place Details” zwraca jeden obiekt typu „Place”, natomiast metoda „Text Search” zwraca obiekty typu „Place” zawarte w places tablica.
Wybierz potrzebne pola
Funkcje „Szczegóły miejsca”, „Wyszukiwanie tekstowe” i „Wyszukiwanie w pobliżu” wymagają podania maski pola w interfejsie API Places (nowa wersja). Jeśli nie podano żadnego pola, żądanie zwraca błąd.
W przypadku wyszukiwania tekstowego maska pola może wyglądać następująco:
places.displayName,places.formattedAddress
Jeśli aplikacja wymaga również strony internetowej i oceny, szablon pola można rozszerzyć:
places.displayName,places.formattedAddress,places.websiteUri,places.rating
Google obsługuje również * jako symbol wieloznaczny dla wszystkich dostępnych pól, jednak odradza się stosowanie tego symbolu w środowisku produkcyjnym. Żądanie niepotrzebnych pól może zwiększyć ilość zwracanych danych i spowodować przejście żądania do wyższej taryfy rozliczeniowej.
Należy ograniczyć maskę pól wyłącznie do danych, z których aplikacja faktycznie korzysta. Wybór pól ma wpływ zarówno na koszt odpowiedzi, jak i na koszt żądania.
W poniższej sekcji poświęconej cenom wyjaśniono, w jaki sposób te opcje pól odpowiadają numerom SKU w interfejsie API Google Places.
Użyj Outscraper Skrobak Map Google w celu gromadzenia danych biznesowych za pomocą przepływu pracy typu „no-code”, bez konieczności konfigurowania poszczególnych żądań w ramach interfejsu API Places.
Ceny i bezpłatne korzystanie z interfejsu API Google Places
Interfejs API Google Places działa w modelu rozliczeń na zasadzie „płać za rzeczywiste wykorzystanie”. Każde żądanie jest rozliczane w ramach konkretnego kodu SKU, a jego koszt zależy od zastosowanej metody, żądanych pól oraz liczby miesięcznych zdarzeń podlegających rozliczeniu.
Firma Google nie korzysta już ze starego, cyklicznego limitu kredytowego $200 w ramach platformy Maps Platform. W obecnym modelu każdy kod SKU ma własny miesięczny limit bezpłatnego wykorzystania. Limity te są resetowane na początku każdego miesiąca.
Jak działają numery SKU w interfejsie API Google Places
SKU to kategoria rozliczeniowa przypisana do żądania kierowanego do interfejsu API Places.
Interfejs API Places (nowy) dzieli wiele żądań na poziomy cenowe, takie jak Essentials, Pro i Enterprise. Wybór żądanych pól może spowodować, że żądanie zostanie zakwalifikowane do droższego wariantu cenowego (SKU).
Na przykład pozycja „Szczegóły lokalizacji” może być rozliczana w ramach różnych numerów SKU w zależności od wybranych pól:
- Najważniejsze informacje o miejscu obejmuje miesięczny limit bezpłatnego wykorzystania wynoszący 10 000 zdarzeń.
- Miesięczny limit bezpłatnego wykorzystania dla Szczegóły lokalizacji Pro wynosi 5 000 zdarzeń.
- Dla Szczegóły dotyczące miejsca: Przedsiębiorstwo, miesięczny limit bezpłatnego wykorzystania wynosi 1 000 zdarzeń.
Po przekroczeniu limitu bezpłatnego korzystania opłaty naliczane są za każde 1 000 zdarzeń i maleją wraz ze wzrostem miesięcznego wolumenu.
Wyszukiwanie tekstowe i wyszukiwanie w pobliżu mają podobną strukturę.
W przypadku pierwszego poziomu płatnego korzystania z usługi firma Google podaje obecnie następujące stawki na oficjalnej stronie Strona z cennikiem platformy Google Maps:
*Dane te dotyczą pierwszego przedziału cenowego przedstawionego na globalnej stronie Google poświęconej cennikowi. W przypadku większych miesięcznych wolumenów obowiązują niższe stawki za 1 000.
Google oferuje również niektóre pozycje katalogowe przeznaczone wyłącznie do identyfikacji, z nieograniczonym bezpłatnym dostępem, w tym „Place Details Essentials (tylko identyfikatory)” oraz „Text Search Essentials (tylko identyfikatory)”.
Aktualne limity bezpłatnego korzystania
Bezpłatne korzystanie jest przypisane do poszczególnych pozycji asortymentowych (SKU), a nie do jednej wspólnej kwoty kredytowej w dolarach.
Na przykład:
- Żądania autouzupełniania: 10 000 bezpłatnych zdarzeń miesięcznie
- Podstawowe informacje o miejscu: 10 000
- Szczegóły miejsca Pro: 5 000
- Text Search Pro: 5 000
- Nearby Search Pro: 5 000
- Szczegóły dotyczące lokalizacji: 1 000
- Wyszukiwanie tekstowe w wersji Enterprise: 1 000
- Wyniki wyszukiwania w pobliżu: 1 000
Niektóre usługi dostępne wyłącznie po podaniu identyfikatora oferują nieograniczony bezpłatny dostęp.
W związku z tym szacunki kosztów w większym stopniu zależą od konkretnego żądania niż w przypadku starszego systemu rozliczeniowego. Dwie aplikacje wykonujące taką samą liczbę wywołań interfejsu Places API mogą generować różne rachunki, jeśli żądają różnych pól lub korzystają z różnych metod.
Jak wymagane pola wpływają na rozliczenia
Maska pól ma wpływ nie tylko na wielkość odpowiedzi.
W przypadku funkcji „Szczegóły miejsca”, „Wyszukiwanie tekstowe” i „Wyszukiwanie w pobliżu” firma Google rozlicza żądanie zgodnie z najwyższym poziomem SKU odpowiadającym żądanym polom. Jeśli maska pól obejmuje pola zarówno z pakietu Essentials, jak i Pro, żądanie jest rozliczane na poziomie Pro.
Na przykład aplikacja, która potrzebuje jedynie identyfikatora miejsca (Place ID) i adresu, może nie wymagać tych samych pól, co aplikacja pobierająca oceny, godziny otwarcia, recenzje i dodatkowe atrybuty miejsca.
W związku z tym wybór pola stanowi część kalkulacji kosztów.
Należy unikać domyślnego pobierania wszystkich dostępnych pól. Należy zacząć od pól wymaganych przez daną funkcję, a pozostałe dodawać tylko wtedy, gdy służą one jasno określonemu celowi.
W jaki sposób sesje autouzupełniania wpływają na rozliczenia
Usługa autouzupełniania może być rozliczana za każde żądanie lub w ramach sesji.
Bez tokenu sesji każde żądanie funkcji autouzupełniania jest rozliczane osobno w ramach pozycji SKU „Żądania funkcji autouzupełniania”.
Sesja grupuje żądania funkcji autouzupełniania użytkownika wraz z żądaniem, które finalizuje wybór. Typowa sesja rozpoczyna się od jednego lub kilku wywołań funkcji autouzupełniania, a kończy się wyświetleniem szczegółów lokalizacji (nowych) lub weryfikacją adresu. Każde nowe wyszukiwanie użytkownika powinno wykorzystywać nowy token sesji.
W przypadku sesji kończących się żądaniem „Place Details Essentials” firma Google rozlicza obecnie pierwsze 12 żądań funkcji autouzupełniania osobno. Żądania powyżej 12. są rozliczane w ramach „Autocomplete Session Usage”, co nie wiąże się z żadnymi opłatami. Kończące sesję żądanie „Place Details” jest nadal rozliczane w ramach własnego kodu SKU.
Porzucone sesje nie są traktowane w ten sposób. Jeśli użytkownik nigdy nie zakończy sesji, przechodząc do sekcji „Szczegóły miejsca” lub „Weryfikacja adresu”, opłaty za funkcję autouzupełniania powracają do stawek naliczanych za każde żądanie.
Jak oszacować koszty korzystania z interfejsu API Google Places
Rzetelne oszacowanie kosztów należy opierać raczej na rzeczywistym przepływie żądań niż na całkowitej liczbie użytkowników.
Sprawdź:
- Która metoda interfejsu API Places zostanie wywołana.
- Ile razy metoda jest wywoływana podczas jednej czynności użytkownika.
- Które pola są uwzględnione w masce pól.
- Który numer katalogowy (SKU) wywołują te pola.
- Ile wydarzeń podlegających rozliczeniu przewiduje się w każdym miesiącu?.
- Jaka część tego zużycia mieści się w ramach bezpłatnego miesięcznego limitu dla danego SKU?.
- Czy żądania autouzupełniania są grupowane w prawidłowo zakończone sesje.
Na przykład aplikacja wysyłająca co miesiąc 20 000 żądań typu „Place Details Essentials” najpierw wykorzystałaby miesięczny limit 10 000 bezpłatnych zdarzeń. Pozostałe 10 000 zdarzeń podlegałoby płatnemu poziomowi cenowemu.
Przy obecnej stawce pierwszego poziomu wynoszącej $5 na 1 000 zdarzeń te 10 000 płatnych żądań kosztowałyby około $50 przed opodatkowaniem i bez uwzględnienia kosztów korzystania z innych usług platformy Maps Platform.
Obliczenia ulegają zmianie, jeśli maska pola powoduje przypisanie wersji Pro lub Enterprise, dlatego przewidywane pola powinny być uwzględnione w kosztorysie od samego początku.
Kiedy interfejs API Google Places jest, a kiedy nie jest odpowiednim narzędziem
Interfejs API Google Places sprawdza się dobrze, gdy informacje o miejscach stanowią część funkcji aplikacji. Pole wyszukiwania, lokalizator sklepów, aplikacja turystyczna, interfejs dostawczy lub funkcja wyszukiwania pobliskich firm mogą pobierać informacje o miejscach wtedy, gdy użytkownik ich potrzebuje.
Wymagania zmieniają się, gdy głównym celem jest stworzenie zbioru danych biznesowych. Gromadzenie rekordów z wielu kategorii, miast lub regionów to proces odmienny od wyszukiwania miejsc w ramach aplikacji.
Aby zapoznać się z bardziej szczegółowym porównaniem oficjalnego dostępu do API i pozyskiwania danych na dużą skalę, zobacz API Google Maps a zbieranie danych z sieci.
Kiedy interfejs API Google Places działa prawidłowo
Firma Google opracowała interfejs API Places (nowy) z myślą o funkcjach aplikacji wykorzystujących dane lokalizacyjne.
Rozwiązanie to doskonale sprawdza się, gdy aplikacja musi:
- wyszukiwanie miejsc na podstawie danych wprowadzonych przez użytkownika
- znajdź pobliskie firmy lub atrakcje
- proponować miejsca w trakcie wpisywania
- pobierz informacje o znanym miejscu
- wyświetl zdjęcia miejsc
- korzystaj z identyfikatorów miejsc w obsługiwanych usługach platformy Google Maps
Na przykład aplikacja do rezerwacji hoteli mogłaby wyświetlać restauracje w pobliżu wybranego obiektu. Aplikacja do zamawiania dostaw mogłaby wykorzystywać funkcję autouzupełniania, aby ułatwić klientowi wpisanie miejsca docelowego. Wyszukiwarka sklepów mogłaby wyświetlać informacje o konkretnym oddziale po jego wybraniu przez użytkownika.
Żądania te zazwyczaj pojawiają się w ramach interakcji wewnątrz aplikacji. Programista decyduje, która metoda zostanie wywołana, które pola zostaną zwrócone oraz w jaki sposób wyniki zostaną wyświetlone użytkownikowi.
W dokumentacji Google opisano interfejs API Places (nowy) w kontekście takich funkcji aplikacji, jak wyszukiwanie miejsc, sprawdzanie informacji o nich, autouzupełnianie oraz funkcje wykorzystujące lokalizację.
Kiedy potrzebujesz danych biznesowych w dużych ilościach
Niektóre projekty wymagają raczej zbioru danych niż funkcji wyszukiwania lokalizacji.
Zamiast pytać:
Jakie restauracje znajdują się w pobliżu tego użytkownika?
Zespół badawczy może potrzebować:
Które restauracje działają w tych 50 miastach?
Ten sam schemat powtarza się w różnych zespołach:
- Programiści może zaistnieć potrzeba wyszukania lokalizacji lub szczegółowych informacji w aplikacji.
- Specjaliści ds. marketingu może potrzebować danych dotyczących firm według kategorii i lokalizacji do celów badań rynkowych.
- Zespoły sprzedaży może potrzebować dokumentacji biznesowej spełniającej określone kryteria geograficzne lub dotyczące firmy.
- Specjaliści ds. danych może potrzebować uporządkowanych danych do celów analizy, tworzenia pulpitów nawigacyjnych lub obsługi systemów wewnętrznych.
Gdy praca polega na gromadzeniu setek lub tysięcy dokumentów biznesowych, proces ten przestaje polegać na wyszukiwaniu poszczególnych pozycji, a staje się gromadzeniem danych.
W zakresie badań rynkowych zobacz Jakie dane firmowe z Google Maps należy zebrać na potrzeby analizy rynku zanim zdecydujesz, które pola powinny znaleźć się w Twoim zbiorze danych.
Rozwiązanie typu „no-code” do gromadzenia danych biznesowych
Zespoły, które nie muszą tworzyć funkcji wyszukiwania lokalizacji, mogą skorzystać z Outscraper Skrobak Map Google w celu gromadzenia dokumentacji biznesowej bez konieczności konfigurowania żądań w Google Cloud ani pisania kodu API.
Użytkownicy mogą wyszukiwać dane według kategorii i lokalizacji, uruchamiać zbieranie danych za pośrednictwem interfejsu internetowego oraz eksportować wyniki do celów badawczych, poszukiwawczych lub analitycznych.
Dla programistów i zespołów zajmujących się danymi, które potrzebują dostępu programowego, Outscraper Interfejs API miejsc w Mapach Google jest usługą odrębną od usługi Google Interfejs API „Miejsca” (nowość). Umożliwia zbiorcze gromadzenie danych biznesowych. Zobacz Dokumentacja API Outscraper aby uzyskać szczegółowe informacje na temat wniosku.
Aplikacja, która wymaga wyszukiwania miejsc w pobliżu, ma inne wymagania dotyczące danych niż zespół tworzący zbiór danych biznesowych przeznaczony do wielokrotnego wykorzystania.
Użyj Outscraper Interfejs API miejsc w Mapach Google gdy potrzebujesz dokumentacji biznesowej z różnych kategorii lub lokalizacji do celów badawczych, sprzedażowych, analitycznych lub w ramach innego procesu przetwarzania danych.
Gdy potrzebujesz dodatkowych danych dotyczących firmy lub danych kontaktowych
Interfejs API Google Places może zwracać adresy, numery telefonów, strony internetowe, oceny, recenzje, godziny otwarcia, status firmy oraz inne dane dotyczące miejsc.
W przypadku pozyskiwania potencjalnych klientów lub badań rynkowych mogą jednak nadal występować luki. Zespoły mogą również potrzebować adresów e-mail, danych kontaktowych, profili w mediach społecznościowych lub innych informacji o firmie, zanim dany wpis będzie gotowy do wykorzystania.
Jeśli chcesz dodać dane kontaktowe i informacje o firmie po zebraniu danych dotyczących lokalizacji, zapoznaj się z przewodnikiem dotyczącym Wzbogacanie danych dotyczących miejsc w Google Maps.
Typowy przebieg pracy wygląda następująco:
- Wyszukaj firmy według kategorii i lokalizacji.
- Zachowaj pola niezbędne do kierowania reklam.
- Dodaj dane kontaktowe lub dane firmy.
- Wyeksportuj dane do systemu sprzedaży, badań lub innego systemu.
wysięgnik wspiera gromadzenie danych biznesowych zarówno za pomocą rozwiązań typu „no-code”, jak i przepływów pracy opartych na API, oferując dodatkowe opcje wzbogacania danych dotyczących wiadomości e-mail, kontaktów i profili w mediach społecznościowych.
Interfejs API Google Places umożliwia wyszukiwanie miejsc i wyświetlanie szczegółowych informacji o nich w aplikacjach. Procesy przetwarzania danych biznesowych, które wymagają danych kontaktowych, wzbogacania danych lub eksportu, zazwyczaj wymagają dodatkowych narzędzi.
Ograniczenia, limity i ryzyko związane z rozliczeniami w ramach interfejsu API Google Places
Konfiguracja interfejsu API Places może działać poprawnie w środowisku testowym, a mimo to po wzroście wykorzystania mogą pojawić się problemy związane z kosztami, limitami lub dostępem.
Firma Google stosuje limity w podziale na metody API i projekty, a nie w ramach jednego wspólnego limitu dziennego. Dane dotyczące wykorzystania, limity, błędy i rozliczenia można sprawdzić w Google Cloud Console.
Żądaj tylko tych pól, których potrzebujesz
Maska pól ma wpływ zarówno na odpowiedź, jak i na pozycję rozliczeniową.
Jeśli żądanie zawiera pola z pakietu Pro, firma Google może naliczyć opłatę za to żądanie według stawki za pakiet Pro, nawet jeśli zawiera ono również pola o niższej cenie. Należy ograniczyć maskę pól wyłącznie do danych, z których aplikacja faktycznie korzysta.
Wybierz odpowiednią metodę wyszukiwania
Wyszukiwanie tekstowe opiera się na wpisanym zapytaniu. Wyszukiwanie w pobliżu opiera się na określonym obszarze geograficznym i kryteriach dotyczących typu miejsca.
Na przykład:
kawiarnie w Bostoniepasuje do wyszukiwania tekstowego.- restauracje znajdujące się w określonym promieniu spełniają kryteria wyszukiwania „W pobliżu”.
Wybór odpowiedniej metody pozwala ograniczyć zbędne żądania i dodatkowe filtrowanie.
Prawidłowe zarządzanie sesjami autouzupełniania
Funkcja autouzupełniania może generować kilka żądań w trakcie wpisywania tekstu przez użytkownika.
W każdej sesji wyszukiwania należy używać nowego tokenu sesji, a sesję należy zakończyć zgodnym żądaniem typu „Szczegóły miejsca” lub „Weryfikacja adresu”. Przerwane lub nieprawidłowo skonfigurowane sesje mogą zostać rozliczone jako oddzielne żądania.
Należy rozdzielać stare i nowe zgłoszenia
Interfejs API Places (wersja starsza) i interfejs API Places (wersja nowa) wykorzystują różne formaty żądań, nazwy pól i struktury odpowiedzi.
Nie należy mieszać tokenów sesji funkcji autouzupełniania w żądaniach typu „Legacy” i „New”. Przed przeniesieniem ruchu produkcyjnego do Places API (New) należy sprawdzić starsze integracje.
Ogranicz dostęp do swoich kluczy API
Firma Google zaleca ograniczenie kluczy API w podziale na aplikacje i interfejsy API.
W przypadku żądań po stronie serwera ograniczenia dotyczące adresów IP mogą ograniczać zakres stosowania klucza. Ograniczenia API mogą ograniczać stosowanie tego samego klucza do interfejsu Places API (nowy) i innych wymaganych usług.
Nieprawidłowo skonfigurowany klucz może również spowodować REQUEST_DENIED błędy, dlatego przed wdrożeniem do środowiska produkcyjnego należy przetestować ograniczenia.
Ustawianie limitów i powiadomień dotyczących rozliczeń
Konsola Google Cloud umożliwia monitorowanie ruchu, błędów, limitów i wydatków.
Ustaw limity kontyngentów i powiadomienia dotyczące rozliczeń, zanim liczba żądań wzrośnie. Powiadomienia dotyczące rozliczeń ostrzegają o osiągnięciu wybranych progów wydatków, ale nie powodują automatycznego wstrzymania korzystania z API.
Ostateczna lista kontrolna: przed rozpoczęciem korzystania z interfejsu API Google Places
- Wybierz metodę interfejsu API Places, która odpowiada danemu zadaniu.
- Skorzystaj z interfejsu API Places (nowość) i żądaj tylko tych pól, których potrzebujesz.
- Sprawdź numer SKU, limit bezpłatnego wykorzystania oraz przewidywany miesięczny koszt.
- Ogranicz uprawnienia klucza API oraz ustaw limity lub powiadomienia dotyczące rozliczeń.
- Zdecyduj, czy potrzebujesz funkcji wyszukiwania miejsc za pomocą aplikacji, czy też zbiorczego gromadzenia danych o firmach.
Posługiwać się Outscraper Google Maps Places API w celu gromadzenia dokumentacji biznesowej z różnych lokalizacji lub kategorii.
FAQ
Najczęściej zadawane pytania i odpowiedzi
Interfejs API Google Places nie jest w pełni bezpłatny. Firma Google stosuje model rozliczeń oparty na faktycznym zużyciu, z miesięcznymi limitami bezpłatnego wykorzystania dla poszczególnych pozycji (SKU). Na przykład w przypadku żądań autouzupełniania i usługi „Place Details Essentials” obecnie przewidziano 10 000 bezpłatnych zdarzeń miesięcznie, podczas gdy inne pozycje mają niższe limity.
Interfejs API Places służy do wyszukiwania miejsc oraz pobierania informacji o firmach, zabytkach i innych lokalizacjach. Interfejs API Geocoding służy głównie do przekształcania adresów na współrzędne lub współrzędnych z powrotem na adresy. Oba interfejsy mogą korzystać z identyfikatorów miejsc (Place ID), ale służą do realizacji różnych zadań związanych z danymi lokalizacyjnymi.
Interfejs API Places udostępnia dane dotyczące miejsc za pośrednictwem żądań HTTP. Interfejs API Maps JavaScript służy do dodawania interaktywnych map i funkcji mapowych opartych na przeglądarce do stron internetowych. Zawarta w nim biblioteka Places umożliwia również wyszukiwanie miejsc i autouzupełnianie w ramach aplikacji internetowej.
Tak. Projekt produkcyjny korzystający z Places API wymaga projektu Google Cloud powiązanego z kontem rozliczeniowym. Projekt ten musi również mieć włączoną wymaganą usługę Places API oraz posiadać ważne dane uwierzytelniające.
Identyfikator miejsca (Place ID) to tekstowy identyfikator lokalizacji w bazie danych Google Places oraz w Google Maps. Można go wykorzystywać w wielu usługach platformy Google Maps Platform, w tym w Places API, Geocoding API, Maps JavaScript API oraz Routes API. Firma Google zwraca uwagę, że identyfikatory miejsc mogą ulegać zmianom w miarę upływu czasu, i zaleca odświeżanie zapisanych identyfikatorów, które mają ponad 12 miesięcy.
Interfejs API Places (nowy) to aktualna wersja przeznaczona do nowych projektów. Niektóre metody starszej wersji odpowiadają bezpośrednio nowszym metodom, podczas gdy inne uległy zmianie. Na przykład metoda „Wyszukiwanie tekstowe (nowa)” zastępuje metodę „Znajdź miejsce (starsza)”. Istniejące projekty oparte na starszej wersji są nadal obsługiwane, ale w nowych projektach w chmurze nie można włączać usług starszej wersji.
W aktualnej liście pól danych lokalizacji (Place) w interfejsie API Google Places (New) nie pojawia się żadne pole dotyczące firmowego adresu e-mail. Interfejs API może zwracać takie pola, jak numery telefonów i adresy URL stron internetowych, jednak firmowe adresy e-mail nie figurują na liście obsługiwanych pól lokalizacji.
