Termin geokodowanie zwykle oznacza tłumaczenie adresu zrozumiałego dla człowieka na lokalizację na mapie. Odwrotny proces, czyli tłumaczenie lokalizacji z mapy na zrozumiały dla człowieka adres, to odwrotne geokodowanie.
Żądania odwrotnego geokodowania
Wymagane parametry
latlng
– współrzędne szerokości i długości geograficznej określające lokalizację, w której przypadku chcesz znaleźć najbliższy, czytelny dla człowieka adres.key
– klucz interfejsu API aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.
Parametry opcjonalne
Oto opcjonalne parametry, które można uwzględnić w żądaniu odwrotnego geokodowania:
language
– język, w którym wyświetlane są wyniki.- Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być pełna.
- Jeśli nie zostanie podany
language
, geokoder spróbuje użyć preferowanego języka określonego w nagłówkuAccept-Language
lub języka ojczystego domeny, z której wysyłane jest żądanie. - Geokoder dokłada wszelkich starań, aby podać czytelny adres zarówno dla użytkownika, jak i lokalnego. W tym celu zwraca adresy w języku lokalnym, transliterację na skrypt w razie potrzeby zrozumiały dla użytkownika i zachowując preferowany język. Pozostałe adresy są zwracane w preferowanym języku. Komponenty adresu są zwracane w tym samym języku, który jest wybierany z pierwszego komponentu.
- Jeśli nazwa jest niedostępna w preferowanym języku, geokoder użyje najbliższego odpowiednika.
region
– kod regionu, podany jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Parametr może też wpływać na wyniki na podstawie obowiązującego prawa.result_type
– filtr obejmujący co najmniej 1 typ adresu rozdzielone pionową kreską (|
). Jeśli parametr zawiera kilka typów adresów, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga na temat przetwarzania: parametrresult_type
nie restrict wyszukiwania do określonych typów adresów.result_type
działa raczej jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego elementulatlng
, a potem odrzuca wyniki, które nie pasują do określonych typów adresów. Obsługiwane są te wartości:street_address
wskazuje dokładny adres.route
wskazuje nazwaną trasę (np. „E701”).intersection
oznacza główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.political
oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt związany z administracją cywilną.country
oznacza krajowy podmiot polityczny i zwykle jest najwyższym typem porządku zwracanym przez Geocoder.administrative_area_level_1
oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są stanami. Nie we wszystkich krajach obowiązują te poziomy administracyjne. W większości przypadków krótkie nazwy są zbliżone do nazw z normą ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy tego jednak zagwarantować, 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 są hrabstwami. 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 niewielki podział cywilny. 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 niewielki podział cywilny. 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 niewielki podział cywilny. 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 niewielki podział cywilny. 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 niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.colloquial_area
wskazuje często używaną nazwę alternatywną jednostki.locality
oznacza miejskie podmioty polityczne.sublocality
wskazuje podmiot cywilny pierwszego rzędu poniżej rejonu. W przypadku niektórych lokalizacji może zostać wyświetlony jeden z dodatkowych typów: odsublocality_level_1
dosublocality_level_5
. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.neighborhood
wskazuje nazwę okolicypremise
oznacza nazwaną lokalizację, zwykle budynek lub zespół budynków o wspólnej nazwiesubpremise
oznacza element pierwszego rzędu pod nazwaną lokalizacją, zwykle pojedynczy budynek należący do zespołu budynków o wspólnej nazwieplus_code
oznacza zakodowane odniesienie do lokalizacji na podstawie szerokości i długości geograficznej. Kody plus mogą zastąpić adresy ulic w miejscach, w których one nie istnieją (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.postal_code
wskazuje kod pocztowy używany w danym kraju do adresowania przesyłek pocztowych.natural_feature
wskazuje ważny obiekt naturalny.airport
oznacza lotnisko.park
wskazuje park nazwany.point_of_interest
wskazuje nazwane miejsce. Takie ważne miejsca to zwykle doskonałe lokalne jednostki, których nie da się łatwo przypisać do innych kategorii, takich jak „Empire State Building” czy „wieża Eiffla”.
location_type
– filtr obejmujący co najmniej 1 typ lokalizacji rozdzielonych pionową kreską (|
). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga na temat przetwarzania: parametrlocation_type
restrict wyszukiwania do określonych typów lokalizacji. Zamiast tegolocation_type
działa jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego elementulatlng
, a potem odrzuca te, które nie pasują do określonych typów lokalizacji. Obsługiwane wartości:"ROOFTOP"
zwraca tylko te adresy, w przypadku których Google dysponuje informacjami o lokalizacji z dokładną dokładnością do adresu."RANGE_INTERPOLATED"
zwraca tylko adresy, które odzwierciedlają przybliżenie (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowaniami). Zakres interpolowany zazwyczaj oznacza, że geokody dachów na dachach są niedostępne w przypadku adresów."GEOMETRIC_CENTER"
zwraca tylko centra geometryczne lokalizacji, takie jak linia łamana (np. ulica) lub wielokąt (region)."APPROXIMATE"
zwraca tylko adresy sklasyfikowane jako przybliżone.
Jeśli obecne są zarówno filtry result_type
, jak i location_type
, interfejs API zwróci tylko te wyniki, które pasują zarówno do wartości result_type
, jak i z wartości location_type
. Jeśli żadna z wartości filtra nie jest akceptowalna, interfejs API zwraca ZERO_RESULTS
.
Przykład odwrotnego geokodowania
To zapytanie zawiera wartość szerokości i długości geograficznej lokalizacji na Brooklynie:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
Powyższe zapytanie zwraca taki wynik:
{
"results" : [
{
"address_components" : [
{
"long_name" : "277",
"short_name" : "277",
"types" : [ "street_number" ]
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
"types" : [ "route" ]
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "New York",
"short_name" : "NY",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "11211",
"short_name" : "11211",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
"types" : [ "street_address" ]
},
... Additional <code>results[]</code> ...
Pamiętaj, że zwrotny geokoder zwrócił więcej niż jeden wynik. Wyniki wyszukiwania "formatted_address"
nie obejmują tylko adresów pocztowych, ale także sposobu na określenie lokalizacji geograficznej. Na przykład podczas geokodowania punktu w Chicago punkt geokodowany można oznaczyć jako ulicę, adres, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie dane są „adresami” dla geokodera. Odwrotny geokoder zwraca każdy z tych typów jako prawidłowe wyniki.
Odwrotny geokoder dopasowuje podmioty polityczne (kraje, prowincje, miasta i dzielnice), adresy i kody pocztowe.
Poniżej znajdziesz pełną listę wartości formatted_address
zwróconych przez poprzednie zapytanie.
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
Ten interfejs API zwraca różne typy adresów – od najbardziej szczegółowych adresów pocztowych po mniej szczegółowe podmioty polityczne, takie jak dzielnice, miasta, hrabstwa i stany. Bardziej dokładny adres jest zwykle najbardziej widocznym wynikiem, jak w tym przypadku. Jeśli chcesz dopasować wyniki do konkretnego typu adresu, zapoznaj się z sekcją poniżej o ograniczaniu wyników według typu. Z tego powodu położenie wyników może się różnić.
Odwrotne geokodowanie odfiltrowane według typu
Poniższy przykład pokazuje filtrowanie zwróconych adresów, tak aby uwzględniały tylko adresy o typie lokalizacji ROOFTOP
i typie adresu street_address
.
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY
Uwaga: te filtry można stosować tylko do odwrotnego geokodowania.
Odpowiedzi na odwrotne geokodowanie
Format odpowiedzi wykorzystującej odwrotne geokodowanie jest taki sam jak odpowiedzi geokodowania. Zobacz odpowiedzi na geokodowanie. Poniżej znajdziesz kody stanu możliwe w odpowiedzi na odwrotne geokodowanie.
Odwrotne kody stanu geokodowania
Pole "status"
w obiekcie odpowiedzi Geocoding zawiera stan żądania i może zawierać informacje na potrzeby debugowania, które pomogą Ci ustalić, dlaczego odwrotne geokodowanie nie działa. Pole "status"
może zawierać te wartości:
"OK"
oznacza, że nie wystąpiły żadne błędy i został zwrócony co najmniej 1 adres."ZERO_RESULTS"
oznacza, że odwrotne geokodowanie zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder przekazałlatlng
w lokalizacji zdalnej."OVER_QUERY_LIMIT"
oznacza, że przekraczasz limit."REQUEST_DENIED"
oznacza, że żądanie zostało odrzucone. Prawdopodobnie żądanie zawiera parametrresult_type
lublocation_type
, ale nie zawiera klucza interfejsu API."INVALID_REQUEST"
zazwyczaj oznacza jedną z tych wartości:- Brak zapytania (
address
,components
lublatlng
). - Podano nieprawidłową wartość
result_type
lublocation_type
.
- Brak zapytania (
"UNKNOWN_ERROR"
oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może zostać zrealizowane.
Odwrotne geokodowanie Plus Code
Pole plus_code
w odpowiedzi na żądanie geokodowania zawiera kod plus, który najlepiej określa szerokość i długość geograficzną zapytania.
Dodatkowo tablica wyników JSON w większości przypadków zawiera pełny wynik geokodowania typu plus_code
i adres zawierający kod plus. Gwarantowana jest, że odległość między zdekodowanym kodem plus a punktem żądania nie przekracza 10 metrów.