Żądanie
Żądanie do interfejsu Geocoding API ma następującą 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 JSON (JavaScript Object Notation); lubxmlwskazuje dane wyjściowe w formacie XML.
Protokół HTTPS jest wymagany.
Niektóre parametry są wymagane, a inne – opcjonalne. Zgodnie ze standardem adresów URL parametry są rozdzielane znakiem ampersand (&).
W dalszej części tej strony opisujemy geokodowanie i odwrotne geokodowanie osobno, ponieważ dla każdego typu żądania dostępne są różne parametry.
Parametry geokodowania (wyszukiwania szerokości i długości geograficznej)
Parametry wymagane w żądaniu geokodowania:
key– klucz interfejsu API aplikacji. Ten klucz identyfikuje Twoją aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.W żądaniu musisz podać
addresslubcomponentsalbo obie te wartości:address– adres pocztowy lub kod Plus Code, który chcesz przekształcić na kod geograficzny. Uwaga: geokodowanie adresów nie rozpoznaje współrzędnych szerokości i długości geograficznej ani innych nieustrukturyzowanych ciągów znaków, które nie reprezentują adresu ani Plus Code. Żądania używające takich ciągów nie są obsługiwane i mogą powodować błędy lub nieokreślone zachowanie. Przykłady nieobsługiwanych zapytań:
Adresy należy podawać w formacie używanym przez krajową pocztę danego kraju. Unikaj dodatkowych elementów adresu, takich jak nazwy firm i numery lokali, apartamentów lub pięter. Elementy adresu powinny być rozdzielone spacjami (tutaj pokazane jako znaki ucieczki adresu URLTyp zapytania Przykład Współrzędne szerokości i długości geograficznej. Zamiast tego użyj odwrotnego geokodowania. "37.422131,-122.084801" Zbyt wiele pojęć lub ograniczeń, takich jak nazwy wielu miejsc, dróg lub miast w jednym zapytaniu. "Market Street San Francisco San Jose Airport" Elementy adresu pocztowego nie są widoczne w Mapach Google. "C/O Jan Kowalski, ul. Główna 123"
"Skr. poczt. 13, Warszawa"nazwy firm, sieci lub kategorii połączone z lokalizacjami, w których te podmioty nie są dostępne; „Tesco w pobliżu Dallas w Teksasie” niejednoznaczne zapytania, które można interpretować na wiele sposobów; „Punkt odbioru ładowarek” nazwy historyczne, które nie są już używane; "Middlesex United Kingdom" Elementy lub intencje niegeoprzestrzenne „Ile łodzi jest w porcie Ventura?” nieoficjalne lub niestandardowe nazwy, „Jenga”
„Helter Skelter”%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2B, a spacje przez%20):- kod globalny to 4-znakowy numer kierunkowy i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9 to
849VCWC8%2BR9). - kod złożony to kod lokalny składający się z co najmniej 6 znaków i zawierający jednoznaczną lokalizację (CWC8+R9 Mountain View, CA, USA to
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- kod globalny to 4-znakowy numer kierunkowy i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9 to
components– filtr komponentów z elementami oddzielonymi znakiem pionowej kreski (|). Filtr komponentów jest też akceptowany jako opcjonalny parametr, jeśli podanoaddress. Każdy element w filtrze komponentów składa się z parycomponent:valuei całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
Dodatkowe wytyczne znajdziesz w najczęstszych pytaniach.
Parametry opcjonalne w żądaniu geokodowania:
bounds– ramka ograniczająca widocznego obszaru, w którym wyniki geokodowania mają być bardziej faworyzowane. Ten parametr będzie miał wpływ na wyniki geokodera, ale nie będzie ich w pełni ograniczał. (Więcej informacji znajdziesz poniżej w sekcji Dostosowywanie do widocznego obszaru).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 podasz parametru
language, geokoder spróbuje użyć preferowanego języka określonego w nagłówkuAccept-Languagelub języka ojczystego domeny, z której wysłano żądanie. - Geokoder stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby osiągnąć ten cel, zwraca adresy pocztowe w języku lokalnym, w razie potrzeby transliterowane na pismo czytelne 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 jest wybierany z pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder używa najbliższego dopasowania.
- Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty 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 to po węgiersku synonimy słów ulica i plac.
region– kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Ten parametr będzie miał wpływ na wyniki z geokodera, ale nie będzie ich w pełni ograniczał. (Więcej informacji znajdziesz w sekcji Ustalanie regionu poniżej). Parametr może też wpływać na wyniki na podstawie obowiązujących przepisów.components– filtr komponentów z elementami oddzielonymi znakiem kreski pionowej (|). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera parametruaddress. Każdy element w filtrze komponentów składa się z parycomponent:valuei całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.extra_computations– użyj tego parametru, aby określić w odpowiedzi te dodatkowe funkcje:ADDRESS_DESCRIPTORS– więcej informacji znajdziesz w artykule o deskryptorach adresów.BUILDING_AND_ENTRANCES– więcej informacji znajdziesz w sekcji Wejścia i kontury budynków.
extra_computationsdla każdej funkcji, na przykład:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
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 o adres „1600 Amphitheatre Parkway, Mountain View, CA”.
To żądanie pokazuje użycie flagi JSON output:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
To żądanie pokazuje, jak używać flagi XML output:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Wybierz 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" }
Zwróć uwagę, że odpowiedź JSON zawiera 2 elementy główne:
"status"zawiera metadane żądania. Zobacz Kody stanu poniżej."results"zawiera tablicę informacji o adresie z kodem geograficznym i informacji o geometrii.
Zwykle w przypadku wyszukiwania adresów zwracany jest tylko 1 wpis w tablicy "results", ale geokoder może zwrócić kilka wyników, jeśli zapytania dotyczące adresu 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>
Zwróć uwagę, że odpowiedź XML składa się z jednego elementu <GeocodeResponse> i 2 elementów najwyższego poziomu:
<status>zawiera metadane żądania. Zobacz Kody stanu poniżej.- Co najmniej 0 elementów
<result>, z których każdy zawiera pojedynczy zestaw informacji o adresie i geometrii z kodem geograficznym.
Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Z tego powodu zalecamy używanie flagi json jako preferowanej flagi wyjściowej, chyba że Twoja usługa z jakiegoś powodu wymaga flagi xml.
Dodatkowo przetwarzanie drzew XML wymaga pewnej ostrożności, aby odwoływać się do właściwych węzłów i elementów. Zalecane wzorce projektowe dotyczące przetwarzania danych wyjściowych znajdziesz w artykule
Analizowanie kodu XML za pomocą XPath.
- Wyniki XML są opakowane w element główny
<GeocodeResponse>. - JSON oznacza wpisy z wieloma elementami za pomocą tablic w liczbie mnogiej (
types), a XML – za pomocą wielu elementów w liczbie pojedynczej (<type>). - Puste elementy są wskazywane przez puste tablice w pliku JSON, ale przez brak takiego elementu w pliku XML. Odpowiedź, która nie generuje żadnych wyników, zwróci na przykład pustą tablicę
resultsw formacie JSON, ale nie zwróci żadnych elementów<result>w formacie XML.
Kody stanu
Pole "status" w obiekcie odpowiedzi geokodowania 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 1 kod geograficzny."ZERO_RESULTS"oznacza, że kodowanie geograficzne zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli do geokodera przekazano nieistniejący parametraddress.OVER_DAILY_LIMIToznacza dowolną z tych wartości:- Brak klucza interfejsu API lub jest on nieprawidłowy.
- Na Twoim koncie nie włączono płatności.
- Przekroczono samodzielnie nałożony limit wykorzystania.
- Podana forma płatności nie jest już waż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.
"OVER_QUERY_LIMIT"oznacza, że przekroczono limit."REQUEST_DENIED"oznacza, że Twoja prośba została odrzucona."INVALID_REQUEST"zwykle oznacza, że brakuje zapytania (address,componentslublatlng)."UNKNOWN_ERROR"oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.
Komunikaty o błędach
Gdy geokoder zwraca kod stanu inny niż OK, w obiekcie odpowiedzi geokodowania może znajdować 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 zwróci żadnych wyników (np. jeśli adres nie istnieje), nadal zwraca pustą tablicę results. (Odpowiedzi XML składają się z co najmniej 0 elementów <result>).
Typowy wynik zawiera te pola:
- Tablica
types[]wskazuje typ zwróconego wyniku. Ta tablica zawiera zbiór co najmniej 0 tagów identyfikujących typ funkcji zwróconej w wyniku. Na przykład kod geograficzny „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, oraz „political”, co oznacza, że jest to jednostka polityczna. Więcej informacji znajdziesz w sekcji Typy adresów i typy komponentów adresów. formatted_addressto ciąg tekstowy zawierający zrozumiały dla człowieka adres tej lokalizacji.Często jest on taki sam jak adres pocztowy. Pamiętaj, że w niektórych krajach, np. w Wielkiej Brytanii, ze względu na ograniczenia licencyjne nie można rozpowszechniać prawdziwych adresów pocztowych.
Sformatowany adres składa się logicznie z co najmniej 1 komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych komponentów: „111” (numer domu), „8th Avenue” (ulica), „New York” (miasto) i „NY” (stan w USA).
Nie analizuj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które odpowiedź interfejsu API zawiera oprócz sformatowanego pola adresu.
address_components[]to tablica zawierająca osobne komponenty dotyczące tego adresu.Każdy komponent adresu zawiera zwykle te pola:
types[]to tablica wskazująca typ komponentu adresu. Jeśli nie ma znanych typów dla danego komponentu adresu, tablica typów może być pusta. W razie potrzeby interfejs API może dodawać nowe wartości typu. Więcej informacji znajdziesz w sekcji Typy adresów i typy komponentów adresów.long_nameto pełny opis tekstowy lub nazwa komponentu adresu zwracanego przez geokoder.short_nameto 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„Alaska” ishort_name„AK” (dwuliterowy skrót pocztowy).
Zwróć uwagę na te informacje o tablicy
address_components[]:- Tablica komponentów adresu może zawierać więcej komponentów niż
formatted_address. - Tablica nie musi zawierać wszystkich jednostek politycznych, które zawierają adres, oprócz tych, które są uwzględnione w
formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj odwrotnego geokodowania, przekazując szerokość i długość geograficzną adresu jako parametr żądania. - Nie ma gwarancji, że format odpowiedzi będzie taki sam w przypadku różnych żądań. W szczególności liczba
address_componentsróżni się w zależności od żądanego adresu i może się zmieniać w czasie dla 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łużyć tablicę komponentów, musisz przeanalizować odpowiedź i wybrać odpowiednie wartości za pomocą wyrażeń. Zapoznaj się z przewodnikiem po analizowaniu odpowiedzi.
postcode_localities[]to tablica zawierająca maksymalnie 100 miejscowości w obrębie kodu pocztowego. Ten element jest obecny tylko wtedy, gdy wynik jest kodem pocztowym, który zawiera wiele miejscowości.geometryzawiera te informacje:locationzawiera wartość szerokości i długości geograficznej. W przypadku zwykłych wyszukiwań adresów to pole jest zwykle najważniejsze.location_typeprzechowuje dodatkowe dane o określonej lokalizacji. Obecnie obsługiwane są te wartości:"ROOFTOP"wskazuje, że zwrócony wynik jest dokładnym kodem geograficznym, dla którego mamy informacje o lokalizacji z dokładnością do adresu."RANGE_INTERPOLATED"wskazuje, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy kody geograficzne dachu są niedostępne dla adresu ulicy."GEOMETRIC_CENTER"wskazuje, że zwrócony wynik jest geometrycznym środkiem wyniku, takiego jak linia łamana (np. ulica) lub wielokąt (region)."APPROXIMATE"wskazuje, że zwrócony wynik jest przybliżony.
viewportzawiera zalecany widok do wyświetlania zwróconego wyniku, określony jako 2 wartości szerokości i długości geograficznej,które definiują rógsouthwestinortheastramki ograniczającej widok. Zwykle widoczny obszar służy do kadrowania wyniku podczas wyświetlania go użytkownikowi.bounds(opcjonalnie zwracany) przechowuje ramkę ograniczającą, która może w pełni zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanemu obszarowi widoczności. (Na przykład San Francisco obejmuje wyspy Farallon, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być zwracane w widocznym obszarze).
-
plus_code(patrz Open Location Code i plus codes) to zakodowane odniesienie do lokalizacji, pochodzące ze współrzędnych szerokości i długości geograficznej, które reprezentuje obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m na 14 m na równiku) lub mniejszy. Plus kody mogą zastępować adresy ulic w miejscach, gdzie nie ma adresów (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). Interfejs API nie zawsze zwraca kody Plus Code.Gdy usługa zwraca plus code, jest on sformatowany jako kod globalny i kod złożony:
global_codeto 4-znakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).compound_codeto co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
-
partial_matchwskazuje, że geokoder nie zwrócił dopasowania ścisłego do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Sprawdź, czy w pierwotnym żądaniu nie ma błędów pisowni lub niekompletnego adresu.Częściowe dopasowania występują najczęściej w przypadku adresów, które nie istnieją w miejscowości podanej w żądaniu. Częściowe dopasowania mogą być też zwracane, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości. Na przykład „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno dla Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie wpisany komponent adresu, usługa geokodowania może zasugerować alternatywny adres. Sugestie wywołane w ten sposób będą również oznaczone jako częściowe dopasowanie.
place_idto unikalny identyfikator, którego można używać z innymi interfejsami API Google. Możesz na przykład użyćplace_idw żądaniu do Places API, aby uzyskać szczegółowe informacje o lokalnej firmie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników i inne. Zobacz omówienie identyfikatorów miejsc.
Typy adresów i typów komponentów adresów
Tablica types w odpowiedzi wskazuje typ adresu. Przykłady typów adresów: adres pocztowy, kraj lub podmiot polityczny. Tablica types w polu address_component wskazuje typ każdej części adresu. Przykłady: numer domu lub kraj.
Adresy mogą mieć wiele typów. Typy można traktować jako „tagi”.
Na przykład wiele miast jest oznaczonych typami political i locality.
Obsługiwane są te typy, które są zwracane zarówno w tablicach typów adresów, jak i tablicach typów komponentów adresów:
| Typ adresu | Opis |
|---|---|
street_address |
dokładny adres, |
route |
nazwana trasa (np. „US 101”). |
intersection |
Główne skrzyżowanie, zwykle 2 głównych dróg. |
political |
Podmiot polityczny. Zwykle ten typ wskazuje wielokąt jakiejś administracji cywilnej. |
country |
Narodowy podmiot polityczny, zwykle najwyższy poziom zwracany przez geokoder. |
administrative_area_level_1 |
Jednostka administracyjna pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany. Nie wszystkie kraje używają tych poziomów administracyjnych. W większości przypadków krótkie nazwy administrative_area_level_1 będą ściśle odpowiadać podregionom ISO 3166-2 i innym powszechnie używanym listom. Nie możemy jednak tego zagwarantować, ponieważ nasze wyniki geokodowania są oparte na różnych sygnałach i danych o lokalizacji. |
administrative_area_level_2 |
Jednostka administracyjna drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje używają tych poziomów administracyjnych. |
administrative_area_level_3 |
Jednostka administracyjna trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych. |
administrative_area_level_4 |
Jednostka administracyjna czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych. |
administrative_area_level_5 |
Jednostka administracyjna piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych. |
administrative_area_level_6 |
Jednostka administracyjna 6 rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych. |
administrative_area_level_7 |
Jednostka administracyjna 7 rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych. |
colloquial_area |
Powszechnie używana alternatywna nazwa podmiotu. |
locality |
podmiot polityczny miasta lub miejscowości; |
sublocality |
Jednostka administracyjna pierwszego rzędu poniżej poziomu miejscowości. W przypadku niektórych lokalizacji możesz otrzymać jeden z dodatkowych typów: od sublocality_level_1 do sublocality_level_5. Każdy poziom dzielnicy jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny. |
neighborhood |
nazwana okolica, |
premise |
Nazwana lokalizacja, zwykle budynek lub zespół budynków o wspólnej nazwie. |
subpremise |
Element podlegający adresowaniu poniżej poziomu budynku, np. mieszkanie, lokal lub apartament. |
plus_code |
Zakodowane odniesienie do lokalizacji, uzyskane na podstawie szerokości i długości geograficznej. Plus codes mogą zastępować adresy ulic tam, gdzie ich nie ma (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes. |
postal_code |
Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju. |
natural_feature |
Wyrazisty obiekt naturalny. |
airport |
Lotnisko. |
park |
park z nazwą, |
point_of_interest |
nazwane ciekawe miejsce, Zwykle są to znane lokalne obiekty, które nie pasują do żadnej innej kategorii, np. „Pałac Kultury i Nauki” 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 komponenty adresu mogą zawierać typy wymienione poniżej.
| Typ komponentu adresu | Opis |
|---|---|
floor |
Piętro w adresie budynku. |
establishment |
Zwykle jest to miejsce, które nie zostało jeszcze skategoryzowane. |
landmark |
Miejsce w pobliżu, które służy jako punkt odniesienia ułatwiający nawigację. |
point_of_interest |
nazwane ciekawe miejsce, |
parking |
Parking lub zadaszony parking. |
post_box |
konkretną skrytkę pocztową, |
postal_town |
Grupowanie obszarów geograficznych, takich jak locality i sublocality, używane w adresach pocztowych w niektórych krajach. |
room |
Numer pokoju w adresie budynku. |
street_number |
Dokładny numer domu. |
bus_station, train_station i transit_station |
Lokalizacja przystanku autobusowego, kolejowego lub transportu publicznego. |
Ustawianie widocznego obszaru
W żądaniu geokodowania możesz poinstruować usługę geokodowania, aby 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-zachodniego i północno-wschodniego rogu tego pola, używając znaku kreski pionowej (|) do oddzielenia współrzędnych.
Na przykład kod geograficzny „Washington” zwykle zwraca stan Waszyngton w USA:
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"
}
Jeśli jednak dodasz argument bounds definiujący ramkę ograniczającą wokół północno-wschodniej części Stanów Zjednoczonych, ten kod geograficzny 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"
}
Faworyzowanie regionu
W żądaniu geokodowania możesz poinstruować usługę geokodowania, aby zwracała wyniki faworyzujące dany region, używając parametru region. Ten parametr przyjmuje argument ccTLD (domena krajowa najwyższego poziomu) określający region. 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 kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).
Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której oficjalnie uruchomiono główną aplikację Map Google. Pamiętaj, że faworyzowanie tylko preferuje wyniki z określonej domeny. Jeśli poza tą domeną istnieją bardziej trafne wyniki, mogą one zostać 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” z 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 interfejs Geocoding API może zwracać wyniki 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 korekty pisowni i częściowego dopasowania co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie do filtra komponentu, odpowiedź będzie zawierać pole partial_match.
components, które można filtrować, to:
postal_codepasuje dopostal_codeipostal_code_prefix.countryodpowiada nazwie kraju lub dwuliterowemu kodowi kraju w standardzie ISO 3166-1. Interfejs API jest zgodny ze standardem ISO dotyczącym 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 będą egzekwowane:
routepasuje do długiej lub krótkiej nazwy trasy.localitypasuje do typówlocalityisublocality.administrative_areapasuje do wszystkich poziomówadministrative_area.
Uwagi dotyczące filtrowania komponentów:
- Nie powtarzaj tych filtrów komponentów w żądaniach, ponieważ interfejs API zwróci błąd
Invalid_request:country,postal_code,route. - Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API ocenia je jako AND, a nie OR.
- Wyniki są zgodne z Mapami Google, które czasami zwracają 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. - Każdy komponent adresu określ w parametrze
addresslub w filtrzecomponents, ale nie w obu tych miejscach. Podanie tych samych wartości w obu polach może spowodować błądZERO_RESULTS.
Kod geograficzny dla „High St, Hastings” z components=country:GB zwraca wynik w Hastings w Anglii, 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"
}
Żądanie geokodowania dla miejscowości „Santa Cruz” z parametrem 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 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"
}
Możesz tworzyć prawidłowe zapytania bez parametru adresu, używając filtra components. (Podczas 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"
}