Usługa geokodowania

Uwaga: biblioteki po stronie serwera
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Omówienie

Geokodowanie to proces konwertowania adresów (np. „1600 Amphitheatre Parkway, Mountain View, CA”) na współrzędne geograficzne (np.szerokość geograficzna 37,423021 i długość geograficzna -122,083739), których można używać do umieszczania znaczników lub pozycjonowania na mapie.

Odwrotne geokodowanie to proces konwertowania współrzędnych geograficznych na adres zrozumiały dla człowieka (patrz Odwrotne geokodowanie (wyszukiwanie adresu)).

Możesz też użyć geokodera, aby znaleźć adres danego identyfikatora miejsca.

Interfejs Maps JavaScript API udostępnia klasę Geocoder do dynamicznego geokodowania i odwrotnego geokodowania danych wejściowych użytkownika. Jeśli chcesz zamiast tego geokodować znane adresy statyczne, zapoznaj się z usługą internetową do geokodowania.

Rozpocznij

Zanim użyjesz usługi geokodowania w interfejsie Maps JavaScript API, upewnij się, że interfejs Geocoding API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany dla interfejsu Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

  1. Otwórz konsolę Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt skonfigurowany dla interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu odszukaj Geocoding API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejs API nie jest wymieniony, włącz go:
    1. U góry strony kliknij WŁĄCZ INTERFEJS API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
    2. Wyszukaj Geocoding API i wybierz go na liście wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu interfejs Geocoding API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

Aby dowiedzieć się więcej o cenach i zasadach korzystania z usługi geokodowania w JavaScript, zapoznaj się z informacjami o korzystaniu z interfejsu Geocoding API i jego rozliczaniu.

Zasady

Korzystanie z usługi geokodowania musi być zgodne z zasadami interfejsu Geocoding API.

Żądania dotyczące geokodowania

Dostęp do usługi geokodowania jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do zewnętrznego serwera. Z tego powodu musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu przetwarzania żądania. Ta metoda wywołania zwrotnego przetwarza wyniki. Pamiętaj, że geokoder może zwrócić więcej niż 1 wynik.

W kodzie uzyskujesz dostęp do usługi geokodowania interfejsu API Map Google za pomocą obiektu konstruktora google.maps.Geocoder. Metoda Geocoder.geocode() inicjuje żądanie do usługi geokodowania, przekazując jej literał obiektu GeocoderRequest zawierający warunki wejściowe i metodę wywołania, która ma zostać wykonana po otrzymaniu odpowiedzi.

Obiekt GeocoderRequest zawiera te pola:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Wymagane parametry: musisz podać jedno i tylko jedno z tych pól:

  • address – adres, który chcesz geokodować.
         lub
    location – LatLng (lub LatLngLiteral), dla którego chcesz uzyskać najbliższy adres zrozumiały dla człowieka. Geokoder wykonuje odwrotne geokodowanie. Więcej informacji znajdziesz w artykule Geokodowanie odwrotne.
         lub
    placeId – identyfikator miejsca, dla którego chcesz uzyskać najbliższy adres zrozumiały dla człowieka. Dowiedz się więcej o pobieraniu adresu na podstawie identyfikatora miejsca.

Parametry opcjonalne:

  • bounds – obszar geograficzny, na którym mają być wyświetlane wyniki geokodowania.LatLngBounds Parametr bounds będzie miał wpływ na wyniki geokodowania, ale nie będzie ich w pełni ograniczać. Poniżej znajdziesz więcej informacji o uwzględnianiu rozmiaru widoku .
  • componentRestrictions – służy do ograniczania wyników do określonego obszaru. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
  • region – kod regionu określony jako dwuznakowy (niecyfrowy) tag regionu w standardzie Unicode. W większości przypadków te tagi są mapowane bezpośrednio na 2-znakowe wartości domen krajowych najwyższego poziomu (ccTLD). Parametr region będzie miał wpływ na wyniki geokodera, ale nie będzie ich w pełni ograniczać. Poniżej znajdziesz więcej informacji o uwzględnianiu kodu regionu.
  • extraComputations – jedyną dozwoloną wartością tego parametru jest ADDRESS_DESCRIPTORS. Więcej informacji znajdziesz w  opisie adresu.
  • fulfillOnZeroResults – w odpowiedzi spełnij obietnicę dotyczącą stanu ZERO_RESULT. Może to być pożądane, ponieważ nawet przy zerowym geokodowaniu mogą zostać zwrócone dodatkowe pola na poziomie odpowiedzi. Więcej informacji znajdziesz w artykule Realizacja zamówienia w przypadku braku wyników.

