Usługa geokodowania

Przegląd

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

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 podanego identyfikatora miejsca.

Interfejs Maps JavaScript API udostępnia klasę geokodera do geokodowania i odwrotnego geokodowania na podstawie danych wejściowych użytkownika. Jeśli zamiast tego chcesz geokodować statyczne, znane adresy, skorzystaj z usługi internetowej geokodowania.

Pierwsze kroki

Zanim użyjesz usługi Geocoding w interfejsie Maps JavaScript API, sprawdź, czy interfejs Geocoding API jest włączony w konsoli Google Cloud w tym samym projekcie, który konfigurujesz 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 następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Geocoding API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. U góry strony wybierz WŁĄCZ 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 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 Geocoding jest asynchroniczny, ponieważ interfejs API Map Google musi wywołać serwer zewnętrzny. 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 mu literał obiektu GeocoderRequest zawierający hasła wejściowe oraz metodę wywołania zwrotnego do wykonania 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órego dane geograficzne chcesz przetworzyć na dane geograficzne.
         lub
    location – adres LatLng (lub LatLngLiteral), dla którego chcesz uzyskać najbliższy, zrozumiały dla człowieka adres. Geokoder wykonuje odwrotny geokod. Więcej informacji znajdziesz w sekcji Odwrotne geokodowanie.
         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 dla identyfikatora miejsca.

Parametry opcjonalne:

  • bounds – LatLngBounds, w ramach którego odchylane są wyniki geokodowania. Parametr bounds będzie miał wpływ tylko na wyniki generowane przez geokoder, ale nie będzie go 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 (nienumeryczny) podtag regionu Unicode. W większości przypadków te tagi są mapowane bezpośrednio na znane dwuznakowe wartości domeny ccTLD („domenie najwyższego poziomu”). Parametr region ma wpływ tylko na wyniki generowane przez geokoder, a nie na jego pełne ograniczenia. Więcej informacji o promowaniu kodu regionu znajdziesz poniżej.
  • extraComputations – jedyna dozwolona wartość w przypadku tego parametru to 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 braku wyników geokodowania nadal mogą być zwracane dodatkowe pola poziomu odpowiedzi. Więcej informacji znajdziesz w artykule na temat realizacji zamówień przy zerowym wyniku.

Odpowiedzi związane z kodowaniem geograficznym

Usługa Geocoding wymaga wykonania metody wywołania zwrotnego po pobraniu wyników geokodera. To wywołanie zwrotne powinno przekazywać 2 parametry pozwalające przechowywać kody results i status w tej kolejności.

Wyniki kodowania geograficznego

Obiekt GeocoderResult reprezentuje pojedynczy wynik geokodowania. Żądanie geokodu 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 geokod z wartością „Chicago” zwraca wartość „locality”, która oznacza, że „Chicago” jest miastem, oraz „polityczny”, co oznacza, że jest podmiotem politycznym. Więcej informacji o typach adresów i typach komponentów adresów znajdziesz poniżej.
  • formatted_address to ciąg znaków zawierający zrozumiały dla człowieka adres tej lokalizacji.

    Adres ten jest często odpowiednikiem adresu pocztowego. 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ę logicznie z co najmniej jednego składnika 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 automatycznie. Zamiast tego używaj poszczególnych komponentów adresu, które oprócz sformatowanego pola adresu zawiera odpowiedź interfejsu API.

  • address_components[] to tablica zawierająca oddzielne komponenty mające zastosowanie 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 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 komponent adresu dla stanu Alaska może mieć wartość long_name o wartości „Alaska” i short_name „AK” z dwuliterowym skrótem pocztowym.

    Zwróć uwagę na te informacje o tablicy address_components[]:

    • Tablica komponentów adresu może zawierać więcej komponentó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 podmioty polityczne, które zawierają konkretny adres, użyj odwrotnego geokodowania, przekazując szerokość i długość geograficzną adresu jako parametr do żądania.
    • Nie ma gwarancji, że format odpowiedzi między żądaniami pozostanie taki sam. W szczególności liczba parametrów 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 adresów znajdziesz poniżej.

  • partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, chociaż mógł dopasować część żądanego adresu. Możesz sprawdzić pierwotną prośbę pod kątem błędów pisowni lub niekompletnych adresów.

    Dopasowania częściowe pojawiają się najczęściej w przypadku adresów, których nie ma w okolicy, którą przekazujesz w żądaniu. Dopasowania częściowe mogą też zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym regionie. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry Street, jak i ulicy Henrietta. Pamiętaj, że jeśli żądanie zawiera błędny adres, usługa geokodowania może zaproponować inny adres. Sugestie wywołane w ten sposób zostaną również oznaczone jako dopasowane częściowo.

  • place_id to unikalny identyfikator miejsca, którego można używać z innymi interfejsami API Google. Na przykład możesz użyć place_id z biblioteką Google Places API, aby uzyskać szczegółowe informacje o firmie lokalnej, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zobacz omówienie identyfikatora miejsca.
  • postcode_localities[] to tablica wskazująca wszystkie miejscowości zawarte w kodzie pocztowym. Jest ona obecna tylko wtedy, gdy wynik to kod pocztowy zawierający wiele miejscowości.

  • geometry zawiera te informacje:

    • location zawiera Geokodowaną wartość szerokości i długości geograficznej. Pamiętaj, że zwracamy tę lokalizację jako obiekt LatLng, a nie w postaci sformatowanego ciągu 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żone (zwykle na drodze) interpolację między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachów są niedostępne dla adresu ulicy.
      • GEOMETRIC_CENTER wskazuje, że zwrócony wynik to środek geometryczny wyniku, np. linii łamanej (na przykład ulicy) lub wielokąta (region).
      • APPROXIMATE wskazuje, ż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 Farallona, które technicznie stanowią część miasta, ale nie powinny się wyświetlać w widocznym obszarze.

