Migracja z interfejsu Geocoding API w wersji 3 do wersji 4

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Interfejs Geocoding API w wersji 4 wprowadza kilka nowych metod, które zastępują funkcje interfejsu API w wersji 3. Z tego przewodnika dowiesz się, jak przenieść aplikację, aby korzystać z nowych metod w wersji 4.

Możesz używać dotychczasowych kluczy interfejsu API z nowymi metodami w wersji 4. Jeśli jednak poprosisz o zwiększenie limitu w przypadku interfejsu API w wersji 3, musisz poprosić o zwiększenie limitu w przypadku nowych interfejsów API w wersji 4.

Migracja z geokodowania w wersji 3

Jeśli do geokodowania adresów używasz geokodowania, przejdź na metodę v4 Geocode an address, która akceptuje żądanie GET.

W interfejsie API w wersji 4 zmieniliśmy nazwy, strukturę i obsługę kilku parametrów. Zdecydowanie zalecamy używanie maski pola do określania pól, które mają zostać zwrócone w odpowiedzi.

Zmiany parametru żądania

Parametr v3 Parametr v4 Uwagi
address, components address Nieustrukturyzowany adres (wersja 3 address) jest teraz przekazywany w ścieżce adresu URL. Filtry komponentów (wersja 3 components) są teraz przekazywane jako parametry zapytania address.*.
bounds locationBias.rectangle Zmieniono nazwę i strukturę na obiekt.
language languageCode Nazwa została zmieniona.
region regionCode Nazwa została zmieniona.
extra_computations Usunięto

Zmiany w polu odpowiedzi

Pole w wersji 3 Pole v4 Uwagi
status, error_message Usunięto Wersja 4 używa kodów stanu HTTP i treści błędów.
results.address_components.long_name/results.address_components.short_name results.addressComponents.longText/results.addressComponents.shortText Nazwa została zmieniona.
results.geometry.location_type results.granularity Nazwa została zmieniona.
results.geometry.location results.location Nazwy pól: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Nazwy pól: northeast/southwest -> high/low.
results.postcode_localities results.postalCodeLocalities Nazwa została zmieniona. Teraz zwracane w przypadku co najmniej 1 lokalizacji (wersja 3 wymaga wartości >1).
results.partial_match Usunięto
Nowość results.addressComponents.languageCode Język konkretnego komponentu adresu.
Nowość results.bounds Jawne granice za pomocą tagów high/low.
Nowość results.place Nazwa zasobu miejsca.
Nowość results.postalAddress Ustrukturyzowany obiekt PostalAddress.

Migracja z odwrotnego geokodowania w wersji 3

Jeśli używasz geokodowania odwrotnego do przekształcania współrzędnych w adresy, musisz przejść na metodę v4 Geokodowanie odwrotne lokalizacji, która akceptuje żądanie GET.

W interfejsie API w wersji 4 zmieniliśmy nazwy, strukturę i obsługę kilku parametrów. Zdecydowanie zalecamy używanie maski pola do określania pól, które mają zostać zwrócone w odpowiedzi.

Zmiany parametru żądania

Parametr v3 Parametr v4 Uwagi
language languageCode Nazwa została zmieniona.
region regionCode Nazwa została zmieniona.
result_type types Zmieniono nazwę; używa powtarzanych parametrów zapytania.
location_type granularity Zmieniono nazwę; używa powtarzanych parametrów zapytania.
extra_computations Usunięto

Zmiany w polu odpowiedzi

Pole w wersji 3 Pole v4 Uwagi
status, error_message Usunięto Wersja 4 używa kodów stanu HTTP i treści błędów.
results.address_components.long_name/results.address_components.short_name results.addressComponents.longText/results.addressComponents.shortText Nazwa została zmieniona.
results.geometry.location_type results.granularity Nazwa została zmieniona.
results.geometry.location results.location Nazwy pól: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Nazwy pól: northeast/southwest -> high/low.
Nowość results.addressComponents.languageCode Język konkretnego komponentu adresu.
Nowość results.bounds Jawne granice za pomocą tagów high/low.
Nowość results.place Nazwa zasobu miejsca.
Nowość results.postalAddress Ustrukturyzowany obiekt PostalAddress.

Migracja z geokodowania miejsc w wersji 3

Jeśli używasz place_id do pobierania adresu dla konkretnego identyfikatora miejsca za pomocą interfejsu Geocoding API w wersji 3, musisz przejść na metodę Place Geocoding w wersji 4, która akceptuje żądanie GET.

