Termin kodowanie geograficzne oznacza przekształcenie zrozumiałego dla człowieka adresu na lokalizację na mapie. Odwrotny proces, czyli tłumaczenie lokalizacji na mapie na adres zrozumiały dla człowieka, to odwrotne geokodowanie.
Odwrotne żądania geokodowania
Wymagane parametry
latlng
– współrzędne szerokości i długości geograficznej wskazujące lokalizację, dla której chcesz znaleźć najbliższy, zrozumiały 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żesz uwzględnić w żądaniu odwrotnego geokodowania:
language
– język, w którym mają być zwracane 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
language
nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówkuAccept-Language
lub języka ojczystego domeny, z której wysłane jest żądanie. - Geokoder dokłada wszelkich starań, aby podać czytelny adres zarówno dla użytkownika, jak i lokalnego. W tym celu funkcja zwraca adresy w języku lokalnym, transliterację do skryptu zrozumiałego dla użytkownika (w razie potrzeby) z uwzględnieniem preferowanego języka. Wszystkie inne 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 nie jest dostępna w preferowanym języku, geokoder użyje najbliższego dopasowania.
region
– kod regionu, podany jako dwuznakowa wartość domeny ccTLD („domena najwyższego poziomu”). Parametr może też wpływać na wyniki zgodnie z obowiązującym prawem.result_type
– filtr obejmujący co najmniej 1 typ adresu rozdzielony pionową kreską (|
). Jeśli parametr zawiera kilka typów adresów, interfejs API zwraca wszystkie adresy pasujące do dowolnego z nich. Uwaga na temat przetwarzania: parametrresult_type
restrict wyszukiwania do określonych typów adresów.result_type
działa raczej jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki związane z określonym parametremlatlng
, a potem odrzuca te, 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. „US 101”).intersection
to główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.political
oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt związany z administracją cywilną.country
wskazuje krajowy podmiot polityczny i zazwyczaj jest to najwyższy typ kolejności zwracany przez geokodera.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 admin_area_level_1 są ściśle dopasowane do podziałów według normy ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy jednak zagwarantować, że wyniki z kodowania geograficznego są uzależnione od różnych sygnałów 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 poziomu 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ą alternatywną nazwę encji.locality
oznacza miasto lub miejscowość, w której on działa.sublocality
wskazuje podmiot cywilny pierwszego rzędu poniżej danego rejonu. W przypadku niektórych lokalizacji może pojawić się 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
wskazuje element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle pojedynczy budynek w zbiorze budynków o wspólnej nazwieplus_code
to zakodowane odwołanie do lokalizacji pobrane na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastąpić adresy w miejscach, gdzie nie istnieją (gdzie budynki nie są numerowane lub nie mają nazw ulic). 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
oznacza ważny obiekt naturalny.airport
wskazuje lotnisko.park
wskazuje park nazwany.point_of_interest
wskazuje nazwane miejsce. Są to zwykle ważne lokalne jednostki, których nie da się łatwo umieścić w innych kategoriach, np. „Empire State Building” lub „wieża Eiffla”.
location_type
– filtr obejmujący co najmniej 1 typ lokalizacji rozdzielony pionową kreską (|
). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z nich. Uwaga na temat przetwarzania: parametrlocation_type
restrict wyszukiwania do określonych typów lokalizacji.location_type
działa raczej 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 są te wartości:- Funkcja
"ROOFTOP"
zwraca tylko te adresy, dla których Google ma informacje o lokalizacji z dokładnością do dokładnego adresu. "RANGE_INTERPOLATED"
zwraca tylko adresy zgodne z przybliżeniem (zwykle na drodze) z interpolacją między 2 precyzyjnymi punktami (np. skrzyżowaniami). Zakres interpolowany zazwyczaj oznacza, że geokody dachów nie są dostępne dla danego adresu.- Funkcja
"GEOMETRIC_CENTER"
zwraca tylko centra geometryczne lokalizacji, np. linię łamaną (na przykład ulicę) lub wielokąt (region). - Funkcja
"APPROXIMATE"
zwraca tylko adresy, które są opisane jako przybliżone.
- Funkcja
Jeśli obecne są zarówno filtry result_type
, jak i location_type
, interfejs API zwróci tylko wyniki, które pasują zarówno do wartości result_type
, jak i z wartości location_type
. Jeśli żadna z wartości filtrów nie jest akceptowana, interfejs API zwraca wartość 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
To 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 odwrotny geokoder zwrócił więcej niż jeden wynik. Wyniki wyszukiwania "formatted_address"
obejmują nie tylko adresy pocztowe, ale także wszelkie informacje o lokalizacji geograficznej. Na przykład podczas geokodowania punktu w mieście Chicago punkt geokodowany można oznaczyć jako adres, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są „adresami” dla geokodera. Odwrotny geokoder zwraca dowolny z tych typów jako prawidłowe wyniki.
Odwrotny geokoder dopasowuje jednostki 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 precyzyjnego adresu pocztowego do mniej szczegółowych podmiotów politycznych, takich jak dzielnice, miasta, hrabstwa i stany. W tym przypadku najbardziej widoczny jest zazwyczaj dokładny adres. Jeśli chcesz dopasować określony typ adresu, zapoznaj się z sekcją poniżej, w której opisano ograniczanie 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 filtruje zwrócone adresy, aby uwzględniały tylko te z typem lokalizacji ROOFTOP
i typem 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: tych filtrów można używać tylko przy odwrotnym geokodowaniu.
Odwrotne odpowiedzi geokodowania
Format odpowiedzi odwrotnej geokodowania jest taki sam jak odpowiedzi na polecenie geokodowania. Więcej informacji znajdziesz w sekcji Odpowiedzi geokodowania. Poniżej znajdziesz kody stanu możliwe w odpowiedzi na odwrotne geokodowanie.
Odwracanie kodów stanu geokodowania
Pole "status"
w obiekcie odpowiedzi Geocoding zawiera stan żądania i może zawierać informacje 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 że został zwrócony co najmniej 1 adres."ZERO_RESULTS"
oznacza, że odwrotne geokodowanie się udało, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał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"
oznacza zazwyczaj 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 się powieść.
Odwrócone kody Plus Code
Pole plus_code
w odpowiedzi na dane geokodowanie 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 z typem plus_code
i adresem zawierającym kod plus. Odległość między zdekodowanym kodem plus a punktem żądania musi być mniejsza niż 10 metrów.