Adresy będą zwracane przez geokoder z wykorzystaniem preferowanego ustawienia języka przeglądarki lub języka określonego podczas wczytywania JavaScriptu 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 obiekcie GeocoderResult wskazuje typ adresu. Tablica types[] może też być zwracana w elemencie GeocoderAddressComponent, aby wskazać typ konkretnego komponentu adresu. Adresy zwracane przez geokoder mogą mieć kilka typów. Typy można uznać za tagi. Na przykład wiele miast jest oznaczonych tagiem 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 oznacza trasę z nazwą (np. „E101”).
  • intersection oznacza główne skrzyżowanie, zwykle dwóch głównych dróg.
  • political oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt niektórych obiektów administracji cywilnej.
  • country wskazuje krajowy podmiot polityczny i jest zwykle najwyższym typem zamówienia zwracanym przez geokoder.
  • administrative_area_level_1 oznacza podmiot cywilny 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 administracyjne_area_level_1 będą bardzo podobne do podgrup w standardzie ISO 3166-2 i innych rozpowszechnianych list. Nie jest to jednak gwarantowane, ponieważ wyniki geokodowania opierają się na różnych sygnałach i danych o lokalizacji.
  • administrative_area_level_2 oznacza podmiot cywilny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_3 oznacza podmiot cywilny trzeciego rzędu poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_4 oznacza podmiot cywilny czwartego rządu poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_5 oznacza podmiot cywilny piątego rzędu poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_6 oznacza podmiot cywilny szóstego rzędu poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_7 oznacza podmiot cywilny siódmego rzędu poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • colloquial_area wskazuje powszechnie używaną nazwę alternatywną elementu.
  • locality oznacza podmiot polityczny z własnym miastem lub miastem.
  • sublocality oznacza jednostkę cywilną pierwszego rzędu pod rejonem. W przypadku niektórych lokalizacji mogą pojawić się dodatkowe typy: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
  • neighborhood oznacza nazwany dzielnicę
  • premise wskazuje nazwane miejsce, zwykle jest to budynek lub zbiór budynków o takiej samej nazwie
  • subpremise oznacza element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle jest to pojedynczy budynek w zespole budynków o takiej samej nazwie
  • plus_code oznacza zakodowane odniesienie do lokalizacji na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastąpić adresy w miejscach, w których nie istnieją (gdzie budynki nie są numerowane lub nazwy ulic nie są nazwane). Szczegółowe informacje znajdziesz na stronie https://plus.codes.
  • postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
  • natural_feature oznacza ważny obiekt naturalny.
  • airport oznacza lotnisko.
  • park oznacza nazwany park.
  • point_of_interest wskazuje nazwane miejsce. Takie miejsca to zazwyczaj znane obiekty lokalne, które nie pasują do żadnej innej kategorii, takiej jak „Empire State Building” czy „Wieża Eiffla”.

