Usługa geokodowania

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

Przegląd

Geokodowanie to proces przekształcania adresów (np. „1600 Amphitheatre Parkway, Mountain View, CA”) w współrzędne geograficzne (np. szerokość geograficzna 37.423021 i długość geograficzna -122.083739), których możesz używać do umieszczania znaczników lub pozycjonowania mapy.

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

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

Interfejs Maps JavaScript API udostępnia klasę Geocoder do dynamicznego geokodowania i odwrotnego geokodowania na podstawie danych wejściowych użytkownika. Jeśli chcesz geokodować statyczne, znane adresy, zapoznaj się z informacjami o usłudze internetowej geokodowania.

Rozpocznij

Zanim zaczniesz korzystać z 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, który został skonfigurowany na potrzeby interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API na panelu znajdź Geocoding API.
  4. Jeśli widzisz interfejs API na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, 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, a następnie wybierz go z listy wyników.
    3. Kliknij WŁĄCZ. Po zakończeniu procesu na panelu na liście interfejsów API pojawi się Geocoding API.

Ceny i zasady

Ceny

Informacje o cenach i zasadach korzystania z usługi geokodowania w JavaScript znajdziesz w sekcji Korzystanie i rozliczenia w artykule o interfejsie Geocoding API.

Zasady

Korzystanie z usługi Geocoding musi być zgodne z zasadami dotyczącymi interfejsu Geocoding API.

Żądania geokodowania

Dostęp do usługi geokodowania jest asynchroniczny, ponieważ interfejs Google Maps API musi wywołać zewnętrzny serwer. Dlatego musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żą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 Google Maps API za pomocą obiektu konstruktora google.maps.Geocoder. Metoda Geocoder.geocode() inicjuje żądanie do usługi geokodowania, przekazując do niej literał obiektu GeocoderRequest zawierający terminy wejściowe i metodę wywołania zwrotnego, która ma zostać wykonana po otrzymaniu odpowiedzi.

Literał obiektu GeocoderRequest zawiera te pola:

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

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

  • address – adres, który chcesz geokodować.
         lub
    location – LatLng (lub LatLngLiteral), dla którego chcesz uzyskać najbliższy, czytelny dla człowieka adres. Geokoder wykonuje odwrotne geokodowanie. Więcej informacji znajdziesz w sekcji Geokodowanie zwrotne.
         lub
    placeId – identyfikator miejsca, dla którego chcesz uzyskać najbliższy adres w formacie czytelnym dla człowieka. Więcej informacji znajdziesz w artykule pobieranie adresu na podstawie identyfikatora miejsca.

Parametry opcjonalne:

  • bounds – LatLngBounds, w którym wyniki geokodowania mają być bardziej widoczne. Parametr bounds będzie tylko wpływać na wyniki z geokodera, a nie w pełni je ograniczać. Więcej informacji o ustawianiu priorytetu dla widocznego obszaru znajdziesz poniżej.
  • 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 (nienumeryczny) podtag Unicode regionu. W większości przypadków te tagi są mapowane bezpośrednio na znane 2-znakowe wartości ccTLD („domena najwyższego poziomu”). Parametr region będzie tylko wpływać na wyniki geokodera, a nie w pełni je ograniczać. Więcej informacji o ustawianiu preferencji dotyczących kodu regionu znajdziesz poniżej.
  • extraComputations – jedyną dozwoloną wartością tego parametru jest ADDRESS_DESCRIPTORS. Więcej informacji znajdziesz w  opisach adresów.
  • fulfillOnZeroResults – spełnij obietnicę dotyczącą stanu ZERO_RESULT w odpowiedzi. Może to być pożądane, ponieważ nawet w przypadku braku wyników geokodowania mogą być zwracane dodatkowe pola na poziomie odpowiedzi. Więcej informacji znajdziesz w artykule Realizacja zamówień w przypadku braku wyników.

Odpowiedzi geokodowania

Usługa geokodowania wymaga metody wywołania zwrotnego, która ma być wykonywana po pobraniu wyników geokodera. To wywołanie zwrotne powinno przekazywać 2 parametry, które będą zawierać odpowiednio results i kod status.

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
 }
}

