Geocoding API – krótkie wprowadzenie

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

Geocoding API: typowe błędy

  • Problem: żądania SearchDestinations bez maski pola kończą się błędem. W odróżnieniu od GeocodeAddress, GeocodeLocation i GeocodePlace maska pola jest wymagana. Rozwiązanie: ustaw nagłówek X-Goog-FieldMask lub parametr $fields w każdym żądaniu SearchDestinations. Zobacz /maps/documentation/geocoding/choose-fields.
  • Problem: w v4 GeocodeAddress nie ma filtra komponentów twardych (v3 components=country:US). Parametry uporządkowane address.* są łączone w jeden adres i nie filtrują wyników. W v4 nie ma też domyślnej wartości regionCode (w v3 domyślną wartością jest us). Rozwiązanie: filtruj results po stronie klienta: dopasuj wielkie litery regionCode do postalAddress.regionCode; dopasuj wielkie litery 2-literowych obszarów administracyjnych do postalAddress.administrativeArea i administrative_area_level_n addressComponents (shortText); normalizuj zarówno dane wejściowe, jak i postalAddress.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 SearchDestinations moż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 parametr placeFilter.addressability na PRIMARY, 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 nie address_components), usuwa status i error_message oraz zwraca pojedynczy obiekt główny z GeocodePlace zamiast tablicy results. 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 odpowiedzi buildings.entrances, navigation_points, buildings.building_outlines, grounds): wycofane od 13 sierpnia 2025 r. Zamiennik: metoda SearchDestinations (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.