Odpowiedzi dotyczące geokodowania

Usługa geokodowania wymaga metody wywołania zwrotnego, która zostanie wykonana po pobraniu wyników geokodowania. To wywołanie zwrotne powinno przekazywać 2 parametry: kod results i kod status (w tej kolejności).

Wyniki geokodowania

Obiekt GeocoderResult reprezentuje pojedynczy wynik geokodowania. Żądanie geokodowania może zwrócić wiele obiektów wyników:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Opis pól:

  • types[] to tablica wskazująca typ adresu zwróconego wyniku. Tablica ta zawiera co najmniej 1 tag, który identyfikuje typ zwracanej w wyniku funkcji. Na przykład kod geograficzny „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co wskazuje, że jest to podmiot polityczny. Poniżej znajdziesz więcej informacji o typach adresów i ich komponentach.
  • formatted_address to ciąg tekstowy zawierający adres tej lokalizacji w zrozumiałej dla człowieka formie.

    Często jest to adres pocztowy. Pamiętaj, że niektóre kraje, takie jak Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

    Sformatowany adres składa się z co najmniej 1 elementu adresu. Na przykład adres „111 8th Avenue, Nowy Jork, NY” składa się z tych elementów: „111” (numer domu), „8th Avenue” (ulica), „Nowy Jork” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu za pomocą kodu. Zamiast tego użyj poszczególnych elementów adresu, które są zawarte w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.

  • address_components[] to tablica zawierająca oddzielne komponenty odpowiednie dla tego adresu.

    Każdy element adresu zawiera zwykle te pola:

    • types[] to tablica wskazująca typ elementu adresu. Zobacz listę obsługiwanych typów.
    • long_name to pełny tekst opisu lub nazwa komponentu adresu zwróconego przez geokoder.
    • short_name to skrócona nazwa tekstowa składnika adresu (jeśli jest dostępna). Na przykład element adresu dla stanu Alaska może mieć long_name „Alaska” i short_name „AK” za pomocą 2-literowego skrótu pocztowego.

    Pamiętaj o tych informacjach dotyczących tablicy address_components[]:

    • Tablica elementów adresu może zawierać więcej elementów niż formatted_address.
    • Tablica niekoniecznie zawiera wszystkie podmioty polityczne, które zawierają adres, poza tymi, które są uwzględnione w formatted_address. Aby pobrać wszystkie jednostki polityczne zawierające określony adres, użyj odwrotnego geokodowania, przekazując szerokość/długość geograficzną adresu jako parametr żądania.
    • Nie ma gwarancji, że format odpowiedzi będzie taki sam w przypadku różnych żądań. W szczególności liczba address_componentszależy od adresu, którego dotyczy żądanie, i może się z czasem zmieniać w przypadku tego samego adresu. Element może zmienić pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować określonego komponentu.

    Poniżej znajdziesz więcej informacji o typach adresów i ich komponentach.

  • partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego zapytania, ale udało mu się dopasować część żądanego adresu. Możesz sprawdzić pierwotną prośbę, aby sprawdzić, czy nie zawiera ona literówek ani niepełnego adresu.

    Częściowe dopasowania występują najczęściej w przypadku adresów ulic, które nie istnieją w miejscowości podanej w żądaniu. W przypadku dopasowania częściowego mogą zostać zwrócone wyniki częściowe, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości. Na przykład wyszukiwanie „Hillpar St, Bristol, UK” zwróci dopasowanie częściowe zarówno do Henry Street, jak i do Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, usługa geokodowania może zaproponować alternatywny adres. Propozycje wygenerowane w ten sposób będą też oznaczone jako częściowe dopasowanie.

  • place_idto unikalny identyfikator miejsca, którego można używać w innych interfejsach API Google. Możesz na przykład używać interfejsu place_id z biblioteką Google Places API, aby uzyskiwać informacje o firmie działającej lokalnie, takie jak numer telefonu, godziny otwarcia czy opinie użytkowników. Zapoznaj się z omówieniem identyfikatora miejsca.
  • postcode_localities[] to tablica zawierająca wszystkie miejscowości zawarte w kodzie pocztowym. Jest obecna tylko wtedy, gdy wynik to kod pocztowy zawierający wiele miejscowości.

  • geometry zawiera te informacje:

    • location zawiera geokodowaną szerokość i długość geograficzną. Pamiętaj, że zwracamy tę lokalizację jako obiekt LatLng, a nie jako sformatowany ciąg znaków.
    • location_type przechowuje dodatkowe dane o określonej lokalizacji. Obsługiwane są następujące wartości:
      • ROOFTOP oznacza, że zwrócony wynik odzwierciedla dokładny kod geograficzny.
      • RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachów są niedostępne dla adresu ulicznego.
      • GEOMETRIC_CENTER oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak linia złożona (np. ulica) lub wielokąt (region).
      • APPROXIMATE oznacza, że zwrócony wynik jest przybliżony.

    • viewport przechowuje zalecany widoczny obszar dla zwróconego wyniku.
    • bounds (opcjonalnie zwracany) przechowuje zmienną LatLngBounds, która może zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanej widoczności. (na przykład San Francisco obejmuje Wyspy Farallon, które technicznie są częścią miasta, ale nie powinny być uwzględniane w widoku).

