Usługa geokodowania

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.

Pierwsze kroki

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

Od 16 lipca 2018 r. w przypadku Map, Tras i Miejsc obowiązuje nowy abonament oparty na płatnościach „pay-as-you-go”. Więcej informacji o nowych cenach i limitach użycia usługi geokodowania JavaScript znajdziesz w sekcji Korzystanie i rozliczenia interfejsu Geocoding API.

Zasady

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

Żądania 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 zostanie 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 w formie zrozumiałej 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  deskryptorach adresów.
  • 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 Zrealizowanie zamówienia przy 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: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
 }
}

Poniżej opisujemy te pola:

  • types[] to tablica wskazująca typ adresu zwróconego wyniku. Ten tablic 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 oznacza, ż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 w przypadku stanu Alaska może mieć long_name „Alaska” i short_name „AK” (2-literowy skrót pocztowy).

    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, z wyjątkiem tych, które są uwzględnione w tablicy formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, należy użyć 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 żądania, 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 do co najmniej 2 lokalizacji w tej samej miejscowości mogą być zwracane również częściowe dopasowania. Na przykład wyszukiwanie „Hillpar St, Bristol, UK” zwróci dopasowanie częściowe zarówno do Henry Street, jak i 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 uzyskać informacje o firmie działającej lokalnie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. 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. Obecnie obsługiwane są te wartości:
      • ROOFTOP wskazuje, ż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 nie są dostępne dla adresu ulicznego.
      • GEOMETRIC_CENTER oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak polilinia (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).

Geokoder zwróci adresy, używając 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 artykule lokalizacja).

Typy adresów i typy ich komponentów

Tablica types[] w GeocoderResult wskazuje typ adresu. Tablica types[] może być też zwracana w ramach GeocoderAddressComponent, aby wskazać typ danego elementu adresu. Adresy zwracane przez geokoder mogą mieć różne typy, które mogą być traktowane jako tagi. Na przykład wiele miast ma tagi typu political i locality.

Geokoder obsługuje i zwraca te typy adresów oraz typy komponentów adresu:

  • street_address oznacza dokładny adres.
  • route wskazuje nazwaną trasę (np. „US 101”).
  • intersection wskazuje główne skrzyżowanie, zwykle 2 głównych dróg.
  • political oznacza podmiot polityczny. Zwykle ten typ wskazuje wielokąt administracyjny.
  • country wskazuje podmiot polityczny o charakterze krajowym i zwykle jest najwyższym typem zwracanym przez geokoder.
  • administrative_area_level_1 wskazuje podmiot prawny 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 krótkie nazwy administrative_area_level_1 będą bardzo zbliżone do podziałów ISO 3166-2 i innych powszechnie używanych list. Nie jest to jednak gwarantowane, ponieważ nasze wyniki geokodowania opierają się na różnych sygnałach i danych dotyczących lokalizacji.
  • administrative_area_level_2 oznacza jednostkę prawną drugiego rzędu na poziomie niższym niż kraj. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_3 oznacza 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 oznacza podmiot prawny czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_5 wskazuje 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 wskazuje 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 wskazuje 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 wskazuje powszechnie używaną nazwę alternatywną podmiotu.
  • locality oznacza zarejestrowany podmiot polityczny miasta.
  • sublocality oznacza jednostkę cywilną pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji może być wymagany jeden z dodatkowych typów: sublocality_level_1 do sublocality_level_5. Każdy poziom podregionu jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny.
  • neighborhood oznacza nazwę dzielnicy.
  • premise wskazuje nazwę lokalizacji, zwykle budynku lub grupy budynków o wspólnej nazwie.
  • subpremise wskazuje element, który można zidentyfikować na poziomie niższym niż budynek, na przykład mieszkanie, lokal lub apartament.
  • plus_code oznacza zakodowany identyfikator lokalizacji, który jest wyprowadzony ze współrzędnych geograficznych. Kody Plus Code mogą zastępować adresy ulicy w miejscach, w których ich nie ma (gdzie budynki nie mają numerów lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
  • postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
  • natural_feature wskazuje charakterystyczny element przyrodniczy.
  • airport oznacza lotnisko.
  • park oznacza park o nazwie.
  • point_of_interest wskazuje nazwane miejsce docelowe. Zwykle są to znane obiekty lokalne, które nie pasują do żadnej innej kategorii, np. „Empire State Building” czy „Wieża Eiffla”.

Pusta lista typów wskazuje, że nie ma żadnych znanych typów dla danego elementu adresu, na przykład 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.

  • floor wskazuje piętro adresu budynku.
  • establishment zwykle oznacza miejsce, które nie zostało jeszcze skategoryzowane.
  • landmark wskazuje miejsce w pobliżu, które służy jako punkt odniesienia do ułatwienia nawigacji.
  • point_of_interest wskazuje nazwane miejsce docelowe.
  • parking oznacza parking lub parking wielopoziomowy.
  • post_box oznacza konkretny skrypt pocztowy.
  • postal_town wskazuje grupę obszarów geograficznych, takich jak locality i sublocality, używaną do adresów pocztowych w niektórych krajach.
  • room wskazuje pokój w budynku.
  • street_number oznacza dokładny numer budynku.
  • bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, kolejowego lub przystanku transportu publicznego.

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 adres 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ę zrealizować żądania z powodu błędu serwera. Żądanie może się powieść, jeśli spróbujesz ponownie.
  • "ERROR" oznacza, że wystąpił limit czasu oczekiwania na odpowiedź lub 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 (wyrażonym jako pole ograniczające). Aby to zrobić, ustaw parametr bounds w literale obiektu GeocoderRequest, aby zdefiniować granice tego widoku. Pamiętaj, że ustawienie preferencji preferuje wyniki w określonych granicach. Jeśli poza tymi granicami istnieją bardziej odpowiednie 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 kodzie 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”).

Podczas korzystania z parametrza region:

  • Podaj tylko 1 kraj lub region. Wiele wartości jest ignorowanych, co może spowodować niepowodzenie żądania.
  • Używaj tylko 2-znakowych podtagó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.

Prośby o geokodowanie można wysyłać 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.

Geokoder 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, jak za pomocą parametru componentRestrictions filtrować 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 nadal mogą być wypełniane pola dodatkowego poziomu odpowiedzi plus_code i address_descriptor. 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, nadal możemy wydrukować kod plusa w obietnicy, jeśli ustawimy parametr 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`);
        });
    }

Adresy – opisy

Opis adresu zawiera 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ć w odpowiedzi opisy adresów, dodaj extra_computations=ADDRESS_DESCRIPTORS do żądania geokodowania, żądania odwrotnego geokodowania lub żądania geokodowania miejsc.

Przykład geokodowania miejsc

Poniższe zapytanie zawiera adres miejsca w Delhi.

function addressDescriptorPlaceIdLookup() {
  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" ]
          }
       ]
    }
  }

W każdym obiekcie address_descriptor znajdują się 2 tablice: landmarks i areas. Tablica landmarks zawiera maksymalnie 5 wyników uporządkowanych według trafności z uwzględnieniem bliskości do żą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 wyszukiwania 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 punktem wejściowym a wynikiem z uwzględnieniem punktów orientacyjnych.
  • travel_distance_meters to odległość w metrach pokonana po sieci drogowej (z pominięciem ograniczeń drogowych) między współrzędnymi wejściowymi a wynikiem z uwzględnieniem punktów orientacyjnych.
  • 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 żadna z tych relacji.
    • "WITHIN", gdy współrzędna wejściowa mieści się w granicach struktury powiązanej z punktem orientacyjnym.
    • "BESIDE" gdy współrzędne wejściowe są bezpośrednio przy zabytku lub punkcie 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 żadna z tych relacji.
    • "WITHIN" gdy współrzędna wejściowa jest zbliżona do środka obszaru.
    • "OUTSKIRTS" gdy współrzędna wejściowa jest blisko krawędzi obszaru.

Zasięg deskryptora adresu

Ta funkcja jest dostępna tylko w wybranych krajach.

To jest funkcja w wersji testowej, dlatego prosimy o opinię. Wyślij e-maila na adres address-descriptors-feedback@google.com.

Odwrotne geokodowanie (wyszukiwanie adresu)

Termin geokodowanie odnosi się zazwyczaj 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 geograficznych (szerokość/długość 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 próbkę

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.

Geokodowanie odwrotne umożliwia dopasowanie jednostek politycznych (krajów, miast, dzielnic), adresów 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ółowego adresu 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ę adresowalną 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ć w innych interfejsach 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

Ten przykład przyjmuje identyfikator miejsca, znajduje odpowiadający mu adres i środkuje mapę na tej lokalizacji. 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 próbkę