Pusta lista typów oznacza, że nie są znane żadne typy określonego komponentu adresu, np. Lieu-dit we Francji.

Oprócz wymienionych powyżej składników adresu mogą występować typy opisane poniżej.

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 jest używane jako punkt odniesienia dla ułatwienia nawigacji.
  • point_of_interest wskazuje nazwane miejsce.
  • parking oznacza parking.
  • post_box oznacza konkretną skrzynkę pocztową.
  • postal_town oznacza grupę obszarów geograficznych, np. locality i sublocality, która jest używana w przypadku adresów pocztowych w niektórych krajach.
  • room wskazuje salę w danym budynku.
  • street_number wskazuje dokładny numer domu.
  • bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, pociągu lub transportu publicznego.

Kody stanu

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

  • "OK" oznacza, że nie wystąpiły błędy. Adres został przeanalizowany i zwrócono co najmniej 1 kod geograficzny.
  • "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 limit został przekroczony.
  • "REQUEST_DENIED" oznacza, że prośba została odrzucona. Strona internetowa nie może korzystać z geokodera.
  • "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 jeszcze raz, żądanie może zostać zrealizowane.
  • "ERROR" oznacza, że upłynął limit czasu żądania lub wystąpił problem z połączeniem z serwerami Google. Jeśli spróbujesz jeszcze raz, żądanie może zostać zrealizowane.

W tym przykładzie geokodujemy adres i umieszczamy znacznik na zwróconych wartościach szerokości i długości geograficznej. Moduł obsługi jest przekazywany jako literał funkcji anonimowego.

  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

Promowanie widocznego obszaru

Możesz poinstruować usługę Geocoding, aby preferowała wyniki w danym widocznym obszarze (wyrażonym jako ramka ograniczająca). Aby to zrobić, ustaw parametr bounds w literale obiektu GeocoderRequest, aby określić granice tego widocznego obszaru. Pamiętaj, że promowanie preferuje tylko wyniki znajdujące się w określonych granicach. Jeśli wykraczające poza te granice wyniki są preferowane, zostaną one uwzględnione.

Na przykład geokod dla hasła „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 określa ramkę ograniczającą Dolinę San Fernando w Los Angeles, geokod zwróci obszar 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"
}

Promowanie kodu regionu

Za pomocą parametru region można skonfigurować usługę Geocoding tak, aby zwracała wyniki stronnicze do określonego regionu. Ten parametr przyjmuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu 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” w przypadku Wielkiej Brytanii).

Gdy używasz parametru region:

  • Określ tylko jeden kraj lub region. Wiele wartości jest ignorowanych, co może doprowadzić do nieudanego żądania.
  • Używaj tylko dwuznakowych tagów podrzędnych regionów (w formacie Unicode CLDR). Wszystkie inne dane wejściowe spowodują błędy.
  • Obsługiwane są tylko kraje i regiony wymienione w informacjach o zasięgu Google Maps Platform.

Żądania geokodowania mogą być wysyłane dla każdej domeny, w której główna aplikacja Mapy 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 kod geograficzny dla „Toledo” zwraca taki wynik, ponieważ domyślna domena usługi Geocoding Service to 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"
}

Geokod 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

Za pomocą filtra komponentów możesz skonfigurować usługę Geocoding Service, aby zwracała wyniki adresów ograniczonych do konkretnego obszaru. 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 pasujące do wszystkich filtrów komponentów. Oznacza to, że ocenia specyfikacje filtra w postaci ORAZ, a nie LUB.

Filtr komponentów składa się z co najmniej jednego 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 odpowiada wszystkim poziomom regionu.
  • postalCode pasuje do kodów pocztowych i prefiksów kodów pocztowych.
  • Atrybut country odpowiada nazwie kraju lub dwuliterowym kodem kraju zgodnym z normą ISO 3166-1. Uwaga: interfejs API jest zgodny ze standardem ISO określającym kraje, a filtrowanie działa najlepiej, gdy używany jest odpowiedni kod ISO kraju.

