Prośba
Żądanie do Geocoding API ma taką postać:
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 JavaScript Object Notation (JSON).xml
oznacza 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. Zgodnie ze standardem w adresach URL parametry są rozdzielone znakiem „&
”.
W pozostałej części tej strony opisujemy geokodowanie i odwrotne geokodowanie oddzielnie, ponieważ dla każdego typu żądania dostępne są inne parametry.
Parametry geokodowania (wyszukiwanie szerokości i długości geograficznej)
Parametry wymagane w żądaniu geokodowania:
address
– adres lub kod plus, dla którego chcesz przetworzyć dane geograficzne. Podaj adresy zgodnie z formatem używanym przez krajową służbę pocztową w danym kraju. Należy unikać dodatkowych elementów adresu, takich jak nazwy firm, lokale, lokale i piętra. Elementy adresu pocztowego powinny być rozdzielone spacjami (w tym przykładzie ze zmianą znaczenia adresu URL do adresu%20
):address=24%20Sussex%20Drive%20Ottawa%20ON
Sformatuj kody plus w sposób podany tutaj (znak plusa musi zawierać kod zmiany znaczenia dla adresu URL%2B
, a spacje należy zapisać w adresie URL do adresu%20
):- Kod globalny to 4-znakowy numer kierunkowy i co najmniej 6 znaków (kod lokalny 849VCWC8+R9 to
849VCWC8%2BR9
). - Kod złożony to co najmniej 6-znakowy kod lokalny z określoną lokalizacją (CWC8+R9 Mountain View, CA, USA to
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
– filtr komponentów z elementami rozdzielonymi pionową kreską (|
). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podano właściwośćaddress
. Każdy element filtra komponentów składa się z parycomponent:value
i całkowicie ogranicza wyniki generowane przez geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.- Kod globalny to 4-znakowy numer kierunkowy i co najmniej 6 znaków (kod lokalny 849VCWC8+R9 to
key
– klucz interfejsu API aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.
Więcej wskazówek znajdziesz w najczęstszych pytaniach.
Parametry opcjonalne w żądaniu Geocoding:
bounds
– ramka ograniczająca widoczny obszar, w którym lepiej eksponuje odchylenie geokodu. Ten parametr ma wpływ tylko na wyniki generowane przez geokodera, a nie jego pełne ograniczenie. Więcej informacji znajdziesz w sekcji Promowanie widocznego obszaru poniżej.language
– język, w którym zwracane 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.
- Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API zwróci, oraz na kolejność ich zwracania. Geokoder interpretuje skróty w różny sposób w zależności od języka (np. skrót nazwy ulicy lub synonimy mogą być poprawne w jednym języku, a w innym nie). Na przykład utca i tér to synonimy słów „ulica” i „kwadrat” w języku węgierskim.
region
– kod regionu, podany jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Ten parametr ma wpływ tylko na wyniki generowane przez geokodera, a nie jego pełne ograniczenie. Więcej informacji znajdziesz poniżej w sekcji Promowanie regionów. Parametr może też wpływać na wyniki w zależności od obowiązującego prawa.components
– filtr komponentów z elementami rozdzielonymi pionową kreską (|
). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera elementuaddress
. Każdy element filtra komponentów składa się z parycomponent:value
i całkowicie ogranicza wyniki generowane przez geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
Odpowiedzi
Odpowiedzi związane z geokodowaniem są zwracane w formacie określonym przez flagę output
w żądaniu adresu URL lub w formacie JSON.
W tym przykładzie interfejs Geocoding API żąda odpowiedzi json
na zapytanie o identyfikator miejsca „ChIJeRpOeF67j4AR9ydy_PIzPuM”. Ten identyfikator miejsca dotyczy budynku pod adresem 1600 Amphitheatre Parkway, Mountain View, CA.
W tym żądaniu pokazano użycie flagi JSON output
:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
W tym żądaniu użyto flagi XML output
:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Wybierz karty poniżej, 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" }
Zwróć uwagę, że odpowiedź JSON zawiera 2 elementy główne:
"status"
zawiera metadane w żądaniu. Zobacz Kody stanu poniżej."results"
zawiera tablicę danych geometrycznych adresowych i danych geometrycznych.
Zwykle w przypadku wyszukiwania adresów zwracany jest tylko jeden wpis w tablicy "results"
, ale geokoder może zwrócić kilka wyników,gdy zapytania o adres 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>
Uwaga: odpowiedź XML składa się z 1 elementu <GeocodeResponse>
i 2 elementów najwyższego poziomu:
<status>
zawiera metadane w żądaniu. Zobacz Kody stanu poniżej.- 0 lub więcej elementów
<result>
, a każdy z nich zawiera pojedynczy zestaw danych geograficznych i danych geometrycznych.
Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Dlatego zalecamy użycie flagi json
jako preferowanego wyniku wyjściowego, chyba że Twoja usługa z jakiegoś powodu wymaga xml
.
Poza tym przetwarzanie drzew XML wymaga zachowania ostrożności, aby odwoływać się do odpowiednich węzłów i elementów. Niektóre zalecane wzorce projektowania do przetwarzania danych wyjściowych znajdziesz w artykule o
analizowaniu kodu XML za pomocą XPath.
- Wyniki XML są zawarte w głównym elemencie
<GeocodeResponse>
. - JSON oznacza wpisy z wieloma elementami w tablicy liczby mnogiej (
types
), a XML – przy użyciu wielu elementów pojedynczych (<type>
). - Puste elementy są oznaczone w formacie JSON przez puste tablice, ale w przypadku braku takich elementów w pliku XML. Odpowiedź, która nie generuje żadnych wyników, zwróci pustą tablicę
results
w formacie JSON, ale nie będzie na przykład elementów<result>
w pliku 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 żadne błędy. Adres został pomyślnie przeanalizowany i zwrócono co najmniej jeden geokod."ZERO_RESULTS"
oznacza, że geokod został przetworzony pomyślnie, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder przekazał nieistniejący obiektaddress
.OVER_DAILY_LIMIT
oznacza jedną z tych wartości:- Brak klucza interfejsu API lub jest on nieprawidłowy.
- Płatności nie są włączone na Twoim koncie.
- Nałożony przez Ciebie limit wykorzystania został przekroczony.
- Podana forma płatności nie jest już aktualna (np. karta kredytowa straciła ważność).
Aby dowiedzieć się, jak rozwiązać ten problem, zapoznaj się z najczęstszymi pytaniami na temat Map.
"OVER_QUERY_LIMIT"
oznacza, że przekraczasz limit."REQUEST_DENIED"
oznacza, że Twoja prośba została odrzucona.- Parametr
"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. Jeśli spróbujesz ponownie, żądanie może zostać zrealizowane.
Komunikaty o błędach
Gdy geokoder zwraca kod stanu inny niż OK
, w obiekcie Geocoding odpowiedzi może pojawić się dodatkowe pole error_message
. Zawiera ono bardziej szczegółowe informacje o przyczynach 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), zwróci pustą tablicę results
. (Odpowiedzi XML zawierają 0 lub więcej elementów <result>
).
Typowy wynik zawiera te pola:
- Tablica
types[]
wskazuje typ zwróconego wyniku. Ta tablica zawiera zestaw tagów określających typ obiektu zwracanego w wyniku (zero lub więcej). Na przykład geokod „Chicago” zwraca „locality”, który wskazuje, że „Chicago” to miasto, i dodatkowo „polityczne”, które wskazuje, że jest to podmiot polityczny. Komponenty mogą mieć pustą tablicę typów, jeśli nie ma znanych typów dla danego komponentu adresu. W razie potrzeby interfejs API może dodać nowe wartości typu. Więcej informacji znajdziesz w artykule Typy adresów i komponenty adresu. formatted_address
to ciąg znaków zawierający czytelny dla człowieka adres tej lokalizacji.Często jest to równoważny adres pocztowy. Pamiętaj, że w niektórych krajach (np. w Wielkiej Brytanii) nie można rozpowszechniać prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.
Sformatowany adres logicznie składa się z co najmniej jednego komponentu adresu. Na przykład adres „111 8th Aleja, Nowy Jork, Nowy Jork” składa się z tych komponentów: „111” (numer domu), „8 Aleja” (trasa), „Nowy Jork” (miasto) i „NY” (stan w USA).
Nie analizuj sformatowanego adresu automatycznie. Zamiast tego należy używać poszczególnych komponentów adresu, które oprócz sformatowanego pola adresu zawierają odpowiedź interfejsu API.
address_components[]
to tablica zawierająca osobne komponenty mające zastosowanie do tego adresu.Każdy komponent adresu zwykle zawiera te pola:
types[]
to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.long_name
to pełny opis lub nazwa składnika adresu zwracanego przez geokodera.short_name
to skrócona nazwa tekstowa komponentu adresu, jeśli jest dostępna. Na przykład składnik adresu dla stanu Alaska może mieć atrybutlong_name
o nazwie „Alaska” oraz wartośćshort_name
w polu „AK” z dwuliterowym skrótem pocztowym.
Zwróć uwagę na te informacje na temat tablicy
address_components[]
:- Tablica komponentów adresu może zawierać więcej komponentów niż
formatted_address
. - Tablica nie musi zawierać wszystkich podmiotów politycznych z adresem (oprócz tych uwzględnionych w elemencie
formatted_address
). Aby pobrać wszystkie jednostki polityczne, które mają określony adres, użyj odwrotnego geokodowania, podając szerokość i długość geograficzną adresu jako parametr w żądaniu. - Nie możemy zagwarantować, że format odpowiedzi będzie taki sam między żądaniami. Liczba
address_components
różni się w zależności od żądanego adresu i może się z czasem zmieniać dla tego samego adresu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmieniać. Konkretnego komponentu może brakować w późniejszej odpowiedzi.
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 lokali zawartych w kodzie pocztowym. Ten atrybut występuje tylko wtedy, gdy wynik to kod pocztowy zawierający wiele miejscowości.geometry
zawiera te informacje:location
zawiera szerokość i długość geograficzną oznaczoną geokodem. W przypadku normalnego wyszukiwania adresów to pole jest zwykle najważniejsze.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 geokoder, w przypadku którego informacje o lokalizacji są dokładne z dokładnością do adresu pocztowego.- Wartość
"RANGE_INTERPOLATED"
wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolację między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki z interpolacji są zwykle zwracane, gdy geokody dachowe są niedostępne w przypadku adresu. "GEOMETRIC_CENTER"
wskazuje, że zwrócony wynik jest geometrycznym środkiem wyniku, takim jak linia łamana (na przykład ulica) lub wielokąt (region)."APPROXIMATE"
wskazuje, że zwrócony wynik jest przybliżony.
viewport
zawiera zalecany widoczny obszar do wyświetlania zwracanego wyniku, określony jako 2 wartości szerokości i długości geograficznej definiujące narożniksouthwest
inortheast
ramki ograniczającej widoczny obszar. Ogólnie widoczny obszar służy do umieszczania wyniku w ramce podczas wyświetlania go użytkownikowi.bounds
(zwracany opcjonalnie) przechowuje ramkę ograniczającą, która może w całości zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie pasować do zalecanego widocznego obszaru. Na przykład San Francisco obejmuje wyspy Farallona, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być zwracane w widocznym obszarze.
-
plus_code
(zobacz Otwórz kod lokalizacji i kody plus) to zakodowane odniesienie do lokalizacji utworzone na podstawie szerokości i długości geograficznej, które reprezentuje obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m x 14 m na równiku) lub mniejsze. Kody Plus Code mogą zastąpić adresy ulic w miejscach, które nie istnieją (gdzie budynki nie mają numerów lub ulic nie mają nazw). Interfejs API nie zawsze zwraca kody plus.Jeśli usługa zwraca kod plus, jest on 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 wyraźną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
-
partial_match
oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, mimo że udało się dopasować część żądanego adresu. Warto sprawdzić w pierwotnej prośbie, czy adres nie zawiera błędów pisowni lub zawiera niepełny adres.Dopasowania częściowe najczęściej występują w przypadku adresów, które nie występują w rejonie podanym w żądaniu. Dopasowania częściowe mogą zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym rejonie. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera komponent adresu z błędną pisownią, usługa geokodowania może zaproponować alternatywny adres. Sugestie uruchamiane w ten sposób będą również oznaczane jako dopasowania częściowe.
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ć informacje o lokalnej firmie, 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łady typów adresów to m.in. adres, kraj lub podmiot polityczny. address_components[]
znajduje się też w tablicy 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ć kilka typów. Typy te można uznać za „tagi”.
Na przykład wiele miast jest oznaczonych tagami political
i locality
.
Geokoder obsługuje te typy i zwraca je zarówno w tablicach typu adresu, jak i typów komponentów adresu:
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”.
Pusta lista typów oznacza, że nie ma znanych typów dla danego komponentu adresu (np. Lieu-dit we Francji).
Oprócz powyższych typów komponenty adresu mogą obejmować wymienione tutaj typy. Ta lista nie jest pełna i może się zmieniać.
floor
wskazuje piętro w adresie budynku.- Typ
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, aby ułatwić nawigację.point_of_interest
wskazuje nazwane miejsce.parking
oznacza parking lub strukturę parkingową.post_box
wskazuje konkretną skrytkę pocztową.postal_town
oznacza grupę obszarów geograficznych, np.locality
isublocality
, używaną w adresach pocztowych w niektórych krajach.room
wskazuje salę, w której znajduje się adres budynku.street_number
wskazuje dokładny numer ulicy.bus_station
,train_station
itransit_station
wskazują lokalizację przystanku autobusowego, pociągu lub transportu publicznego.
Promowanie widocznego obszaru
W żądaniu Geocoding możesz poinstruować usługę Geocoding, by preferowała wyniki w danym widocznym obszarze (wyrażonym jako ramka ograniczająca). Możesz to zrobić w adresie URL żądania, ustawiając parametr bounds
.
Parametr bounds
określa współrzędne geograficzne południowo-zachodnich i północno-wschodnich narożników tej ramki ograniczającej za pomocą pionowej kreski (|
) do oddzielania współrzędnych.
Na przykład geokod dla „Waszyngton” zazwyczaj zwraca 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ą północno-wschodnią część Stanów Zjednoczonych spowoduje, że ten geokod zwróci miasto Waszyngton:
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 Geocoding możesz poinstruować usługę Geocoding, aby zwracała odchylenia wyników w konkretnym regionie przy użyciu parametru region
. Ten parametr przyjmuje argument ccTLD (kod kraju najwyższego poziomu w domenie), który określa odchylenie dotyczące regionu. Większość kodów domen ccTLD jest taka sama jak kody ISO 3166-1, z pewnymi istotnymi wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk
), a kod ISO 3166-1 to „gb” (technicznie oznacza to podmiot „Wielka Brytania Wielkiej Brytanii i Irlandii Północnej”).
Wyniki geokodowania mogą być tendencyjne w przypadku każdej domeny, w której oficjalnie uruchomiono główną aplikację Map Google. Pamiętaj, że promowanie tylko preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną są bardziej trafne wyniki, możemy je uwzględnić.
Ten wynik jest na przykład zwracany w przypadku geokodu „Toledo”, ponieważ domyślną domeną 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 geokodowania dla „Toledo” wysłane do użytkownika 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 może zwracać wyniki adresów ograniczone do określonego obszaru. Ograniczenie można 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 dopasowania częściowego co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie filtra komponentów, odpowiedź będzie zawierać pole partial_match
.
components
, które można filtrować:
postal_code
pasuje dopostal_code
ipostal_code_prefix
.country
to nazwa kraju lub dwuliterowy kod kraju zgodny z normą ISO 3166-1. Interfejs API jest zgodny ze standardem ISO na potrzeby definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.
Poniższe components
mogą być używane do wpływania na wyniki, ale nie będą wymuszane:
route
pasuje do długiej lub krótkiej nazwy trasy.- Dopasowania
locality
do typówlocality
isublocality
. administrative_area
pasuje do wszystkich poziomów (administrative_area
).
Uwagi na temat filtrowania komponentów:
- Nie powtarzaj tych filtrów komponentów w żądaniach, bo interfejs API zwróci kod
Invalid_request
:country
,postal_code
,route
- Jeśli żądanie zawiera powtarzające się filtry komponentów, API użyje operatora ORAZ, a nie LUB.
- Wyniki są zgodne z Mapami Google, które czasami dają nieoczekiwane odpowiedzi na żądanie
ZERO_RESULTS
. W niektórych przypadkach korzystanie z autouzupełniania miejsc może przynieść lepsze wyniki. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania. - Dla każdego komponentu adresu podaj go w parametrze
address
lub filtrzecomponents
, ale nie w obu tych elementach. Podanie tych samych wartości w obu może dać wynikZERO_RESULTS
.
Geokod dla hasła „High St, Hastings” o wartości components=country:GB
zwraca wynik w Hastings (Anglia), a nie w Hastings-On-Hudson (Stany Zjednoczone).
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 kod geokodu dla rejonu „Santa Cruz” z components=country:ES
powoduje zwrócenie 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 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 tworzyć prawidłowe zapytania bez parametru address. (W przypadku geokodowania pełnego adresu parametr address
jest wymagany, 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"
}