Poniżej znajdziesz wyjaśnienia tych pól:

  • types[] to tablica wskazująca typ adresu zwróconego wyniku. Ta tablica zawiera zestaw tagów (co najmniej 1) identyfikujących typ funkcji zwróconej w wyniku. Na przykład geokod „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co oznacza, że jest to jednostka polityczna. Więcej informacji o typach adresów i typach komponentów adresu znajdziesz poniżej.
  • formatted_address to ciąg tekstowy zawierający adres tej lokalizacji w formie czytelnej dla człowieka.

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

    Sformatowany adres logicznie składa się z co najmniej 1 komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych komponentów: „111” (numer ulicy), „8th Avenue” (trasa), „New York” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu programowo. Zamiast tego używaj poszczególnych komponentów adresu, które są uwzględniane w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.

  • address_components[] to tablica zawierająca poszczególne komponenty odnoszące się do tego adresu.

    Każdy komponent adresu zawiera zwykle te pola:

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

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

    • Tablica komponentów adresu może zawierać więcej komponentów niż formatted_address.
    • Tablica nie musi zawierać wszystkich jednostek politycznych, które zawierają adres, z wyjątkiem tych, które są uwzględnione w formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj geokodowania zwrotnego, przekazując szerokość i długość geograficzną adresu jako parametr żądania.
    • Format odpowiedzi nie musi być taki sam w przypadku różnych żądań. W szczególności liczba address_components zależy od żądanego adresu i może się zmieniać z czasem w przypadku tego samego adresu. Komponent może zmienić pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować określonego komponentu.

    Więcej informacji o typach adresów i typach komponentów adresu znajdziesz poniżej.

  • partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Sprawdź, czy w pierwotnej prośbie nie ma błędów pisowni lub niepełnego adresu.

    Częściowe dopasowania najczęściej występują w przypadku adresów ulic, które nie istnieją w miejscowości przekazywanej w żądaniu. Częściowe dopasowania mogą być też zwracane, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości. Na przykład „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie napisaną część adresu, usługa geokodowania może zaproponować alternatywny adres. Sugestie wywołane w ten sposób będą też oznaczone jako częściowe dopasowanie.

  • place_idjest unikalnym identyfikatorem miejsca, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć biblioteki place_id z interfejsem Google Places API, aby uzyskać szczegółowe informacje o firmie działającej lokalnie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zapoznaj się z omówieniem identyfikatorów miejsc.
  • postcode_localities[] to tablica oznaczająca wszystkie miejscowości zawarte w kodzie pocztowym. Jest ona obecna tylko wtedy, gdy wynikiem jest kod pocztowy zawierający wiele miejscowości.

  • geometry zawiera te informacje:

    • location zawiera wartość szerokości i długości geograficznej po geokodowaniu. 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ą te wartości:
      • ROOFTOP oznacza, że zwrócony wynik odzwierciedla dokładny geokod.
      • RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowaniami). Interpolowane wyniki są zwykle zwracane, gdy dla adresu ulicy nie są dostępne geokody dachu.
      • GEOMETRIC_CENTER oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak linia łamana (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 LatLngBounds, który może w pełni zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie pasować do zalecanego obszaru wyświetlania. (Na przykład San Francisco obejmuje Wyspy Farallon, które technicznie są częścią miasta, ale nie powinny być zwracane w obszarze widoku).

Adresy są zwracane przez geokoder w języku preferowanym przez przeglądarkę lub w języku określonym podczas wczytywania kodu JavaScript interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w sekcji Lokalizacja).

Typy adresów i rodzaje komponentów adresu

Tablica types[] w obiekcie GeocoderResult w odpowiedzi wskazuje typ adresu. Przykłady typów adresów to adres ulicy, kraj lub jednostka polityczna. Tablica types w GeocoderAddressComponent wskazuje typ każdej części adresu. Mogą to być np. numer ulicy lub kraj.

Adresy mogą mieć wiele typów. Typy te można uznać za „tagi”. Na przykład wiele miast jest oznaczonych typami political i locality.

Obsługiwane są te typy, które są zwracane w tablicach typu adresu i typu komponentu adresu:

Typ adresu Opis
street_address dokładny adres.
route Nazwa trasy (np. „US 101”).
intersection Główne skrzyżowanie, zwykle dwóch głównych dróg.
political podmiot polityczny; Zwykle ten typ wskazuje wielokąt przedstawiający jakąś jednostkę 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ą ściśle odpowiadać podziałom ISO 3166-2 i innym powszechnie używanym listom, ale nie jest to gwarantowane, ponieważ nasze wyniki geokodowania są oparte na różnych sygnałach i danych o lokalizacji.
administrative_area_level_2 Jednostka administracyjna drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_3 Jednostka administracyjna trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_4 Jednostka administracyjna czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_5 Jednostka administracyjna 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 Jednostka administracyjna 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 Jednostka administracyjna 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 elementu.
locality podmiot polityczny w postaci miasta lub miejscowości;
sublocality Jednostka administracyjna pierwszego rzędu poniżej poziomu miejscowości. W przypadku niektórych lokalizacji może być wyświetlany jeden z dodatkowych typów: sublocality_level_1–sublocality_level_5. Każdy poziom podlokalizacji jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny.
neighborhood Nazwana okolica.
premise Nazwana lokalizacja, zwykle budynek lub zespół budynków o wspólnej nazwie.
subpremise Adresowalny obiekt poniżej poziomu lokalu, np. mieszkanie, lokal lub apartament.
plus_code Zakodowany odnośnik do lokalizacji, który jest wyznaczany na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastępować adresy w miejscach, w których nie istnieją (gdzie budynki nie mają numerów, a ulice nie mają nazw). Więcej informacji znajdziesz na https://plus.codes.
postal_code Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
natural_feature Wyraźny obiekt naturalny.
airport lotnisko,
park Nazwany park.
point_of_interest Nazwane ciekawe miejsce. Zazwyczaj są to znane lokalne obiekty, które nie pasują do żadnej innej kategorii, np. „Empire State Building” lub „Wieża Eiffla”.

Pusta lista typów oznacza, że dla danego komponentu adresu nie ma znanych typów (np. Lieu-dit we Francji).

Oprócz powyższych komponenty adresu mogą obejmować typy wymienione poniżej.

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

Oprócz powyższych komponenty 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 jest używane jako punkt odniesienia ułatwiający nawigację.
point_of_interest Nazwane ciekawe miejsce.
parking parking lub parking wielopoziomowy;
post_box Konkretna skrytka pocztowa.
postal_town Grupa obszarów geograficznych, np. locality i sublocality, używana w adresach pocztowych w niektórych krajach.
room Pokój w adresie budynku.
street_number Dokładny numer ulicy.
bus_station, train_station i transit_station Lokalizacja przystanku autobusowego, kolejowego lub transportu publicznego.

Kody stanu

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

  • "OK" oznacza, że nie wystąpiły żadne błędy. Adres został prawidłowo przeanalizowany i zwrócono co najmniej 1 geokod.
  • "ZERO_RESULTS" oznacza, że geokodowanie zakończyło się powodzeniem, 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 przekraczasz limit.
  • "REQUEST_DENIED" oznacza, że Twoja prośba została odrzucona. Strona internetowa nie może korzystać z geokodera.
  • Symbol "INVALID_REQUEST" zwykle oznacza, że brakuje zapytania (address, components lub latlng).
  • "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.
  • "ERROR" oznacza, że upłynął limit czasu żądania lub wystąpił problem z nawiązaniem połączenia z serwerami Google. Jeśli spróbujesz ponownie, żądanie może się powieść.

W tym przykładzie geokodujemy adres i umieszczamy znacznik w zwróconych wartościach szerokości i długości geograficznej. Pamiętaj, że moduł obsługi 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

Ustalanie priorytetów widocznego obszaru

Możesz poinstruować usługę Geocoding Service, aby preferowała wyniki w danym widocznym obszarze (wyrażonym jako pole ograniczające). Aby to zrobić, ustaw parametr bounds w obiekcie GeocoderRequest, aby zdefiniować granice tego widocznego obszaru. Pamiętaj, że faworyzowanie tylko preferuje wyniki w określonych granicach. Jeśli istnieją bardziej trafne wyniki poza tymi granicami, mogą one zostać uwzględnione.

Na przykład kod geograficzny dla „Winnetka” zwykle zwraca tę dzielnicę 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 podasz parametr bounds określający pole ograniczenia dla doliny San Fernando w Los Angeles, ten geokod zwróci nazwę dzielnicy „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"
}

Preferowanie kodu regionu

Możesz skonfigurować usługę geokodowania tak, aby zwracała wyniki z określonego regionu, używając parametru region. Ten parametr przyjmuje kod regionu określony jako 2-znakowy (nieliczbowy) podtag regionu Unicode. Te tagi są mapowane bezpośrednio na znane 2-znakowe wartości ccTLD („domena najwyższego poziomu”), np. „uk” w domenie „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 „Great Britain”).

Podczas korzystania z parametru region:

  • Określ tylko jeden kraj lub region. Wiele wartości jest ignorowanych i może spowodować niepowodzenie żądania.
  • Używaj tylko dwuznakowych podtagów regionu (format Unicode CLDR). Wszystkie inne dane wejściowe spowodują błędy.
  • Obsługiwane są tylko kraje i regiony wymienione w szczegółach dotyczących zasięgu Google Maps Platform.

Żądania geokodowania można wysyłać dla każdej domeny, w której główna aplikacja Mapy Google oferuje geokodowanie. Pamiętaj, że faworyzowanie tylko preferuje wyniki z określonej domeny. Jeśli poza tą domeną istnieją bardziej trafne wyniki, mogą one zostać uwzględnione.

Na przykład geokod dla „Toledo” zwraca ten wynik, ponieważ domena domyślna 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"
}

Kod geograficzny dla „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 adresów 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 korekty pisowni i dopasowania częściowego co inne żądania geokodowania.

Geokoder zwraca tylko wyniki, które pasują do wszystkich filtrów komponentów. Oznacza to, że ocenia specyfikacje filtra jako warunek 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 podlokalizacji.
  • administrativeArea pasuje do wszystkich poziomów regionu.
  • postalCode pasuje do kodów pocztowych i ich prefiksów.
  • country pasuje do nazwy kraju lub dwuliterowego kodu kraju w standardzie ISO 3166-1. Uwaga: interfejs API jest zgodny ze standardem ISO dotyczącym definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Ten przykład pokazuje, jak używać parametru componentRestrictions do filtrowania według 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 przy braku wyników

W przypadku odwrotnego geokodowania obietnica jest domyślnie naruszana w przypadku status=ZERO_RESULTS. Jednak dodatkowe pola poziomu odpowiedzi plus_code i address_descriptor mogą być w tym przypadku nadal wypełnione. Jeśli w przypadku parametru fulfillOnZeroResults podano wartość „true”, w tym przypadku pole zostanie wypełnione. Jeśli w przypadku parametru fulfillOnZeroResults podano wartość „true”, obietnica nie jest naruszana, a te dodatkowe pola są dostępne w obietnicy, jeśli są obecne.

Poniżej znajdziesz przykład takiego zachowania w przypadku szerokości i długości geograficznej na Antarktydzie. Nawet jeśli nie ma wyników geokodowania wstecznego, możemy wydrukować kod plus w obietnicy, jeśli ustawimy wartość 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 poznać tę funkcję, obejrzyj demonstrację deskryptorów adresu.

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

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 wartość 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" ]
          }
       ]
    }
  }

Każdy obiekt address_descriptor zawiera 2 tablice: landmarks i areas. Tablica landmarks zawiera maksymalnie 5 wyników uporządkowanych według trafności z uwzględnieniem odległości od żą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 wyniku dotyczącego punktów orientacyjnych. 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 współrzędnymi wejściowymi a wynikiem dotyczącym punktów orientacyjnych.
  • travel_distance_meters to odległość w metrach pokonana w sieci dróg (z pominięciem ograniczeń drogowych) między współrzędnymi wejściowymi a wynikiem dotyczącym punktów orientacyjnych.
  • spatial_relationship to szacunkowa relacja między współrzędną wejściową a wynikiem punktów orientacyjnych:
    • "NEAR" to domyślna relacja, gdy nie ma zastosowania żadna z tych opcji.
    • "WITHIN", gdy współrzędna wejściowa znajduje się w granicach struktury powiązanej z punktem orientacyjnym.
    • "BESIDE" gdy współrzędne wejściowe są bezpośrednio sąsiadujące z punktem orientacyjnym lub punktem dostępu do niego.
    • "ACROSS_THE_ROAD" gdy współrzędna wejściowa znajduje się bezpośrednio naprzeciwko punktu orientacyjnego po drugiej stronie trasy.
    • "DOWN_THE_ROAD", gdy współrzędne wejściowe znajdują się na tej samej trasie co punkt orientacyjny, ale nie są to "BESIDES" ani "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" gdy współrzędne wejściowe znajdują się na trasie prostopadłej do punktu orientacyjnego (ograniczone do jednego skrętu);
    • "BEHIND" gdy współrzędne wejściowe są blisko punktu orientacyjnego, ale daleko od jego punktu dostępu.
  • types to typy miejsc charakterystycznego obiektu.

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

  • place_id to identyfikator miejsca wyniku obszarów. Zapoznaj się z omówieniem identyfikatora miejsca.
  • display_name to wyświetlana nazwa obszaru, która zawiera language_code i text.
  • containment to szacunkowa relacja między współrzędnymi wejściowymi a wynikiem obszarów:
    • "NEAR" to domyślna relacja, gdy nie ma zastosowania żadna z tych opcji.
    • "WITHIN" gdy współrzędne wejściowe są blisko środka obszaru.
    • "OUTSKIRTS" gdy współrzędne wejściowe znajdują się blisko krawędzi obszaru.

Pokrycie deskryptorów adresu

Deskryptory adresów są dostępne w GA w przypadku Indii. Korzystanie z deskryptorów adresów w Indiach nie wiąże się z dodatkowymi kosztami, a ich użycie jest objęte istniejącym kodem SKU Geocoding (India) Essentials.

Prześlij opinię

Ta funkcja jest dostępna we wszystkich regionach. W Indiach jest dostępna ogólnie, a w pozostałych regionach znajduje się na etapie eksperymentalnego wprowadzenia przed GA. Chętnie poznamy Twoją opinię:

Odwrotne geokodowanie (wyszukiwanie adresu)

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

Zamiast podawać tekstowy address, podaj rozdzieloną przecinkami parę współrzędnych geograficznych w parametrze location.

W tym przykładzie współrzędne geograficzne są przekształcane na adres, a mapa jest wyśrodkowywana w tej lokalizacji. Wyświetla się też okno informacyjne z sformatowanym adresem:

TypeScript

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async 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]) {
                marker.position = latlng;
                map.setCenter(latlng);
                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));
}

initMap();
index.ts

JavaScript

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async 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]) {
            marker.position = latlng;
            map.setCenter(latlng);
            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));
}
initMap();
index.js
Zobacz przykład

Wypróbuj przykład

Pamiętaj, że w poprzednim przykładzie pokazaliśmy pierwszy wynik, wybierając results[0]. Geokoder zwrotny często zwraca więcej niż jeden wynik. Adresy geokodowane to nie tylko adresy pocztowe, ale też dowolny sposób na geograficzne nazwanie lokalizacji. Na przykład podczas geokodowania punktu w Chicago może on zostać oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są adresami dla geokodera. Geokoder zwrotny zwraca wszystkie te wyniki.

Geokoder odwrotny dopasowuje jednostki administracyjne (kraje, prowincje, miasta i dzielnice), adresy ulic i kody pocztowe.

Oto przykład listy adresów, które 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. Zwykle najbardziej precyzyjny adres jest najbardziej widocznym wynikiem, tak jak w tym przypadku. Pamiętaj, że zwracamy różne typy adresów, od najbardziej szczegółowego adresu ulicy po mniej szczegółowe jednostki administracyjne, takie jak dzielnice, miasta, hrabstwa, stany itp. Jeśli chcesz dopasować bardziej ogólny adres, 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 dla danego identyfikatora 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 Roads API, aby uzyskać adres przyciągniętego punktu. Więcej informacji o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.

Jeśli podasz wartość placeId, żądanie nie może zawierać żadnego z tych pól:

  • address
  • latLng
  • location
  • componentRestrictions

W tym przykładzie akceptowany jest identyfikator miejsca, wyszukiwany jest odpowiedni adres, a mapa jest wyśrodkowywana w tej lokalizacji. Wyświetla też okno informacyjne z sformatowanym adresem odpowiedniego 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 przykład