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:
- Otwórz konsolę Google Cloud.
- Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Geocoding API.
- 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:
- U góry strony wybierz WŁĄCZ API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
- Wyszukaj Geocoding API, a następnie wybierz go z listy wyników.
- 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
– adresLatLng
(lubLatLngLiteral
), 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. Parametrbounds
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”). Parametrregion
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 toADDRESS_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” ishort_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 obiektLatLng
, 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 obiektLatLngBounds
, 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: odsublocality_level_1
dosublocality_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 nazwiesubpremise
oznacza element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle jest to pojedynczy budynek w zespole budynków o takiej samej nazwieplus_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
isublocality
, 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
itransit_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 elementuaddress
."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
lublatlng
)."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>
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 zawieralanguage_code
itext
.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 onalanguage_code
itext
.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;
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;
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;
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;