W interfejsie API w wersji 4 zmieniliśmy nazwy, strukturę i obsługę kilku parametrów. Zdecydowanie zalecamy używanie maski pola do określania pól, które mają zostać zwrócone w odpowiedzi.

Zmiany parametru żądania

Parametr v3 Parametr v4 Uwagi
place_id place pole w protokole żądania Identyfikator miejsca jest teraz podawany jako parametr ścieżki places/{place}, np. https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Odpowiada to polu miejsca w żądaniu bazowym.
language languageCode Nazwa została zmieniona.
region regionCode Nazwa została zmieniona.

Zmiany w polu odpowiedzi

Pole w wersji 3 Pole v4 Uwagi
status, error_message Usunięto Wersja 4 używa kodów stanu HTTP i treści błędów.
results (root) Wersja 4 zwraca pojedynczy obiekt wyniku, a nie tablicę results.
results.address_components.long_name/results.address_components.short_name addressComponents.longText/addressComponents.shortText Nazwa została zmieniona.
results.geometry.location_type granularity Nazwa została zmieniona.
results.geometry.location location Nazwy pól: lat/lng -> latitude/longitude.
results.geometry.viewport viewport Nazwy pól: northeast/southwest -> high/low.
results.postcode_localities postalCodeLocalities Nazwa została zmieniona. Teraz zwracane w przypadku co najmniej 1 lokalizacji (wersja 3 wymaga wartości >1).
Nowość addressComponents.languageCode Język konkretnego komponentu adresu.
Nowość bounds Jawne granice za pomocą tagów high/low.
Nowość place Nazwa zasobu miejsca.
Nowość postalAddress Ustrukturyzowany obiekt PostalAddress.

Migracja z geokodowania danych hiperlokalnych do miejsc docelowych

Te funkcje w Geocoding API v3 są zastępowane przez metodę SearchDestinations w Geocoding API v4:

  • Wejścia
  • Punkty nawigacyjne
  • Tworzenie konspektów
  • Tereny posiadłości

Jeśli do korzystania z powyższych funkcji używasz interfejsu Geocoding API w wersji 3, zapoznaj się z tym dokumentem, aby dowiedzieć się, jak zamiast tego używać metody SearchDestinations. Z tego dokumentu dowiesz się, gdzie w SearchDestinations odpowiedzi znaleźć te funkcje, oraz poznasz różnice w sposobie ich reprezentowania w odpowiedziach interfejsu API między interfejsem Geocoding API w wersji 3 a metodą SearchDestinations interfejsu Geocoding API w wersji 4.

Wejścia

Aby uzyskać wejścia powiązane z destination, użyj pola destination.entrances.

Zwróć uwagę, że format entrance nieco różni się od formatu wejścia w interfejsie Geocoding API w wersji 3. Każde wejście w destination.entrances ma te pola:

  • displayName – to nowe pole opcjonalne, które będzie zawierać czytelną dla użytkownika nazwę wejścia, np. „Brama B”.
  • location – to lokalizacja typu LatLng, która różni się od formatu używanego w Geocoding API w wersji 3.
  • tags – to pole jest takie samo jak pole tags w przypadku wejść z interfejsu Geocoding API w wersji 3.
  • place – analogiczne do pola buildingPlaceId w przypadku wejść z interfejsu Geocoding API w wersji 3. Identyfikator miejsca w tym polu może jednak dotyczyć miejsca dowolnego typu, nie tylko budynku.

Aby uzyskać punkty nawigacyjne powiązane z destination, użyj pola destination.navigationPoints.

Pamiętaj, że format a navigationPoint nieco różni się od formatu punktu nawigacyjnego w interfejsie Geocoding API w wersji 3. Każdy punkt nawigacyjny w destination.navigationPoints ma te pola:

  • displayName – to nowe pole opcjonalne, które będzie zawierać czytelną dla użytkownika nazwę punktu nawigacyjnego, np. „5th Ave”.
  • location – to lokalizacja typu LatLng, która różni się od formatu używanego w Geocoding API w wersji 3.
  • travelModes – jest to podobne do pola restrictedTravelModes punktów nawigacyjnych z interfejsu Geocoding API w wersji 3. Możliwe wartości wyliczenia są takie same, jedyna różnica polega na tym, że to pole reprezentuje teraz dopuszczalne środki transportu dla punktu nawigacyjnego, a nie ograniczone środki transportu.
  • usage – to nowe pole zawiera przypadki użycia obsługiwane przez punkt nawigacyjny. Pamiętaj, że większość punktów nawigacyjnych ma UNKNOWN, ale nie oznacza to, że ich użycie jest w jakikolwiek sposób ograniczone.

