Żądanie
Żądanie do interfejsu Geocode API ma tę formę:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
gdzie outputFormat
może mieć jedną z tych wartości:
json
(zalecane) wskazuje dane wyjściowe w formacie JSON (JavaScript Object Notation),xml
wskazuje dane wyjściowe w formacie XML
W przypadku żądań korzystających z klucza interfejsu API wymagany jest protokół HTTPS.
Niektóre parametry są wymagane, a inne opcjonalne. Tak jak ma to miejsce w przypadku adresów URL, parametry są rozdzielone znakiem „&
”.
W pozostałej części strony omawiamy geokodowanie i odwrotne geokodowanie oddzielnie, ponieważ w przypadku każdego typu żądania dostępne są różne parametry.
Parametry geokodowania (wyszukiwanie szerokości i długości geograficznej)
Parametry wymagane w żądaniu geokodowania:
address
– adres pocztowy lub kod Plus Code, który chcesz zakodować geograficznie; Adresy należy podać zgodnie z formatem obowiązującym w danym kraju. Nie należy używać dodatkowych elementów adresu, takich jak nazwy firm i jednostki, lokale lub piętra. Elementy adresu ulicy powinny być rozdzielone spacjami (przedstawione w adresie URL jako%20
):address=24%20Sussex%20Drive%20Ottawa%20ON
Sformatuj kody plus, tak jak pokazano tutaj (znaki plus zamieniają url w%2B
, a spacje w adresy URL w%20
):- kod globalny to 4-znakowy numer kierunkowy i 6 lub więcej znaków lokalnych (849VCWC8 + R9 to
849VCWC8%2BR9
). - kod złożony to co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9 Mountain View, CA, USA to
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
– filtr komponentów z elementami oddzielonymi pionową kreską (|
). Jeśli podanoaddress
, filtr komponentów jest też opcjonalny. Każdy element w filtrze komponentów składa się z parycomponent:value
i całkowicie ogranicza wyniki z kodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.- kod globalny to 4-znakowy numer kierunkowy i 6 lub więcej znaków lokalnych (849VCWC8 + R9 to
key
– klucz interfejsu API aplikacji. Ten klucz określa Twoją aplikację na potrzeby zarządzania limitem. Dowiedz się, jak uzyskać klucz.
Dodatkowe wskazówki znajdziesz w Najczęstszych pytaniach.
Opcjonalne parametry w żądaniu geokodowania:
bounds
– ramka ograniczająca widoczny obszar, w którym odchylenie wyników geograficznych jest wyraźniejsze. Ten parametr będzie miał wpływ tylko na wyniki z geokodera, a nie na wszystkie. (Więcej informacji znajdziesz poniżej w sekcji Promowanie ze względu na widoczność).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ć wyczerpująca.
- Jeśli nie zostanie podany parametr
language
, geokoder spróbuje użyć preferowanego języka określonego w nagłówkuAccept-Language
lub języka natywnego domeny, z której zostało wysłane żądanie. - Geokoder stara się podać adres pocztowy, który będzie czytelny dla użytkowników i użytkowników lokalnych. Aby osiągnąć ten cel, funkcja ta zwraca adresy pocztowe w języku lokalnym, a w razie potrzeby transliterację do skryptu zrozumiałego dla użytkownika z uwzględnieniem preferowanego języka. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który został wybrany z pierwszego komponentu.
- Jeśli nazwa jest niedostępna w wybranym języku, geokoder używa najbliższego dopasowania.
- Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz kolejność ich zwracania. Geokoder interpretuje skróty w zależności od języka, np. skróty dla typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér są synonimami odpowiednio słowa „Street” i „kwadrat” po węgiersku.
region
– kod regionu podany jako ccTLD („domena najwyższego poziomu”). Ten parametr wpływa tylko na wyniki z geokodera, a nie jest w pełni ograniczony. Więcej informacji znajdziesz w sekcji Promowanie według regionu poniżej. Ten parametr może też wpływać na wyniki w zależności od obowiązującego prawa.components
– filtr komponentów z elementami oddzielonymi pionową kreską (|
). Jeśli żądanie nie zawiera polaaddress
, filtr komponentów jest wymagany. Każdy element w filtrze komponentów składa się z parycomponent:value
i całkowicie ogranicza wyniki z kodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
Odpowiedzi
Odpowiedzi geokodowania są zwracane w formacie określonym przez flagę output
w żądaniu adresu URL lub domyślnie w formacie JSON.
W tym przykładzie interfejs Geocoding API wysyła odpowiedź json
na zapytanie dotyczące identyfikatora miejsca „ChIJeRpOeF67j4AR9ydy_PIzPuM”. Identyfikator tego miejsca
to budynek znajdujący się pod adresem 1600 Amphitheatre Parkway, Mountain View, CA.
To żądanie pokazuje za pomocą flagi JSON output
:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
To żądanie przedstawia flagę XML output
:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Kliknij poniższe karty, aby zobaczyć przykładowe odpowiedzi w formacie JSON i XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "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" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4224428, "lng": -122.0842467 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4239627802915, "lng": -122.0829089197085 }, "southwest": { "lat": 37.4212648197085, "lng": -122.0856068802915 } } }, "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM", "plus_code": { "compound_code": "CWC8+X8 Mountain View, CA", "global_code": "849VCWC8+X8" }, "types": [ "street_address" ] } ], "status": "OK" }
Odpowiedź JSON zawiera 2 elementy główne:
- Żądanie
"status"
zawiera metadane dotyczące żądania. Więcej informacji znajdziesz poniżej w sekcji Kody stanu. "results"
zawiera tablicę z danymi adresowymi i geometrią.
Ogólnie w wynikach wyszukiwania adresów zwracana jest tylko jedna pozycja w tablicy "results"
, jednak w przypadku niejednoznacznych zapytań może być dostępnych kilka wyników.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Pamiętaj, że odpowiedź XML składa się z 1 elementu <GeocodeResponse>
i 2 elementów najwyższego poziomu:
- Żądanie
<status>
zawiera metadane dotyczące żądania. Więcej informacji znajdziesz poniżej w sekcji Kody stanu. - 0 lub więcej elementów
<result>
, z których każdy zawiera 1 zestaw informacji geograficznych i adresu geograficznego.
Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Z tego powodu zalecamy używanie flagi wyjściowej json
jako preferowanej, chyba że z jakiegoś powodu usługa wymaga xml
.
Dodatkowo przetwarzanie drzew XML wymaga zachowania ostrożności, aby można było odwoływać się do właściwych węzłów i elementów. Niektóre zalecane wzorce projektowe dla przetwarzania danych wyjściowych znajdziesz w
sekcji analizy pliku XML za pomocą XPath.
- Wyniki w formacie XML są umieszczone w głównym elemencie
<GeocodeResponse>
. - JSON oznacza wpisy z wieloma elementami według liczby mnogiej (
types
), a kod XML – z użyciem wielu pojedynczych elementów (<type>
). - Puste elementy są wskazane w postaci pustych tablic w formacie JSON, ale bez żadnych takich elementów w pliku XML. Odpowiedź, która nie generuje żadnych wyników, zwraca w formacie JSON pustą tablicę
results
, ale nie zawiera np. żadnych elementów<result>
.
Kody stanu
Pole "status"
w obiekcie odpowiedzi Geocode zawiera stan żądania i może zawierać dane debugowania, które pomogą Ci ustalić, dlaczego geokodowanie nie działa. Pole "status"
może zawierać te wartości:
"OK"
oznacza, że nie wystąpiły żadne błędy. Adres został przeanalizowany, a przynajmniej 1 kod geograficzny został zwrócony."ZERO_RESULTS"
wskazuje, że udało się przetworzyć dane geograficzne, ale nie znaleziono żadnych wyników. Może tak się zdarzyć, jeśli koder został przekazany jako nieistniejącyaddress
.OVER_DAILY_LIMIT
wskazuje dowolną z tych wartości:- Brak klucza interfejsu API lub jest on nieprawidłowy.
- Płatności nie zostały włączone na Twoim koncie.
- Samodzielnie ustawiony limit wykorzystania.
- Podana forma płatności jest już nieważna (np. karta kredytowa straciła ważność).
Aby dowiedzieć się, jak rozwiązać ten problem, zapoznaj się z najczęstszymi pytaniami dotyczącymi Map Google.
"OVER_QUERY_LIMIT"
oznacza, że został przekroczony limit."REQUEST_DENIED"
oznacza, że Twoja prośba została odrzucona."INVALID_REQUEST"
zwykle wskazuje, że brakuje zapytania (address
,components
lublatlng
)."UNKNOWN_ERROR"
oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Prośba może się udać, jeśli spróbujesz ponownie.
Komunikaty o błędach
Gdy geokoder zwraca kod stanu inny niż OK
, w obiekcie odpowiedzi Geocoding może pojawić się dodatkowe pole error_message
. To pole zawiera bardziej szczegółowe informacje o przyczynach danego kodu stanu.
Wyniki
Gdy geokoder zwraca wyniki, umieszcza je w tablicy results
(JSON). Nawet jeśli geokoder nie zwraca żadnych wyników (na przykład nie istnieje adres), wciąż zwraca pustą tablicę results
. (odpowiedzi XML składają się z zera lub większej liczby elementów <result>
).
Typowy wynik zawiera następujące pola:
- Tablica
types[]
wskazuje typ zwróconego wyniku. Tablica zawiera zero lub więcej tagów określających typ cechy zwróconego w wyniku. Na przykład mapa geograficzna słowa „Chicago” zwraca nazwę „locality”, która wskazuje, że „Chicago” jest miastem, a „polityczna” wskazuje, że jest to podmiot polityczny. Komponenty mogą zawierać tablicę pustych typów, jeśli dla danego adresu nie są znane żadne typy. Interfejs API może w razie potrzeby dodawać nowe wartości typu. Więcej informacji znajdziesz w artykule Typy i komponenty adresów. formatted_address
to ciąg znaków zawierający adres tej lokalizacji czytelny dla człowieka.Często jest to odpowiednik 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ę z co najmniej jednego komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z następujących elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).
Nie analizuj automatycznie sformatowanego adresu. Zamiast nich należy używać poszczególnych komponentów adresu, które oprócz odpowiedzi na pole formatowania zawierają odpowiedź interfejsu API.
address_components[]
to tablica zawierająca osobne komponenty mające zastosowanie do tego adresu.Każdy komponent adresu zawiera zazwyczaj następujące pola:
types[]
to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.long_name
to pełny opis lub nazwa komponentu adresu zwracana przez geokoder.short_name
to skrócona nazwa tekstowa komponentu adresu (jeśli jest dostępna). Na przykład komponent adresu w stanie Alaska może zawierać wartościlong_name
„Alaska” ishort_name
„AK” korzystające z dwuliterowego skrótu kodu pocztowego.
Zapamiętaj te fakty na temat tablicy
address_components[]
:- Tablica komponentów adresu może zawierać więcej komponentów niż element
formatted_address
. - Tablica nie musi obejmować wszystkich jednostek politycznych zawierających adres oprócz tych uwzględnionych w polu
formatted_address
. Aby pobrać wszystkie elementy polityczne zawierające konkretny adres, użyj odwrotnego geokodowania. W tym żądaniu podaj szerokość i długość geograficzną adresu. - Format odpowiedzi nie może być taki sam między żądaniami. W szczególności liczba obiektów
address_components
różni się w zależności od żądanego adresu i może się zmienić z upływem czasu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować konkretnego komponentu.
Aby obsługiwać tablicę komponentów, należy przeanalizować odpowiedź i wybrać odpowiednie wartości za pomocą wyrażeń. Zapoznaj się z przewodnikiem po analizie odpowiedzi.
postcode_localities[]
to tablica wskazująca wszystkie rejony zawarte w kodzie pocztowym. Ten wynik występuje tylko wtedy, gdy wynik jest kodem pocztowym zawierającym wiele lokalizacji.geometry
zawiera te informacje:location
zawiera geograficzną szerokość i długość geograficzną. W przypadku zwykłych wyszukiwań adresów to pole jest zwykle najważniejsze.location_type
przechowuje dodatkowe dane na temat określonej lokalizacji. Obecnie obsługiwane są te wartości:"ROOFTOP"
wskazuje, że zwrócony wynik to dokładny geokod, w przypadku którego informacje o lokalizacji są dokładne, nawet z dokładnością do adresu ulicy."RANGE_INTERPOLATED"
wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolowane między 2 punktami dokładnymi (na przykład skrzyżowania). Interpolowane wyniki są zwykle zwracane, gdy dane geograficzne z dachu nie są dostępne dla adresu ulicy."GEOMETRIC_CENTER"
wskazuje, że zwrócony wynik jest geometrycznym środkiem wyniku, takim jak linia łamana (np. ulica) lub wielokąt (region)."APPROXIMATE"
oznacza, że zwrócony wynik jest przybliżony.
viewport
zawiera zalecany obszar wyświetlania zwracanego wyniku, zdefiniowany jako 2 wartości szerokości i długości geograficznej,które określają górny róg polasouthwest
inortheast
. Zasadniczo widoczny obszar jest używany do kadrowania wyniku podczas wyświetlania go użytkownikowi.bounds
(opcjonalnie) jest przeznaczony do przechowywania ramki ograniczającej, która może zawierać pełny wynik. Te granice mogą nie być zgodne z zalecanym widocznym obszarem. Na przykład San Francisco obejmuje wyspy Fallona, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być zwracane w widocznym obszarze.
-
plus_code
(patrz Otwórz kod lokalizacji i kody Plus Code) to zakodowane odniesienie do lokalizacji określone na podstawie współrzędnych szerokości i długości geograficznej, reprezentujące obszar: 1/8000 stopnia w 1/8000. stopnia (14 x 14 m w równaniu) lub mniejszego. Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie ma adresów (gdy budynki nie są numerowane lub nie mają nazw ulic). Interfejs API nie zawsze zwraca kody plus.Gdy usługa zwraca kod plus, jest on sformatowany jako kod globalny i kod złożony:
global_code
to 4-cyfrowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).compound_code
to co najmniej 6-znakowy kod lokalny z jednoznaczną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tej treści programowo.
-
Parametr
partial_match
wskazuje, że geokoder nie zwracał dokładnego dopasowania do pierwotnego żądania, chociaż mógł go dopasować do części żądanego adresu. Możesz sprawdzić pierwotną prośbę o weryfikację i niepoprawny adres.Częściowo pasujące są najczęściej adresy, które nie istnieją w regionie podanym w żądaniu. Częściowe dopasowania mogą się też pojawić, gdy żądanie pasuje do co najmniej dwóch lokalizacji w tym samym regionie. Na przykład wyszukiwanie „Hillpar St, Bristol, Wielka Brytania” zwróci częściowo dopasowania do ulicy Henry Street i ulicy Henrietta. Pamiętaj, że jeśli żądanie zawiera błędnie wpisany komponent adresu, usługa geokodowania może zaproponować inny adres. Sugestie aktywowane w ten sposób również będą oznaczane jako częściowe dopasowanie.
place_id
to unikalny identyfikator, którego można używać z innymi interfejsami API Google. Możesz na przykład użyćplace_id
w żądaniu Places API, aby uzyskać szczegółowe informacje o lokalnej firmie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników i inne. Zapoznaj się z omówieniem identyfikatora miejsca.
Typy adresów i typy komponentów adresów
Tablica types[]
w wyniku wskazuje typ adresu. Przykładowe typy adresów to adresy, kraje lub podmioty polityczne. address_components[]
zawiera też tablicę types[]
, która wskazuje typ każdej części adresu. Może to być na przykład numer domu lub kraj. (poniżej znajdziesz pełną listę typów). Adresy mogą mieć wiele typów. Typy mogą być uznawane za „tagi”.
Na przykład wiele miast jest oznaczonych za pomocą typu political
i locality
.
Te typy są obsługiwane i zwracane przez geokoder zarówno w tablicach typów adresów, jak i ich typach:
street_address
wskazuje dokładny adres.route
oznacza nazwą trasę (np. „PL 101”).intersection
wskazuje główne skrzyżowanie, złożone zwykle z 2 głównych dróg.political
oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt administracji cywilnej.country
wskazuje krajową instytucję polityczną i jest zwykle najwyższym typem zamówienia zwracanym przez geokoder.administrative_area_level_1
wskazuje na pierwszy poziom jednostki cywilnej niższy niż kraj. W Stanach Zjednoczonych są to stany administracyjne. Nie wszystkie kraje mają ten poziom administracyjny. W większości przypadków krótkie nazwy administracyjne_area_level_1 są bardzo zbliżone do podziałów ISO 3166-2 i innych szeroko rozpowszechnianych list. Nie gwarantujemy jednak, że wyniki geokodowania będą oparte na różnych sygnałach i danych o lokalizacji.administrative_area_level_2
wskazuje na kolejne kraje poziom cywilny drugiego rzędu. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje mają ten poziom administracyjny.administrative_area_level_3
wskazuje podmiot cywilny trzeciego poziomu poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.administrative_area_level_4
wskazuje na 4. porządek cywilny poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.administrative_area_level_5
wskazuje jednostkę cywilną o piątej kolejności poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.administrative_area_level_6
wskazuje na poziomie kraju szósty podmiot cywilny. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.administrative_area_level_7
wskazuje podmiot cywilny 7 poziomu poniżej kraju. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.colloquial_area
wskazuje powszechnie używaną alternatywną nazwę elementu.locality
wskazuje spółkę państwową, która jest częścią miasta.sublocality
oznacza podmiot cywilny pierwszego stopnia znajdujący się niżej w okolicy. W przypadku niektórych lokalizacji może pojawić się dodatkowy typ: odsublocality_level_1
dosublocality_level_5
. Każdy poziom podrejonu to podmiot cywilny. Większe liczby oznaczają mniejszy obszar geograficzny.neighborhood
wskazuje na nazwaną dzielnicępremise
wskazuje nazwane miejsce, zwykle budynek lub zbiór budynków o wspólnej nazwiesubpremise
wskazuje encję pierwszego stopnia poniżej nazwanej lokalizacji. Zazwyczaj jest to pojedynczy budynek w kolekcji budynków o takiej samej nazwie.plus_code
wskazuje zakodowane odwołanie do lokalizacji pobrane na podstawie szerokości i długości geograficznej. Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie istnieją (gdy budynki nie są numerowane lub nie mają nazw ulic). Szczegółowe informacje znajdziesz na https://plus.codes.postal_code
to kod pocztowy, który jest używany do obsługi poczty w danym kraju.natural_feature
wskazuje charakterystyczną cechę naturalną.airport
oznacza lotnisko.park
wskazuje nazwany park.point_of_interest
wskazuje na wybrane miejsce. Są to zwykle ważne lokalne obiekty, które nie pasują do żadnej kategorii, np. „Empire State Building” lub „Eiffel Tower”.
Pusta lista typów oznacza, że nie ma znanych typów poszczególnych komponentów adresu, np. Lieu-dit we Francji.
Oprócz wymienionych powyżej komponentów adresowych mogą obejmować podane tutaj typy. Ta lista nie jest pełna i może ulec zmianie.
floor
– piętro adresu budynku.establishment
zwykle oznacza miejsce, które nie zostało jeszcze sklasyfikowane.landmark
wskazuje miejsce w pobliżu używane jako odniesienie, które ułatwia nawigację.point_of_interest
wskazuje na wybrane miejsce.parking
wskazuje parking.post_box
oznacza konkretną skrzynkę pocztową.postal_town
oznacza grupę obszarów geograficznych, takich jaklocality
isublocality
, używane do określania adresów pocztowych w niektórych krajach.room
oznacza salę z budynkiem.street_number
wskazuje dokładny numer domu.bus_station
,train_station
itransit_station
wskazują lokalizację przystanku autobusowego, pociągowego lub publicznego.
Promowanie zakresu danych
W żądaniu geokodowania możesz poinstruować usługę geokodowania, aby preferowała wyniki z danego obszaru roboczego (wyrażonego jako ramka ograniczająca). Aby to zrobić, w adresie URL żądania ustaw parametr bounds
.
Parametr bounds
definiuje szerokość i długość geograficzną południowo-wschodniego i północnego wschodu ramki ograniczającej, rozdzielając je pionową kreską (|
).
Na przykład kod geograficzny „Washington” zwykle zwraca stan USA „Washington”:
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Dodanie argumentu bounds
określającego ramkę ograniczającą wokół północno-wschodniej części Stanów Zjednoczonych powoduje, że kod geograficzny zwraca miasto Waszyngton w stanie D.C.:
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Promowanie regionu
W żądaniu Geocode możesz poinstruować usługę Geocode, aby zwracała wyniki odchylenia do określonego regionu za pomocą parametru region
. Ten parametr przyjmuje argument ccTLD (domena krajowa najwyższego poziomu) określającą odchylenie regionu. Większość kodów ccTLD jest taka sama jak kody ISO 3166-1, ale istnieją pewne wyjątki. Na przykład krajowa domena ccTLD Wielkiej Brytanii to „uk” (.co.uk
), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).
Wyniki geokodowania mogą być podawane w przypadku każdej domeny, w której oficjalnie wdrażana jest główna aplikacja Map Google. Promowanie wyników preferowanych tylko dla określonej domeny. Można dodać bardziej trafne wyniki spoza tej domeny.
Na przykład kod geograficzny „Toledo” zwraca ten wynik, ponieważ domyślną lokalizacją interfejsu Geocoding API jest Stany Zjednoczone. Prośba:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Żądanie geokodu dla „Toledo” dla region=es
(Hiszpania) zwróci hiszpańskie miasto.
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"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" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtrowanie komponentów
W odpowiedzi geokodowania interfejs Geocoding API może zwracać wyniki dotyczące adresów ograniczone do określonego obszaru. Ograniczenie możesz określić za pomocą filtra components
. Filtr składa się z listy par component:value
rozdzielonych pionową kreską (|
). Wartości filtrów obsługują te same metody poprawiania pisowni i dopasowywania częściowego co inne żądania Geocode. Jeśli geokoder znajdzie częściowe dopasowanie dla filtra komponentów, odpowiedź będzie zawierać pole partial_match
.
components
, które można filtrować, to:
postal_code
pasuje dopostal_code
ipostal_code_prefix
.country
jest zgodny z nazwą kraju lub dwuliterowym kodem kraju ISO 3166-1. Interfejs API jest zgodny ze standardem ISO definiującym kraje, a filtrowanie działa najlepiej, gdy używasz odpowiadającego mu kodu ISO.
components
może mieć wpływ na wyniki, ale nie będzie egzekwowana:
route
pasuje do długiej lub krótkiej nazwy trasy.locality
pasuje do typówlocality
isublocality
.administrative_area
pasuje do wszystkich poziomówadministrative_area
.
Uwagi dotyczące filtrowania komponentów:
- Nie powtarzaj tych filtrów w żądaniach, ponieważ interfejs API zwróci
Invalid_request
:country
,postal_code
,route
- Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API ocenia te filtry jako operator ORAZ, a nie LUB.
- Wyniki są spójne z Mapami Google, które czasami zwracają nieoczekiwane odpowiedzi
ZERO_RESULTS
. Korzystanie z autouzupełniania miejsc może w niektórych przypadkach przynieść lepsze wyniki. Więcej informacji znajdziesz w najczęstszych pytaniach. - W przypadku każdego komponentu adresu określ go w parametrze
address
lub w filtrzecomponents
, ale nie w obu naraz. Podanie tych samych wartości w obu przypadkach może spowodować ustawienieZERO_RESULTS
.
Geokod dla „High St, Hastings” z components=country:GB
zwraca wynik w Hastings w Anglii, a nie w Hastings-On-Hudson, USA.
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Żądanie geokodu dla miejscowości „Santa Cruz” z adresem components=country:ES
zwraca Santa Cruz de Tenerife na Wyspy Kanaryjskie w Hiszpanii.
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtrowanie komponentów zwraca odpowiedź ZERO_RESULTS
tylko wtedy, gdy podasz filtry, które wzajemnie się wykluczają.
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Filtr components
pozwala tworzyć prawidłowe zapytania bez parametru adresu. (W przypadku geokodowania pełnego adresu parametr address
jest wymagany, jeśli żądanie zawiera nazwy i liczby budynków).
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}