Geocoding API to usługa internetowa, która konwertuje adresy na współrzędne i identyfikatory miejsc oraz współrzędne lub identyfikatory miejsc na adresy. Metoda v4 SearchDestinations zwraca też szczegóły miejsca docelowego, takie jak wejścia do budynków, punkty nawigacyjne, kontury budynków i terenów oraz pobliskie punkty orientacyjne.
Geocoding API: najważniejsze informacje
- Usługa: Geocoding API
- Kategoria: Miejsca
- Platforma: usługa internetowa (REST)
- Działa na: serwerze (kod backendu)
- Etap uruchomienia: GA
- Cykl życia: aktywny
- Omówienie: omówienie Geocoding API
Geocoding API: kiedy używać
Używaj interfejsu Geocoding API, gdy:
- Musisz przekonwertować adres ulicy na współrzędne szerokości i długości geograficznej oraz identyfikator miejsca na serwerze backendu.
- W przypadku współrzędnych GPS lub znanego identyfikatora miejsca potrzebujesz adresu wyświetlanego lub regionu (miasta, kodu pocztowego).
- Aby kierować kierowców lub kurierów do miejsca docelowego, potrzebujesz wejść do budynków, punktów nawigacyjnych z możliwością wyznaczania trasy lub konturów budynków/terenów.
- Musisz podzielić miejsce docelowe w dużym kompleksie (lotnisko, centrum handlowe, kampus) na mniejsze miejsca docelowe lub pobliskie punkty orientacyjne.
Nie używaj Geocoding API, gdy:
- Potrzebujesz geokodowania z poziomu kodu JavaScript przeglądarki po stronie klienta. Wywołanie wersji 4 z ujawnionym kluczem interfejsu API stanowi zagrożenie dla bezpieczeństwa. Zamiast tego użyj Maps JavaScript API.
- Musisz obliczyć trasę lub szacowany czas dotarcia na miejsce do miejsca docelowego z kodem geograficznym. Zamiast tego użyj interfejsu Routes API.
- Potrzebujesz szczegółowych wskazówek dojazdu do punktu nawigacyjnego w aplikacji na Androida. Zamiast tego użyj pakietu Navigation SDK na Androida.
- Potrzebujesz szczegółowych wskazówek dojazdu do tokena punktu nawigacyjnego w aplikacji na iOS. Użyj pakietu Navigation SDK na iOS.
Geocoding API: konfiguracja
- Usługa do włączenia:
geocoding-backend.googleapis.com - Uwierzytelnianie: klucz interfejsu API, OAuth 2.0, konto usługi.
- Pierwsze kroki: skonfiguruj Geocoding API
- Dokumentacja API: dokumentacja Geocoding API
- Ceny: korzystanie z Geocoding API i rozliczenia
- Zasady: zasady dotyczące Geocoding API
- Informacje o wersjach: informacje o wersjach interfejsu Geocoding API
Geocoding API: produkty powiązane
- Często używane z: Routes API, Navigation SDK for Android, Navigation SDK for iOS
Geocoding API: typowe błędy
- Problem: żądania
SearchDestinationsbez maski pola kończą się błędem. W odróżnieniu odGeocodeAddress,GeocodeLocationiGeocodePlacemaska pola jest wymagana. Rozwiązanie: ustaw nagłówekX-Goog-FieldMasklub parametr$fieldsw każdym żądaniuSearchDestinations. Zobacz /maps/documentation/geocoding/choose-fields. - Problem: w v4
GeocodeAddressnie ma filtra komponentów twardych (v3components=country:US). Parametry uporządkowaneaddress.*są łączone w jeden adres i nie filtrują wyników. W v4 nie ma też domyślnej wartościregionCode(w v3 domyślną wartością jestus). Rozwiązanie: filtrujresultspo stronie klienta: dopasuj wielkie literyregionCodedopostalAddress.regionCode; dopasuj wielkie litery 2-literowych obszarów administracyjnych dopostalAddress.administrativeAreaiadministrative_area_level_naddressComponents(shortText); normalizuj zarówno dane wejściowe, jak ipostalAddress.postalCode(usuń spacje i łączniki oraz zastosuj reguły regionu). Więcej informacji znajdziesz na stronie /maps/documentation/geocoding/geocoding-v4-migrate. - Problem: wywoływanie interfejsu Geocoding API w wersji 4 bezpośrednio z poziomu kodu JavaScript w przeglądarce ujawnia klucz interfejsu API. Ograniczenia dotyczące strony odsyłającej HTTP można obejść, fałszując nagłówek
Referer. Rozwiązanie: wywołaj wersję 4 z własnego backendu za pomocą chronionego klucza lub użyj usługi geokodowania Maps JavaScript API (backend w wersji 3) na potrzeby po stronie klienta. Więcej informacji znajdziesz na stronie /maps/documentation/geocoding/geocoding-v4-migrate. - Problem: metoda
SearchDestinationsmoże zwracać wyniki, które nie mają dokładnego adresu podstawowego, w przeciwieństwie do wersji 3 i innych metod wersji 4. Rozwiązanie: ustaw parametrplaceFilter.addressabilitynaPRIMARY, gdy potrzebujesz tylko wyników z dokładnymi adresami podstawowymi. Więcej informacji znajdziesz na stronie /maps/documentation/geocoding/geocoding-v4-migrate. - Problem: kod napisany dla Geocoding API w wersji 3 nie działa w przypadku odpowiedzi REST w wersji 4. Wersja 4 używa nazw pól w formacie lowerCamelCase (
addressComponents, a nieaddress_components), usuwastatusierror_messageoraz zwraca pojedynczy obiekt główny zGeocodePlacezamiast tablicyresults. Rozwiązanie: sprawdź kody stanu HTTP i treści błędów w wywołaniach REST w wersji 4, odczytaj pola lowerCamelCase (addressComponents,postalAddress) i pamiętaj, że odpowiedzi gRPC nadal używają snake_case. Więcej informacji znajdziesz na stronie /maps/documentation/geocoding/geocoding-v4-migrate.
Geocoding API: starsze i wycofane funkcje
- Dane hiperlokalne Geocoding API w wersji 3 (
extra_computations:BUILDING_AND_ENTRANCES,NAVIGATION_POINTS,GROUNDS; pola odpowiedzibuildings.entrances,navigation_points,buildings.building_outlines,grounds): wycofane od 13 sierpnia 2025 r. Zamiennik: metodaSearchDestinations(POST /v4/geocode/destinations) interfejsu Geocoding API w wersji 4. Zapoznaj się z przewodnikiem po migracji.
Co możesz zrobić za pomocą interfejsu Geocoding API
Zapoznaj się z przewodnikami po poszczególnych zadaniach, do których linki znajdziesz poniżej, lub porównaj usługi w Eksploratorze funkcji.
- Zwracanie współrzędnych szerokości i długości geograficznej adresu (geokodowanie).
- Zwracanie adresu dla zestawu współrzędnych szerokości i długości geograficznej (odwrotne geokodowanie).
- Ogranicz żądanie geokodowania, aby zwracało wyniki w określonym widocznym obszarze. Uwaga: w Geocoding API w wersji 4 parametr locationBias faworyzuje wyniki w określonym obszarze widoku, zamiast ściśle je ograniczać.
- Ogranicz żądanie geokodowania lub odwrotnego geokodowania, aby zwracało wyniki tylko w określonym regionie, kraju lub kodzie pocztowym. Uwaga: w Geocoding API v4 parametr regionCode faworyzuje wyniki z określonego regionu CLDR, a nie ściśle je ogranicza. Informacje o filtrowaniu komponentów według kraju lub kodu pocztowego w starszej wersji v3 znajdziesz na stronie https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Ogranicz żądanie odwrotnego geokodowania, aby zwracało wyniki tylko dla określonych typów adresów. Uwaga: w Geocoding API w wersji 4 parametr types filtruje zwrócone wyniki odwrotnego geokodowania według typu adresu po wyszukiwaniu, a nie ogranicza wyszukiwanie podstawowe.
- Zwracanie informacji o odległości od punktów orientacyjnych lub obszarów dla danego adresu.
- Zwracanie informacji o odległości od punktów orientacyjnych lub obszarów dla zestawu współrzędnych szerokości i długości geograficznej.
- Zwracanie informacji o bliskości punktów orientacyjnych lub obszarów dla identyfikatora miejsca Google.
- Zwraca adres dla identyfikatora miejsca Google.
- Zwracanie współrzędnych szerokości i długości geograficznej obrysu budynku dla adresu.
- Zwracanie współrzędnych szerokości i długości geograficznej obrysu budynku dla zestawu współrzędnych szerokości i długości geograficznej.
- Zwracanie współrzędnych szerokości i długości geograficznej obrysu budynku na podstawie identyfikatora miejsca Google.
- Zwracanie współrzędnych szerokości i długości geograficznej wejścia do budynku dla danego adresu.
- Zwracanie współrzędnych szerokości i długości geograficznej wejścia do budynku dla zestawu współrzędnych szerokości i długości geograficznej.
- Zwracanie współrzędnych szerokości i długości geograficznej wejścia do budynku na podstawie identyfikatora miejsca Google.