Ten przykład pokazuje użycie parametru componentRestrictions do filtrowania według wartości 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 uszkodzona w status=ZERO_RESULTS. Jednak dodatkowe pola na poziomie odpowiedzi plus_code i address_descriptor mogą być w tym przypadku nadal wypełnione. 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 przedstawiono przykład takiego zachowania dla współrzędnych geograficznych Antarktydy. Mimo że nie ma żadnych wyników odwrotnego geokodowania, nadal możemy wydrukować kod plus, jeśli ustawisz 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ładowe geokodowanie w miejscach

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 są 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 żądanej współrzędnej, częstości występowania punktu orientacyjnego i jego widoczności. Każdy wynik dotyczący punktu orientacyjnego zawiera te wartości:

  • place_id to identyfikator miejsca w wynikach wyszukiwania punktów orientacyjnych. Zobacz omówienie identyfikatora miejsca.
  • display_name to wyświetlana nazwa punktu orientacyjnego, która zawiera language_code i text.
  • straight_line_distance_meters to odległość między punktami w metrach między podaną współrzędną a wynikami punktów orientacyjnych.
  • travel_distance_meters to odległość pokonana w metrach przez sieć dróg (z wyłączeniem ograniczeń drogowych) między wejściowymi współrzędnymi a wynikami punktów orientacyjnych.
  • spatial_relationship to szacowany związek między współrzędnymi wejściowymi a wynikami punktów orientacyjnych:
    • Gdy nie ma zastosowania żadna z poniższych sytuacji, relacją domyślną jest "NEAR".
    • "WITHIN", gdy współrzędna wejściowa znajduje się w granicach obiektu powiązanego z punktem orientacyjnym.
    • "BESIDE", jeśli współrzędna wejściowa przylega bezpośrednio do punktu dostępu do punktu orientacyjnego lub punktu dostępu.
    • "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ędne wejściowe znajdują się wzdłuż tej samej trasy co punkt orientacyjny, ale nie "BESIDES" ani "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER", gdy współrzędne wejściowe znajdują się wzdłuż prostopadłej trasy jako punktu orientacyjnego (tylko do jednego skrętu).
    • "BEHIND", gdy współrzędna wejściowa jest przestrzennie blisko punktu orientacyjnego, ale daleko od jego punktu dostępu.
  • types to typy miejsc punktu orientacyjnego.

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

  • place_id to identyfikator miejsca wskazanego w wynikach wyszukiwania obszarów. Zobacz omówienie identyfikatora miejsca.
  • display_name to wyświetlana nazwa obszaru. Zawiera ona language_code i text.
  • containment to szacunkowy stosunek izolacji między współrzędną wejściową a wynikiem obszaru:
    • Gdy nie ma zastosowania żadna z poniższych sytuacji, relacją domyślną jest "NEAR".
    • "WITHIN", gdy współrzędna wejściowa jest blisko ś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. Chętnie poznamy Twoją opinię. Wyślij do nas e-maila na adres address-descriptors-feedback@google.com.

Odwrotne geokodowanie (wyszukiwanie adresu)

Termin geokodowanie odnosi się ogólnie do tłumaczenia zrozumiałego dla człowieka adresu w lokalizację na mapie. Działanie odwrotne, czyli tłumaczenie lokalizacji na mapie na adres czytelny dla człowieka, jest nazywany odwrotnym geokodowaniem.

Zamiast podawać tekstowe address, w parametrze location podaj rozdzieloną przecinkami parę szerokości i długości geograficznej.

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:

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

Zobacz próbkę

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 to adresy geokodera. Odwrotny geokoder zwraca wszystkie te wyniki.

Odwrotny geokoder dopasowuje jednostki polityczne (kraje, prowincje, miasta i dzielnice), adresy i kody pocztowe.

Oto przykład listy adresów, które może zwrócić 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 zwykle bardziej dokładny adres. Pamiętaj, że zwracamy różne typy adresów – od najbardziej precyzyjnego adresu po bardziej konkretne jednostki polityczne, takie jak dzielnice, miasta, hrabstwa, województwa itp. Jeśli chcesz dopasować bardziej ogólny adres, przejrzyj pole results[].types.

Uwaga: odwrotne geokodowanie nie jest metodą ścisłą. Geokoder spróbuje znaleźć najbliższą zaadresowaną lokalizację z dokładnością do określonej tolerancji.

Pobieranie adresu dla 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ć placeId zwrócony przez Roads API, aby uzyskać adres przyciągniętego punktu. Więcej informacji o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatorów miejsc.

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

  • address
  • latLng
  • location
  • componentRestrictions

W poniższym przykładzie można zaakceptować identyfikator miejsca, znaleźć odpowiedni adres i wyśrodkować mapę na tej lokalizacji. Wyświetli się też okno informacyjne ze 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

Zobacz próbkę