Tworzenie konspektów

Aby uzyskać kontury budynków powiązane z destination, użyj pola displayPolygon obiektów placeView w destination, które reprezentują budynki. W przypadku każdego placeView możesz sprawdzić, czy jest to budynek, korzystając z pola placeView.structureType. Jeśli typ struktury to BUILDING, kontur możesz uzyskać z pola placeView.displayPolygon. placeView będzie też zawierać dodatkowe pola dotyczące budynku, których nie było w interfejsie Geocoding API w wersji 3.

destination może mieć obiekt placeView, który reprezentuje budynek w tych polach:

  • destination.primary – to główne miejsce docelowe.
  • destination.containingPlaces – to pole powtarzane, które może zawierać większe miejsca, które „zawierają” miejsce podstawowe. Jeśli na przykład głównym miejscem jest subpremise, containingPlaces zwykle zawiera placeView reprezentujące budynek.
  • destination.subDestinations – to pole powtarzane, które może zawierać podrzędne miejsca docelowe głównego miejsca. Na przykład poszczególne mieszkania w budynku. To pole zwykle nie zawiera placeView reprezentującego budynek.

Pamiętaj, że format placeView.displayPolygon jest zgodny z formatem konturu budynku w interfejsie Geocoding API w wersji 3, czyli formatem GeoJSON, który korzysta z formatu RFC 7946.

Tereny posiadłości

Podobnie jak w przypadku konturów budynków, aby uzyskać tereny powiązane z destination, użyj pola displayPolygon obiektów placeView w destination, które reprezentują tereny. W przypadku każdego placeView możesz sprawdzić, czy jest to podstawa, korzystając z pola placeView.structureType. Jeśli typ struktury to GROUNDS, możesz pobrać konspekt z pola placeView.displayPolygon. placeView będzie też zawierać dodatkowe pola dotyczące powodów, których nie było w interfejsie Geocoding API w wersji 3.

destination może mieć obiekt placeView, który reprezentuje podstawy w tych polach:

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

Pamiętaj, że format placeView.displayPolygon jest zgodny z formatem konturu terenu w interfejsie Geocoding API w wersji 3, czyli formatem GeoJSON, który korzysta z formatu RFC 7946.

Użyj maski pola, aby poprosić o te funkcje

Metoda SearchDestinations wymaga maski pola, co wyjaśniono w artykule Wybieranie pól do zwrócenia. Maskę pola można ustawić na *, aby zwrócić wszystkie pola, lub ustawić ją na konkretne pola, które chcesz otrzymać. Na przykład to żądanie do interfejsu API ustawia maskę pola, aby otrzymać wszystkie pola wymagane do uzyskania wejść, punktów nawigacyjnych, obrysów budynków i terenów miejsca docelowego:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4beta/geocode/destinations

Bezpieczeństwo

Geocoding API w wersji 4 to interfejs API działający między serwerami. Użytkownicy JavaScript nie mogą bezpośrednio przejść z wersji 3 na wersję 4. Wywoływanie metod v4 bezpośrednio z JavaScriptu po stronie klienta (np. w przeglądarce) przy użyciu klucza interfejsu API naraża ten klucz na wysokie ryzyko kradzieży i nadużycia.

Ograniczenia dotyczące odsyłającego HTTP, choć przydatne, nie zapewniają wystarczającego zabezpieczenia punktów końcowych usług sieciowych, ponieważ mogą być łatwo omijane przez osoby przeprowadzające atak, które fałszują nagłówek Referer w swoich żądaniach.

Zalecany sposób korzystania z interfejsu Geocoding API w wersji 4 to używanie go na własnym serwerze backendu. Aplikacja kliencka powinna wysyłać żądania do tego serwera pośredniczącego, który następnie bezpiecznie wywołuje interfejs API Google za pomocą chronionego klucza interfejsu API (np. klucza przechowywanego w zmiennej środowiskowej lub w usłudze Secret Manager). Dzięki temu klucz interfejsu API nigdy nie będzie widoczny w kodzie interfejsu.

Alternatywne rozwiązania dla potrzeb po stronie klienta

Jeśli masz potrzeby po stronie klienta, które wymagają geokodowania, rozważ użycie jednego z tych rozwiązań po stronie klienta: