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 dla podanego 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 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

16 lipca 2018 r. wszedł w życie nowy abonament z płatnościami według wykorzystania usługi Mapy, Trasy i Miejsca. Więcej informacji o nowych cenach i limitach wykorzystania za korzystanie z usługi geokodowania JavaScript znajdziesz w artykule o korzystaniu i płatnościach za korzystanie z interfejsu Geocoding API.

Zasady

Korzystanie z usługi Geocoding musi być zgodne z zasadami opisanymi dla interfejsu 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 żądania. Ta metoda wywołania zwrotnego przetwarza wyniki. Pamiętaj, że geokoder może zwrócić więcej niż 1 wynik.

Dostęp do usługi geokodowania interfejsu API Map Google uzyskujesz w kodzie 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órego dane geograficzne chcesz przetworzyć na dane geograficzne.
       lub
  location – LatLng (lub LatLngLiteral), dla którego chcesz uzyskać najbliższy adres w formie zrozumiałej dla człowieka. Geokoder wykonuje odwrotny geokod. Więcej informacji znajdziesz w artykule Geokodowanie odwrotne.
       lub
  placeId – identyfikator miejsca, w przypadku którego chcesz uzyskać najbliższy, zrozumiały dla człowieka adres. 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. Parametr bounds będzie miał wpływ na wyniki geokodowania, ale nie będzie ich w pełni ograniczać. Więcej informacji o promowaniu 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 (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 ma wpływ tylko na wyniki generowane przez geokoder, a nie na jego pełne ograniczenia. 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 artykule o deskryptorach adresów.
• fulfillOnZeroResults – spełnia obietnicę stanu ZERO_RESULT w odpowiedzi. 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, które zawierają odpowiednio kod results i status.

Wyniki kodowania geograficznego

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 objaśniono te pola:

• types[] to tablica wskazująca typ adresu zwróconego wyniku. Ta tablica zawiera zestaw zero lub więcej tagów identyfikujących typ cechy zwróconej w wyniku. 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 komponentów: „111” (numer domu), „8th Avenue” (trasa), „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 komponent adresu zawiera zwykle te pola:

  • types[] to tablica wskazująca typ elementu adresu. Zobacz listę obsługiwanych typów.
  • long_name to pełny opis tekstowy lub nazwa komponentu adresu zwrócone przez Geocoder.
  • short_name to skrócona nazwa tekstowa komponentu 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 obejmuje wszystkie podmioty polityczne, które zawierają adres, z wyjątkiem tych zawartych w tabeli 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 między żądaniami pozostanie taki sam. 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 częściowego może zostać zwrócony wynik, 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 Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, usługa geokodowania może zaproponować alternatywny adres. Propozycje utworzone 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. Na przykład możesz użyć place_id z biblioteką 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 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 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 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 zwracana) przechowuje obiekt LatLngBounds, który może w całości zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanemu widocznemu obszarowi. (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 o lokalizacji).

Typy adresów i typy komponentów adresu

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 zarówno w typach adresów, jak i komponentach adresu:

• street_address wskazuje dokładny adres.
• route wskazuje nazwaną trasę (np. „US 101”).
• intersection oznacza główne skrzyżowanie, zwykle dwóch głównych dróg.
• political oznacza podmiot polityczny. Zwykle ten typ wskazuje poligon administracji cywilnej.
• country wskazuje podmiot polityczny o zasięgu krajowym i jest zwykle najwyższym typem zwracanym przez geokoder.
• administrative_area_level_1 wskazuje podmiot prawny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to stany. Nie we wszystkich krajach obowiązują 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 oznacza niewielką jednostkę cywilną. 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 oznacza niewielką jednostkę cywilną. Nie wszystkie kraje mają te poziomy administracyjne.
• colloquial_area wskazuje powszechnie używaną nazwę alternatywną podmiotu.
• locality oznacza podmiot polityczny z własnym miastem lub miastem.
• sublocality oznacza jednostkę cywilną pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji mogą pojawić się dodatkowe typy: od sublocality_level_1 do sublocality_level_5. Każdy poziom podregionu jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny.
• neighborhood wskazuje nazwany dzielnicę.
• premise wskazuje nawaną lokalizację, zwykle budynek lub zbiór budynków o takiej samej 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 zakodowane odniesienie do lokalizacji na podstawie 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 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. 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 oznacza, że nie ma znanych typów tego składnika adresu, np. Lieu-dit we Francji.

Oprócz wymienionych powyżej komponenty adresu mogą obejmować te typy:

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

• floor wskazuje piętro w adresie budynku.
• establishment zwykle oznacza miejsce, które nie zostało jeszcze sklasyfikowane.
• landmark wskazuje miejsce w pobliżu, które służy jako punkt odniesienia do ułatwienia nawigacji.
• point_of_interest oznacza nazwane miejsce docelowe.
• parking oznacza parking.
• 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 salę w danym 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 geokod został poprawnie użyty, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder został przekazany do nieistniejącego elementu 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. Jeśli spróbujesz jeszcze raz, żądanie może zostać zrealizowane.

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 anonimowy literał funkcji.

  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 odchylenie preferuje tylko wyniki znajdujące się w określonych granicach. Jeśli więcej trafnych wyników znajduje się poza tymi granicami, zostaną one uwzględnione.

Na przykład kod geograficzny dla „Winnetka” zwraca zwykle to przedmieście 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 mapują bezpośrednio na dobrze znane dwuznakowe wartości domeny ccTLD („domena najwyższego poziomu”), np. „pl” 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 jeden 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.

Żądania geokodowania mogą być wysyłane w przypadku każdej domeny, w której główna aplikacja Map Google oferuje geokodowanie. Pamiętaj, że promowanie preferuje tylko wyniki z konkretnej domeny. Jeśli poza tą domeną występują trafniejsze wyniki, zostaną one 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 pasuje do typów rejonów i podrejonów.
• 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 w parametrze fulfillOnZeroResults zostanie podana wartość „prawda”, obietnica nie jest uszkodzona, a te dodatkowe pola są dostępne z obietnicy (jeśli występują).

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 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 adresów

Deskryptory adresów zawierają dodatkowe informacje, które pomagają opisać lokalizację za pomocą punktów orientacyjnych i obszarów. Aby dowiedzieć się więcej o tej funkcji, zobacz prezentację deskryptorów adresów.

Deskryptory adresów można włączać za pomocą parametru extraComputations. Aby w odpowiedzi otrzymywać deskryptory adresów, uwzględnij extra_computations=ADDRESS_DESCRIPTORS w żądaniu geokodowania, żądaniu odwrotnego geokodowania lub żądaniu geokodowania miejsc.

Przykład geokodowania miejsc

Kolejne 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 jest następujący.

  {
    "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 znajduje 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 są bezpośrednio przeciwne do 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 miejscowości i duże kompleksy. Obszary zawierające żądane współrzędne są wymienione 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 geograficzne (szerokość/długość geograficzna) rozdzielone przecinkami.

Poniższy przykładowy kod geograficzny określa długość i szerokość geograficzną oraz wyśrodkowuje mapę w tej lokalizacji, co powoduje wyświetlenie okna informacyjnego ze sformatowanym adresem:

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

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

W poprzednim przykładzie pokazaliśmy pierwszy wynik, wybierając results[0]. Odwrotny geokoder często zwraca więcej niż 1 wynik. Adresy geokodowane to nie tylko adresy pocztowe, ale też dowolny sposób na określenie lokalizacji geograficznej. Na przykład podczas geokodowania punktu w mieście Chicago punkt ten może być oznaczony jako adres pocztowy, 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 największej do najmniejszej liczby dopasowań. Jak w tym przypadku w tym przypadku jest na ogół bardziej dokładny adres. 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 dla danego identyfikatora 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

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:

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

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