Adresy są zwracane przez usługę Geocoder, która korzysta z preferowanego ustawienia języka przeglądarki lub języka określonego podczas wczytywania kodu JavaScript interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w  tym artykule).

Typy adresów i typy elementów adresu

Tablica types[] w obiekcie GeocoderResult w odpowiedzi wskazuje typ adresu. Przykłady typów adresów to adres ulicy, kraj lub podmiot polityczny. Tablica types w elementach GeocoderAddressComponent wskazuje typ każdej części adresu. Może to być np. numer ulicy lub kraj.

Adresy mogą być różnego typu. Typy mogą być uznawane za „tagi”. Na przykład wiele miast ma tagi typu political i locality.

W tablicach typów adresów i typów komponentów adresu obsługiwane są i zwracane są te typy:

Typ adresu Opis
street_address Dokładny adres.
route Nazwana trasa (np. „US 101”).
intersection Główne skrzyżowanie, zwykle 2 głównych dróg.
political podmiot polityczny, Zwykle ten typ wskazuje wielokąt administracji cywilnej.
country Narodowy podmiot polityczny, zwykle najwyższy typ zwracany przez geokoder.
administrative_area_level_1 Jednostka administracyjna pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany. Nie wszystkie kraje mają te poziomy administracyjne. W większości przypadków administrative_area_level_1krótkie nazwy będą bardzo zbliżone do podziałów ISO 3166-2 i innych powszechnie rozpowszechnionych list, ale nie jest to gwarantowane, ponieważ nasze wyniki geokodowania opierają się na różnych sygnałach i danych o lokalizacji.
administrative_area_level_2 Podmiot prawny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_3 Podmiot prawny trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_4 Czwarta jednostka cywilna poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_5 Podmiot prawny piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_6 Podmiot prawny szóstego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_7 Podmiot prawny siódmego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
colloquial_area powszechnie używana nazwa alternatywna danego podmiotu;
locality Ustanowiona jednostka polityczna, np. miasto.
sublocality Jednostka administracyjna pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji może być używany jeden z dodatkowych typów: sublocality_level_1 do sublocality_level_5. Każdy poziom podregionu jest jednostką administracyjną. Większe liczby oznaczają mniejszy obszar geograficzny.
neighborhood Nazwana okolica.
premise Nazwane miejsce, zwykle budynek lub zbiór budynków o wspólnej nazwie.
subpremise Adresowalna jednostka poniżej poziomu obiektu, np. mieszkanie, lokal lub apartament.
plus_code zakodowany identyfikator lokalizacji, który jest wyprowadzony ze współrzędnych szerokości i długości geograficznej; Kody Plus Code mogą zastępować adresy ulicy w miejscach, w których ich nie ma (gdzie budynki nie mają numerów, a ulice nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
postal_code Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
natural_feature Wyraźna cecha przyrodnicza.
airport Lotnisko.
park Park o nazwie.
point_of_interest Nazwa interesującego miejsca. Zwykle są to znane obiekty lokalne, które nie pasują do żadnej innej kategorii, np. Pałac Kultury i Nauki czy Wieża Eiffla.

Pusty wykaz typów wskazuje, że nie ma żadnych znanych typów dla danego elementu adresu (np. Lieu-dit we Francji).

Oprócz wymienionych powyżej elementy adresu mogą obejmować te typy.

Uwaga: ta lista nie jest wyczerpująca i może ulec zmianie.

Oprócz wymienionych powyżej elementy adresu mogą obejmować typy wymienione poniżej.

Typ elementu adresu Opis
floor Piętro w adresie budynku.
establishment Zwykle jest to miejsce, które nie zostało jeszcze skategoryzowane.
landmark Miejsce w pobliżu, które służy jako punkt odniesienia, aby ułatwić nawigację.
point_of_interest Nazwa interesującego miejsca.
parking Parking lub parkingowy budynek.
post_box Określona skrzynka pocztowa.
postal_town Grupa obszarów geograficznych, takich jak locality i sublocality, używana do adresów pocztowych w niektórych krajach.
room Pokój w adresie budynku.
street_number Dokładny numer budynku.
bus_station, train_station i transit_station lokalizacja przystanku autobusowego, kolejowego lub przystanku komunikacji miejskiej;

Kody stanu

Kod status może zwracać jedną z tych wartości:

  • "OK" oznacza, że nie wystąpiły żadne błędy; adres został pomyślnie przeanalizowany i zwrócono co najmniej 1 geokod.
  • "ZERO_RESULTS" oznacza, że geokodowanie się udało, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał nieistniejący address.
  • "OVER_QUERY_LIMIT" oznacza, że przekroczysz limit.
  • "REQUEST_DENIED" oznacza, że prośba została odrzucona. Strona internetowa nie może korzystać z geokodera.
  • Wartość "INVALID_REQUEST" oznacza zwykle, że brakuje zapytania (address, components lub latlng).
  • "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Żądanie może się powieść, jeśli spróbujesz ponownie.
  • "ERROR" oznacza, że żądanie przekroczyło limit czasu lub wystąpił problem z kontaktem z serwerami Google. Żądanie może się powieść, jeśli spróbujesz ponownie.

W tym przykładzie geokodujemy adres i umieszczamy znacznik w zwróconych wartościach szerokości i długości geograficznej. Pamiętaj, że uchwyt jest przekazywany jako litera funkcji anonimowej.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Zobacz przykład

Wpływ widocznego obszaru

Możesz zlecić usłudze geokodowania, aby preferowała wyniki w danym widocznym obszarze (określanym jako ograniczony obszar). Aby to zrobić, ustaw parametr bounds w literale obiektu GeocoderRequest, aby zdefiniować granice tego widoku. Pamiętaj, że użycie ukierunkowania preferuje wyniki w określonych granicach. Jeśli poza tymi granicami istnieją bardziej trafne wyniki, mogą one zostać uwzględnione.

Na przykład geokodowanie „Winnetka” zwykle zwraca ten przysiółek Chicago:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Jeśli jednak określisz parametr bounds, który definiuje prostokąt ograniczający dla doliny San Fernando w Los Angeles, geokodowanie zwróci dzielnicę o nazwie „Winnetka” w tej lokalizacji:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Uwzględnianie kodu regionu

Za pomocą parametru region możesz ustawić, aby usługa geokodowania zwracała wyniki z uwzględnieniem konkretnego regionu. Ten parametr przyjmuje kod regionu podany jako dwuznakowy (niecyfrowy) tag regionu w standardzie Unicode. Te tagi są bezpośrednio mapowane na znane wartości 2-znakowe ccTLD („domena najwyższego poziomu”), np. „uk” w „co.uk”. W niektórych przypadkach tag region obsługuje też kody ISO-3166-1, które czasami różnią się od wartości ccTLD (np. „GB” zamiast „Wielka Brytania”).

Gdy używasz parametru region:

  • Określ tylko 1 kraj lub region. Wiele wartości jest ignorowanych, co może spowodować niepowodzenie prośby.
  • Używaj tylko 2-znakowych tagów regionów (w formacie Unicode CLDR). Wprowadzanie innych danych spowoduje wyświetlenie błędów.
  • Obsługiwane są tylko kraje i regiony wymienione w szczegółach dotyczących zasięgu Google Maps Platform.

Żądania geokodowania mogą być wysyłane w przypadku każdej domeny, w której główna aplikacja Map Google oferuje geokodowanie. Pamiętaj, że ustawienie preferencji tylko preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną istnieją bardziej trafne wyniki, mogą one zostać uwzględnione.

Na przykład geokod „Toledo” zwraca ten wynik, ponieważ domyślna domena usługi geokodowania jest ustawiona na Stany Zjednoczone:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Geokodowanie „Toledo” z polem region ustawionym na 'es' (Hiszpania) zwróci hiszpańskie miasto:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Filtrowanie komponentów

Możesz skonfigurować usługę geokodowania tak, aby zwracała wyniki adresu ograniczone do określonego obszaru, używając filtra komponentów. Określ filtr w parametrze componentRestrictions. Wartości filtrów obsługują te same metody poprawiania pisowni i dopasowania częściowego co inne żądania geokodowania.

Geokodownik zwraca tylko wyniki, które pasują do wszystkich filtrów komponentu. Oznacza to, że specyfikacje filtra są oceniane jako AND, a nie OR.

Filtr komponentów składa się z co najmniej 1 z tych elementów:

  • route pasuje do długiej lub krótkiej nazwy trasy.
  • locality dopasowuje się do typów lokalizacji i podtypów lokalizacji.
  • administrativeArea pasuje do wszystkich poziomów obszaru administracyjnego.
  • postalCode pasuje do kodów pocztowych i prefiksów kodów pocztowych.
  • country pasuje do nazwy kraju lub dwuliterowego kodu kraju ISO 3166-1. Uwaga: interfejs API stosuje standard ISO do definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Ten przykład pokazuje użycie parametru componentRestrictions do filtrowania według parametrów country i postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Realizacja w przypadku braku wyników

W przypadku odwrotnego geokodowania domyślnie obietnica jest niespełniona w przypadku wartości status=ZERO_RESULTS. W takim przypadku pola dodatkowego poziomu odpowiedzi plus_code i address_descriptor mogą być nadal wypełnione. Jeśli parametr fulfillOnZeroResults ma wartość Prawda, zostanie wypełniony w tym przypadku. Jeśli parametr fulfillOnZeroResults ma wartość Prawda, obietnica nie została zerwana i te dodatkowe pola są dostępne w obietnicy, jeśli są obecne.

Poniżej znajdziesz przykład tego zachowania w przypadku współrzędnych geograficznych w Antarktyce. Nawet jeśli nie ma wyników odwrotnego geokodowania, możemy nadal wydrukować kod plusa w obietnicy, jeśli ustawimy fulfillOnZeroResults=true. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Deskryptory adresu

Deskryptory adresów zawierają dodatkowe informacje, które pomagają opisać lokalizację za pomocą punktów orientacyjnych i obszarów. Aby zapoznać się z tą funkcją, obejrzyj prezentację adresów.

Deskryptory adresów można włączyć za pomocą parametru extraComputations. Aby otrzymać deskryptory adresu w odpowiedzi, dodaj parametr extra_computations=ADDRESS_DESCRIPTORS do żądania geokodowania, żądania odwrotnego geokodowania lub żądania geokodowania miejsc.

Przykład geokodowania miejsc

To zapytanie zawiera adres miejsca w Delhi.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Przykład odwrotnego geokodowania

To zapytanie zawiera współrzędne szerokości i długości geograficznej lokalizacji w Delhi.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Przykład deskryptora adresu

Przykład address_descriptor:

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

W każdym obiekcie address_descriptor występują 2 tablice: landmarks i areas. Tablica landmarks zawiera maksymalnie 5 wyników uporządkowanych według trafności z uwzględnieniem bliskości żądanych współrzędnych, popularności punktu orientacyjnego i jego widoczności. Każdy wynik dotyczący punktu orientacyjnego zawiera te wartości:

  • place_id to identyfikator miejsca w wyniku z punktami orientacyjnymi. Zapoznaj się z omówieniem identyfikatora miejsca.
  • display_name to wyświetlana nazwa punktu orientacyjnego, która zawiera language_code i text.
  • straight_line_distance_meters to odległość w metrach między punktem wejściowym a wynikiem z uwzględnieniem punktów orientacyjnych.
  • travel_distance_meters to odległość w metrach przebyta po sieci drogowej (z pominięciem ograniczeń drogowych) między współrzędnymi wejściowymi a wynikiem zwracanym przez punkty orientacyjne.
  • spatial_relationship to szacowany związek między współrzędnymi wejściowymi a wynikiem dotyczącym punktów orientacyjnych:
    • "NEAR" to domyślna relacja, gdy nie ma zastosowania żadne z tych relacji.
    • "WITHIN", gdy współrzędna wejściowa znajduje się w granicach struktury powiązanej z punktem orientacyjnym.
    • "BESIDE" gdy współrzędna wejściowa znajduje się bezpośrednio obok punktu dostępu do zabytku lub punktu dostępu do zabytku.
    • "ACROSS_THE_ROAD", gdy współrzędne wejściowe znajdują się po przeciwnej stronie punktu orientacyjnego po drugiej stronie trasy.
    • "DOWN_THE_ROAD", gdy współrzędna wejściowa znajduje się na tej samej trasie co punkt orientacyjny, ale nie "BESIDES" ani "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" gdy współrzędne wejściowe znajdują się na drodze prostopadłej do punktu orientacyjnego (ograniczone do jednego skrętu).
    • "BEHIND" gdy współrzędne wejściowe znajdują się w pobliżu punktu orientacyjnego, ale daleko od punktu dostępu.
  • types to typy miejsc związane z miejscem.

Obiekt areas zawiera maksymalnie 3 odpowiedzi i ogranicza się do miejsc, które reprezentują małe regiony, takie jak dzielnice, mniejsze jednostki administracyjne i duże kompleksy. Obszary zawierające podane współrzędne są wyświetlane jako pierwsze i posortowane od najmniejszego do największego. Każdy wynik areas zawiera te wartości:

  • place_id to identyfikator miejsca w wyniku „areas”. Zapoznaj się z omówieniem identyfikatora miejsca.
  • display_name to wyświetlana nazwa obszaru, która zawiera language_code i text.
  • containment to szacowany związek zasięgu między współrzędnymi wejściowymi a wynikiem obszarów:
    • "NEAR" to domyślna relacja, gdy nie ma zastosowania żadne z tych relacji.
    • "WITHIN" gdy współrzędna wejściowa jest zbliżona do środka obszaru.
    • "OUTSKIRTS" gdy współrzędna wejściowa znajduje się blisko krawędzi obszaru.

Zasięg deskryptorów adresu

Deskryptory adresu są dostępne w GA w Indiach. Korzystanie z opisów adresów w Indiach nie wiąże się z dodatkowymi kosztami i jest objęte dotychczasową poziom SKU Essentials (geokodowanie, Indie).

Prześlij opinię

Ta funkcja jest dostępna we wszystkich regionach. Ta funkcja jest dostępna w wersji GA w Indiach, a w pozostałych regionach jest w fazie eksperymentalnej przed GA. Będziemy wdzięczni za opinię:

Odwrotne geokodowanie (wyszukiwanie adresu)

Termin geokodowanie odnosi się ogólnie do przekształcania adresu w postaci czytelnej dla człowieka w lokalizację na mapie. Proces odwrotny, czyli przekształcanie lokalizacji na mapie w adres zrozumiały dla człowieka, nazywa się odwrotnym geokodowaniem.

Zamiast podawać tekstowy parametr address, podaj w parametrze location pary współrzędnych geograficzne (długość i szerokość geograficzna) rozdzielone przecinkami.

W tym przykładzie geokodujemy współrzędne geograficzne i wyśrodkowujemy mapę na tej lokalizacji, wyświetlając okno z sformatowanym adresem:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Zobacz przykład

Wypróbuj fragment

Pamiętaj, że w poprzednim przykładzie wyświetliliśmy pierwszy wynik, wybierając results[0]. Odwrotny geokodownik często zwraca więcej niż 1 wynik. Adresy geokodowane to nie tylko adresy pocztowe, ale dowolny sposób na określenie lokalizacji geograficznej. Podczas geokodowania punktu w mieście Chicago może on zostać oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są adresami dla geokodera. Odwrotny geokodownik zwraca wszystkie te wyniki.

Odwrotny geokodownik dopasowuje jednostki polityczne (kraje, prowincje, miasta i dzielnice), adresy ulic i kodów pocztowych.

Oto przykład listy adresów, którą może zwrócić powyższe zapytanie: 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Adresy są zwracane w kolejności od najlepszego do najgorszego dopasowania. Zazwyczaj im dokładniejszy adres, tym ważniejszy wynik, jak w tym przypadku. Pamiętaj, że zwracamy różne typy adresów, od najbardziej szczegółowych adresów ulicy do mniej szczegółowych jednostek administracyjnych, takich jak dzielnice, miasta, powiaty, stany itp. Jeśli chcesz dopasować adres bardziej ogólny, możesz sprawdzić pole results[].types.

Uwaga: odwrotne geokodowanie nie jest nauką ścisłą. Geokoder spróbuje znaleźć najbliższą lokalizację z adresem w określonym zakresie tolerancji.

Pobieranie adresu na podstawie identyfikatora miejsca

Podaj placeId, aby znaleźć adres podany w identyfikatorze miejsca. Identyfikator miejsca to unikalny identyfikator, którego można używać z innymi interfejsami API Google. Możesz na przykład podać wartość placeId zwróconą przez interfejs Roads API, aby uzyskać adres punktu załamania. Więcej informacji o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatorów miejsc.

Gdy podajesz placeId, żądanie nie może zawierać tych pól:

  • address
  • latLng
  • location
  • componentRestrictions

W tym przykładzie funkcja przyjmuje identyfikator miejsca, wyszukuje odpowiadający mu adres i środkuje na nim mapę. Wyświetla się też okno z sformatowanym adresem danego miejsca:

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Zobacz przykład

Wypróbuj fragment