Prośba
Żądanie do interfejsu Geocoding API ma następującą postać:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
gdzie outputFormat
może być jedną z tych wartości:
json
(zalecane) wskazuje dane wyjściowe w formacie JSON (JavaScript Object Notation); lubxml
oznacza dane wyjściowe w formacie XML
Wymagany jest protokół HTTPS.
Niektóre parametry są wymagane, a inne opcjonalne. Standardowo w adresach URL parametry są oddzielane znakiem „&
”.
W dalszej części tej strony oddzielnie opisujemy geokodowanie i odwrotne geokodowanie, ponieważ dla poszczególnych typów żądań dostępne są różne parametry.
Parametry geokodowania (wyszukiwanie szerokości i długości geograficznej)
Parametry wymagane w żądaniu geokodowania:
address
– adres lub kod plus, którego dane geograficzne chcesz przetworzyć na dane geograficzne. Podaj adresy w formacie używanym przez krajowy urząd pocztowy w danym kraju. Należy unikać dodatkowych elementów adresowych, takich jak nazwy firm, numer lokalu, lokalu lub piętra. Elementy adresu pocztowego powinny być rozdzielone spacjami (w tym przykładzie ze zmianą znaczenia w adresie URL w kodzie%20
):address=24%20Sussex%20Drive%20Ottawa%20ON
Sformatuj kod plus w podany niżej sposób (znaki plus będą zawierały kod zmiany znaczenia w adresie URL, a spacje zawierają kod%20
ze znakami zmiany znaczenia w adresie URL):- kod globalny to 4-znakowy kod kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9 to
849VCWC8%2BR9
). - złożony kod to co najmniej 6-znakowy kod lokalny z konkretną lokalizacją (CWC8+R9 Mountain View, CA, USA to
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
%2B
--OR--
components
– filtr komponentów z elementami oddzielonymi pionową kreską (|
). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podaszaddress
. Każdy element w filtrze komponentów składa się z parycomponent:value
i całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.- kod globalny to 4-znakowy kod kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9 to
key
– klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.
Dodatkowe wskazówki znajdziesz w najczęstszych pytaniach.
Opcjonalne parametry w żądaniu Geocoding:
bounds
– ramka ograniczająca widocznego obszaru, w ramach której odchylane są wyniki geolokalizacji. Ten parametr będzie miał wpływ tylko na wyniki generowane przez geokoder, ale nie będzie go w pełni ograniczać. (Więcej informacji znajdziesz w sekcji Promowanie widocznego obszaru poniżej).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
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 zostanie wysłane żądanie. - Geokoder stara się podać adres czytelny dla użytkowników i lokalnych osób. Aby osiągnąć ten cel, zwraca adresy w języku lokalnym, transliterację na skrypt, który w razie potrzeby może odczytać użytkownik, z zachowaniem preferowanego języka. Pozostałe adresy są zwracane w preferowanym języku. Wszystkie 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.
- Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz na kolejność, w jakiej są one zwracane. Geokoder różnie interpretuje skróty w zależności od języka. Mogą to być np. skróty określające typy ulic lub synonimy, które mogą być prawidłowe w jednym języku, a w innym nie. Na przykład utca i tér to synonimy ulicy i kwadratu w języku węgierskim.
region
– kod regionu określony jako dwuznakowa wartość domeny ccTLD („domeny najwyższego poziomu”). Ten parametr będzie miał wpływ tylko na wyniki generowane przez geokoder, ale nie będzie go w pełni ograniczać. (Więcej informacji znajdziesz w sekcji Promowanie według regionu poniżej). Ten parametr może też wpływać na wyniki na podstawie obowiązujących przepisów.components
– filtr komponentów, w którym elementy są oddzielone pionową kreską (|
). Filtr komponentów jest wymagany, jeśli żądanie nie zawieraaddress
. Każdy element w filtrze komponentów składa się z parycomponent:value
i całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.extra_computations
– jedyna dozwolona wartość w przypadku tego parametru toADDRESS_DESCRIPTORS
. Więcej informacji znajdziesz w artykule o deskryptorach adresów.
Odpowiedzi
Odpowiedzi geokodowania są zwracane w formacie wskazanym przez flagę output
w żądaniu adresu URL lub domyślnie w formacie JSON.
W tym przykładzie interfejs Geocoding API żąda odpowiedzi json
na zapytanie na adres „1600 Amphitheatre Parkway, Mountain View, CA”.
To żądanie demonstruje użycie flagi output
JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
To żądanie demonstruje użycie flagi output
XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Kliknij karty poniżej, aby zobaczyć przykładowe odpowiedzi 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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Pamiętaj, że odpowiedź JSON zawiera 2 elementy główne:
"status"
zawiera metadane dotyczące tego żądania. Zobacz Kody stanu poniżej."results"
zawiera tablicę danych geometrycznych i danych adresowych.
Zwykle przy wyszukiwaniu adresu zwracany jest tylko jeden wpis w tablicy "results"
, jednak geokoder może zwrócić kilka wyników, gdy zapytania adresowe są niejednoznaczne.
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 jednego elementu <GeocodeResponse>
i 2 elementów najwyższego poziomu:
<status>
zawiera metadane dotyczące tego żądania. Patrz Kody stanu poniżej.- Nie więcej niż 0 elementów
<result>
, z których każdy zawiera jeden zestaw danych adresowych i geometrycznych z kodami geograficznymi.
Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Z tego powodu zalecamy używanie json
jako preferowanej flagi danych wyjściowych, chyba że usługa z jakiegoś powodu wymaga xml
.
Dodatkowo przetwarzanie drzew XML wymaga należytej staranności, ponieważ należy odwoływać się do odpowiednich węzłów i elementów. Zalecane wzorce projektowe do przetwarzania danych wyjściowych znajdziesz w opisie
analizowania kodu XML za pomocą ścieżki XPath.
- Wyniki XML są zawarte w elemencie głównym
<GeocodeResponse>
. - JSON oznacza wpisy z wieloma elementami w formie liczby mnogiej (
types
), natomiast XML oznacza je, używając wielu pojedynczych elementów (<type>
). - Puste elementy są wskazywane przez puste tablice w formacie JSON, ale brak takiego elementu w pliku XML. Odpowiedź, która nie generuje wyników, zwraca pustą tablicę
results
w pliku JSON, ale nie zwraca żadnych elementów<result>
w kodzie XML.
Kody stanu
Pole "status"
w obiekcie odpowiedzi Geocoding zawiera stan żądania i może zawierać informacje na potrzeby 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 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_DAILY_LIMIT
oznacza dowolne z tych wartości:- Brak klucza interfejsu API lub jest on nieprawidłowy.
- Płatności nie zostały włączone na Twoim koncie.
- Przekroczono nałożony samodzielnie limit wykorzystania.
- Podana forma płatności straciła ważność (na przykład wygasła karta kredytowa).
Zapoznaj się z najczęstszymi pytaniami dotyczącymi Map, aby dowiedzieć się, jak rozwiązać ten problem.
"OVER_QUERY_LIMIT"
oznacza, że limit został przekroczony."REQUEST_DENIED"
oznacza, że prośba została odrzucona."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.
Komunikaty o błędach
Gdy geokoder zwróci kod stanu inny niż OK
, w obiekcie odpowiedzi Geocoding może zawierać dodatkowe pole error_message
. To pole zawiera bardziej szczegółowe informacje o przyczynach występowania danego kodu stanu.
Wyniki
Gdy geokoder zwróci wyniki, umieszcza je w tablicy results
(JSON). Nawet jeśli geokoder nie zwróci żadnych wyników (np. gdy adres nie istnieje), i tak zwróci pustą tablicę results
. (Odpowiedzi XML zawierają zero lub więcej elementów <result>
).
Typowy wynik zawiera te pola:
- Tablica
types[]
wskazuje typ zwróconego wyniku. Ta tablica zawiera zestaw zero lub więcej tagów określających typ cechy zwróconej w wyniku. Na przykład kod geograficzny „Chicago” zwraca wartość „locality”, która oznacza, że „Chicago” jest miastem, oraz hasło „polityczne”, co oznacza, że jest podmiotem politycznym. Komponenty mogą mieć pustą tablicę typów, gdy nie są znane żadne typy danego komponentu adresu. W razie potrzeby interfejs API może dodać nowe wartości typów. Więcej informacji znajdziesz w artykule Typy adresów i ich komponenty. 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.
Aby obsługiwać tablicę komponentów, przeanalizuj odpowiedź i wybierz odpowiednie wartości za pomocą wyrażeń. Zapoznaj się z przewodnikiem dotyczącym analizowania odpowiedzi.
postcode_localities[]
to tablica wskazująca maksymalnie 100 miejscowości zawartych w kodzie pocztowym. Jest on dostępny tylko wtedy, gdy wynikiem jest kod pocztowy zawierający wiele miejscowości.geometry
zawiera te informacje:- Pole
location
zawiera Geokodowaną wartość długości i szerokości geograficznej. W przypadku normalnego wyszukiwania adresów to pole ma zwykle najważniejsze znaczenie. location_type
przechowuje dodatkowe dane o określonej lokalizacji. Obecnie obsługiwane są te wartości:"ROOFTOP"
oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji z dokładnością do dokładnego adresu."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 dachowe dla adresu ulicy są niedostępne."GEOMETRIC_CENTER"
oznacza, że zwrócony wynik to środek geometryczny wyniku, np. linii łamanej (na przykład ulica) lub wielokąta (region)."APPROXIMATE"
oznacza, że zwrócony wynik jest przybliżony.
viewport
zawiera zalecany widoczny obszar, na którym można wyświetlić zwrócony wynik, określony za pomocą 2 wartości szerokości i długości geograficznej, które określają róg ramki ograniczającej widoczny obszarsouthwest
inortheast
. Ogólnie widoczny obszar służy do umieszczania wyniku w ramce podczas wyświetlania go użytkownikowi.bounds
(opcjonalnie zwracana) przechowuje ramkę ograniczającą, która 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 prawdopodobnie nie powinny pojawiać się na widocznym obszarze.
- Pole
-
plus_code
(patrz Otwórz kod lokalizacji i kody plus) to zakodowane odniesienie do lokalizacji określane na podstawie współrzędnych geograficznych i reprezentujące obszar: 1/8000 stopnia i 1/8000 stopnia (około 14 x 14 m na równiku) lub mniejszy. Kody Plus Code mogą zastąpić adresy w miejscach, w których adresy nie istnieją (gdzie budynki nie są ponumerowane ani nazwy ulic). API nie zawsze zwraca kody Plus Code.Gdy usługa zwraca kod plus, jest sformatowany jako kod globalny i kod złożony:
global_code
to czteroznakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).compound_code
to co najmniej 6-znakowy kod lokalny z konkretną lokalizacją (CWC8+R9, Mountain View, Kalifornia, USA). Nie analizuj takich treści programowo.
-
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, 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 firmie lokalnej, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zobacz omówienie identyfikatora miejsca.
Typy adresów i typy komponentów adresu
Tablica types[]
w wyniku wskazuje typ adresu. Przykładowe rodzaje adresu to ulica i numer, kraj lub nazwa podmiotu politycznego. W obiekcie address_components[]
znajduje się też tablica types[]
, która wskazuje typ każdej części adresu. Może to być na przykład numer domu lub kraj. (Poniżej znajduje się pełna lista typów). Adresy mogą mieć kilka rodzajów. Typy mogą być uważane za „tagi”.
Na przykład wiele miast jest oznaczonych tagami typu political
i locality
.
Te typy są obsługiwane i zwracane przez geokoder zarówno w tablicach typu adresu, jak i typu komponentu 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 tego składniki adresu mogą zawierać wymienione tu typy. Ta lista nie jest pełna 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.
Promowanie widocznego obszaru
W żądaniu geokodowania można polecić usłudze Geocoding, aby preferowała wyniki w danym obszarze (wyrażony jako ramka ograniczająca). Aby to zrobić, ustaw parametr bounds
w adresie URL żądania.
Parametr bounds
określa współrzędne szerokości i długości geograficznej południowego i północno-wschodniego narożnika tej ramki ograniczającej za pomocą kreski pionowej (|
).
Na przykład kod geograficzny „Waszyngton” zwraca zwykle stan Waszyngton:
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"
}
Jednak dodanie argumentu bounds
definiującego ramkę ograniczającą wokół północno-wschodniej części Stanów Zjednoczonych spowoduje, że geokod będzie zwracał miasto Waszyngton w Dystrykcie Kolumbii:
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 geokodowania można za pomocą parametru region
polecić usłudze Geocoding, aby zwracała ona wyniki stronnicze w określonym regionie. Ten parametr przyjmuje argument ccTLD (domena najwyższego poziomu kodu kraju) określający odchylenie regionu. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk
), a jej kod ISO 3166-1 to „gb”
(technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).
Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której została oficjalnie uruchomiona główna aplikacja Map Google. 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 ten wynik, ponieważ domyślna domena interfejsu Geocoding API jest ustawiona na 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 geokodowania dla „Toledo” wysłane przez 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 Geocoding API interfejs Geocoding API może zwracać wyniki adresowe 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 korekty pisowni i częściowego dopasowywania, co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie do filtra komponentów, odpowiedź będzie zawierać pole partial_match
.
Wartości, które można filtrować (components
) to:
postal_code
pasuje dopostal_code
ipostal_code_prefix
.- Atrybut
country
odpowiada nazwie kraju lub dwuliterowym kodem kraju zgodnym z normą ISO 3166-1. Interfejs API jest zgodny ze standardem ISO dla definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.
Te components
mogą być używane do wpływania na wyniki, ale nie są wymuszane:
route
odpowiada długą lub krótką nazwą trasy.locality
pasuje do typówlocality
isublocality
.administrative_area
pasuje do wszystkichadministrative_area
poziomów.
Uwagi na temat filtrowania komponentów:
- Nie powtarzaj tych filtrów komponentów w żądaniach. W przeciwnym razie interfejs API zwróci wartość
Invalid_request
:country
,postal_code
,route
- Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API ocenia te filtry za pomocą operatorów ORAZ, a nie LUB.
- Wyniki są zgodne z Mapami Google, co czasem zwraca nieoczekiwane odpowiedzi
ZERO_RESULTS
. W niektórych przypadkach użycie autouzupełniania miejsc może 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 tych miejscach. Podanie tych samych wartości w obu przypadkach może spowodowaćZERO_RESULTS
.
Geokod odpowiadający „High St, Hastings” zawierający components=country:GB
zwraca wynik w Hastings (Anglia), a nie w Hastings-On-Hudson w 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"
}
Prośba o geokod dla rejonu „Santa Cruz” z components=country:ES
zwraca Santa Cruz de Tenerife na Wyspach Kanaryjskich 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 wykluczają się nawzajem.
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"
}
Za pomocą filtra components
możesz wysyłać prawidłowe zapytania bez parametru adresu. (podczas geokodowania pełnego adresu wymagany jest parametr address
, jeśli żądanie zawiera nazwy i numery 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"
}