Żądanie
Żą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. Zgodnie ze standardem w adresach URL
Parametry są oddzielane znakiem ampersand (&
).
W pozostałej części tej strony opisaliśmy geokodowanie odwrotne geokodowanie, ponieważ dla każdego typu żądania dostępne są różne parametry.
Parametry geokodowania (wyszukiwanie szerokości i długości geograficznej)
Parametry wymagane w żądaniu geokodowania:
address
– adres lub kod plus, który chcesz poddać geokodowaniu. Podaj adresy zgodnie z formatem wykorzystywane przez krajowy urząd pocztowy w danym kraju. Dodatkowe informacje elementów adresowych, takich jak nazwy firm i numer lokalu, lokalu lub piętra powinno być pomijane. Elementy adresu powinny być rozdzielone spacjami (wyświetlane tutaj jako adres URL ze zmianą znaczenia do adresu%20
):address=24%20Sussex%20Drive%20Ottawa%20ON
Sformatuj kody plus zgodnie z poniższym opisem (znaki plusa są zmieniane w adres URL jako%2B
, a spacje zawierają kod%20
ze znakami zmiany znaczenia w adresie URL):- .
- kod globalny to 4-znakowy kod kierunkowy i co najmniej 6 znaków
kod lokalny (849VCWC8+R9 to
849VCWC8%2BR9
). - złożony kod to co najmniej 6-znakowy kod lokalny ze znakiem
bezpośrednia lokalizacja (CWC8+R9 Mountain View, CA, USA to
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
– filtr komponentów z elementami. są oddzielone pionową kreską (|
). Filtr komponentów również jest akceptowany. jako parametr opcjonalny, jeśli podanoaddress
. Każdy element w filtrze komponentów składa się zcomponent:value
i całkowicie ogranicza wyniki od geokodera. Zobacz więcej informacji: filtrowania komponentów poniżej.- kod globalny to 4-znakowy kod kierunkowy i co najmniej 6 znaków
kod lokalny (849VCWC8+R9 to
key
– klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje Twojej aplikacji na potrzeby zarządzania limitami. Dowiedz się, jak uzyskaj klucz.
Zapoznaj się z najczęstszymi pytaniami na temat: dodatkowe wskazówki.
Opcjonalne parametry w żądaniu Geocoding:
bounds
– ramka ograniczająca widocznego obszaru. w ramach których można bardziej eksponować wyniki geokodowania. Ten parametr będzie jedynie wpływać na wyniki, a nie całkowicie ograniczać. (Więcej więcej informacji znajdziesz w sekcji Promowanie widocznego obszaru poniżej).language
– język, w którym ma być używany wyniki.- Zobacz listę obsługiwanych funkcji języki. Google często aktualizuje obsługiwane języki, więc może nie być wyczerpująca.
- Jeśli nie zostanie podany
language
, geokoder spróbuje użyj preferowanego języka określonego wAccept-Language
lub język ojczysty domeny, z której wysłano żądanie. - Geokoder stara się podać adres, który łatwy do odczytania zarówno przez użytkownika, jak i lokalnie. Aby osiągnąć ten cel, zwraca adresy ulic w języku lokalnym po transliteracji na skryptach odczytanych przez użytkownika w razie potrzeby, obserwując preferowany język. Wszystkie inne adresy są zwracane w preferencjach język. wszystkie komponenty adresu są zwracane w jednym języku, który jest wybierany z pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder użyje jak najbliższe znaczeniem.
- Preferowany język ma niewielki wpływ na zestaw wyników, które zwracany przez interfejs API i kolejność ich zwrócenia. Geokoder różnie interpretuje skróty w zależności od takie jak skróty określające typy ulic lub synonimy, które mogą mogą być ważne w jednym języku, a w innym już nie. Na przykład: utca. tér to synonimy ulicy i kwadratu po węgiersku.
region
– kod regionu określony jako ccTLD. („domena najwyższego poziomu”) wartość dwuznakowa. Ten parametr będzie tylko wpływ, a nie na całkowite ograniczanie, wyników z geokodera. (Więcej więcej informacji znajdziesz w sekcji Promowanie według regionu poniżej). może też wpływać na wyniki na podstawie obowiązującego prawa.components
– filtr komponentów z elementami. oddzielone pionową kreską (|
). Filtr komponentów to wymagany, jeśli żądanie nie zawieraaddress
. Każdy element w filtrze komponentów składa się zcomponent:value
i całkowicie ogranicza wyniki od geokodera. Zobacz więcej informacji: filtrowania komponentów poniżej.extra_computations
– użyj tego parametru, aby określić parametr następujące dodatkowe funkcje w odpowiedzi:ADDRESS_DESCRIPTORS
– Zobacz deskryptory adresów.BUILDING_AND_ENTRANCES
– Zobacz wejścia i kontury budynków.
extra_computations
w żądaniu dla każdej funkcji, np.: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 wysyła żądanie json
odpowiedź na pytanie dotyczące adresu „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 adresowych z kodami geograficznymi oraz informacje geometryczne.
Zwykle zwracany jest tylko jeden wpis w tablicy "results"
dla argumentu
podczas wyszukiwania adresów, jednak geokoder może zwrócić kilka wyników,
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
<GeocodeResponse>
i 2 elementy najwyższego poziomu:
<status>
zawiera metadane dotyczące tego żądania. Zobacz Kody stanu poniżej.- 0 lub więcej elementów
<result>
, z których każdy zawiera jeden zbiór danych geometrycznych o adresach i danych geometrycznych.
Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Dla:
dlatego zalecamy wybór formatu json
.
flagi wyjściowej, chyba że usługa z jakiegoś powodu wymaga xml
.
Ponadto przetwarzanie drzew XML wymaga pewnej ostrożności, dlatego należy odwoływać się
odpowiednich węzłów i elementów. Zobacz
Analiza pliku XML za pomocą XPath w celu uzyskania niektórych zalecanych wzorców projektowych do przetwarzania danych wyjściowych.
- Wyniki XML są zawarte w elemencie głównym
<GeocodeResponse>
. - JSON oznacza wpisy z wieloma elementami przez tablice liczby mnogiej (
types
), a XML oznacza je przy użyciu wielu pojedynczych elementów (<type>
). - Puste elementy są wskazywane przez puste tablice w formacie JSON, ale przez brak
w kodzie XML. Odpowiedź, która nie generuje żadnych wyników, zwraca wartość pustą.
tablica
results
w formacie JSON, ale brak elementów<result>
w pliku XML, na przykład.
Kody stanu
Pole "status"
w obiekcie odpowiedzi Geocoding zawiera stan
żądania i może zawierać informacje na potrzeby debugowania, które ułatwiają ustalenie, dlaczego geokodowanie
nie działa. Pole "status"
może zawierać te wartości:
"OK"
oznacza, że nie wystąpiły błędy. adres został pomyślnie przeanalizowany i został zwrócony co najmniej jeden 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 ważność karty kredytowej wygasła).
Przeczytaj Najczęstsze pytania dotyczące Map, aby dowiedzieć się więcej. jak to naprawić.
"OVER_QUERY_LIMIT"
oznacza, że limit został przekroczony."REQUEST_DENIED"
oznacza, że prośba została odrzucona.- Zmienna
"INVALID_REQUEST"
zwykle wskazuje, że zapytanie (address
,components
lublatlng
). "UNKNOWN_ERROR"
oznacza, że nie udało się zrealizować żądania przetworzono z powodu błędu serwera. Żądanie może zostać zrealizowane, jeśli: spróbuj jeszcze raz.
Komunikaty o błędach
Gdy geokoder zwróci kod stanu inny niż OK
, mogą pojawić się dodatkowe
error_message
w obiekcie odpowiedzi Geocoding. To pole zawiera więcej
szczegółowe informacje o przyczynach związanych z określonym kodem stanu.
Wyniki
Gdy geokoder zwróci wyniki, umieszcza je w kodzie results
(JSON)
. Nawet jeśli geokoder nie zwróci żadnych wyników (np. jeśli adres nie istnieje), nadal nie zostanie znaleziony.
zwraca pustą tablicę results
. (Odpowiedzi XML zawierają zero lub więcej wartości
<result>
elements.)
Typowy wynik zawiera te pola:
- Tablica
types[]
wskazuje typ zwróconej wynik. Ta tablica zawiera zestaw zero lub więcej tagów identyfikujących typ funkcji zwracanych w wyniku. Na przykład kod geograficzny „Chicago”. zwraca "locality" który wskazuje, że „Warszawa” to miasta, a także zwraca wartość „political” (polityczny) co dowodzi, że jest to podmiot polityczny. Komponenty mogą mieć puste typy , gdy nie ma znanych typów dla danego składnika 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 tej lokalizacji.Adres ten jest często odpowiednikiem adresu pocztowego. Pamiętaj, że niektóre takich jak Wielka Brytania, nie zezwalają na dystrybucję prawdziwego adresów pocztowych ze względu na ograniczenia licencyjne.
Sformatowany adres składa się logicznie z jednego lub wielu adresów . Na przykład adres „ul. Polna 13, Warszawa” składa się z następujących komponentów: „111” (numer domu), „Ósma Aleja” (trasa), „Nowy Jork” (miasto) i „NY” (stan w USA).
Nie analizuj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych składników adresu, które zawiera odpowiedź interfejsu API do sformatowanego pola adresu.
address_components[]
to tablica zawierająca oddzielne dotyczące tego adresu.Każdy komponent adresu zawiera zwykle te pola:
types[]
to tablica wskazująca typ adresu. Zobacz listę obsługiwanych typów.long_name
to pełny opis lub nazwa elementu komponentem adresowym zwracanym przez Geocoder.short_name
to skrócona nazwa tekstowa adresu jeśli jest dostępny. Na przykład składnik adresu dla stanu obszaru Alaski może miećlong_name
o wartości „Alaska” ishort_name
pozycji „Akademia” za pomocą dwuliterowego skrótu pocztowego.
Zwróć uwagę na te informacje na temat:
address_components[]
tablica:- Tablica komponentów adresu może zawierać więcej komponentów niż
formatted_address
- Tablica nie musi obejmować wszystkich podmiotów politycznych, które
zawierają adres, oprócz tych zawartych w tagu
formatted_address
Aby pobrać wszystkie jednostki polityczne zawierających konkretny adres, należy zastosować odwrotne geokodowanie, przesyłając szerokość i długość geograficzną adresu jako parametr żądania. - Nie ma gwarancji, że format odpowiedzi będzie taki sam
żądań. W szczególności chodzi o liczbę
address_components
zmienia się w zależności od żądanego adresu i może się zmieniać pod tym samym adresem. Komponent może zmienić pozycję w tablicy. Typ komponentu może się zmienić. Konkretnym komponentem może być których brakuje w późniejszej odpowiedzi.
Aby obsługiwać tablicę komponentów, musisz przeanalizować odpowiedź i wybieraj odpowiednie wartości za pomocą wyrażeń. Zobacz przewodnik podczas analizowania odpowiedzi.
postcode_localities[]
to tablica oznaczająca do 100 miejscowości podane w kodzie pocztowym. Ten parametr jest widoczny tylko wtedy, gdy wynik to kod pocztowy który zawiera wiele lokalizacji.geometry
zawiera te informacje:- Pole
location
zawiera Geokodowaną wartość długości i szerokości geograficznej. Normalne wyszukiwań adresów, to pole jest zwykle najważniejsze. location_type
przechowuje dodatkowe dane o określonej lokalizacji. obecnie obsługiwane są następujące wartości:"ROOFTOP"
oznacza, że zwrócony wynik to dokładny geokod dla zapytania dzięki którym dysponujemy dokładnymi informacjami o lokalizacji aż do dokładnego adresu."RANGE_INTERPOLATED"
oznacza że zwracany wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między dwoma dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody na dachach nie są dostępne dla danej ulicy. adresu."GEOMETRIC_CENTER"
oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak linia łamana (na przykład ulica) lub wielokąt (region)."APPROXIMATE"
oznacza, że zwracany wynik jest przybliżony.
viewport
zawiera zalecany widoczny obszar wyświetlania zwrócony wynik, określony jako dwie wartości szerokości i długości geograficznej,definiującesouthwest
inortheast
róg ramki ograniczającej widoczny obszar. Ogólnie parametr jest używany do umieszczania wyniku w ramce podczas wyświetlania go użytkownikowi.- Funkcja
bounds
(opcjonalnie zwrócona) przechowuje ramkę ograniczającą który może w całości zawierać zwrócony wynik. Te progi mogą nie odpowiadać wartości zalecany widoczny obszar. (Na przykład San Francisco obejmuje Wyspy Farallona, technicznie stanowią część miasta, ale prawdopodobnie nie powinny być wyświetlane na widocznym obszarze).
- Pole
-
plus_code
(zobacz Otwórz kod lokalizacji i kody plus) to zakodowany odniesienie do lokalizacji na podstawie współrzędnych geograficznych, przedstawia obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m x 14 m na równiku) lub mniejszą. Kody Plus Code mogą zastąpić: adresów w miejscach, które nie istnieją (gdzie budynki nie są lub ulice nie mają nazwy). 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 4-znakowy 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ł kodu. dokładne dopasowanie do pierwotnego żądania, chociaż udało mu się dopasować część w żądanym adresie. Możesz sprawdzić pierwotną prośbę pod kątem błędów ortograficznych i/lub jest niepełny adres.Dopasowania częściowe najczęściej pojawiają się w przypadku adresów, które nie istnieją na obszarze objętym zgłoszeniem. Częściowe dopasowania mogą również zostać zwracany, 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 dla obu Henry Street i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera parametr błędnie zapisany adres, usługa geokodowania może zaproponować alternatywę adresu. Sugestie wywołane w ten sposób zostaną również oznaczone jako częściowe dopasowania.
place_id
to unikalny identyfikator których można używać z innymi interfejsami API Google. Możesz na przykład: użyj funkcjiplace_id
w Żądanie Places API do pobrania informacje o lokalnej firmie, takie jak numer telefonu, godziny otwarcia, opinie i inne treści. Zobacz identyfikator miejsca .
Typy adresów i typy komponentów adresu
Tablica types[]
w wyniku wskazuje
typ adresu. Przykłady typów adresów to: ulicę i numer,
kraju lub podmiotu politycznego. Istnieje również tablica types[]
w argumencie
address_components[]
, który 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
types.) Adresy mogą mieć kilka rodzajów. Typy mogą być uważane za „tagi”.
Na przykład wiele miast jest oznaczonych tagami political
oraz
Typ: locality
.
Geokoder obsługuje i zwraca poniższe typy w obu tablice typu adresu i typu komponentu adresu:
street_address
wskazuje dokładny adres.route
oznacza trasę z nazwą (np. „E101”).intersection
oznacza większe przecięcie, zwykle składające się z dwóch dróg głównych.political
oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt niektórych jednostek administracji cywilnej.country
oznacza krajowy podmiot polityczny i jest zwykle jest to najwyższy typ kolejności zwracany przez Geocoder.administrative_area_level_1
oznacza cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to stany. Nie we wszystkich krajach na poziomach administracyjnych. W większości przypadków parametr administracyjny_area_level_1 krótkie nazwy będą dokładnie odpowiadać podziałom zgodnym z normą ISO 3166-2 oraz innymi powszechnymi publikowane listy; Nie jest to jednak gwarantowane, ponieważ wyniki geokodowania na podstawie różnych sygnałów i danych o lokalizacji.administrative_area_level_2
oznacza typ cywilny drugiego rzędu. poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie we wszystkich krajach na poziomach administracyjnych.administrative_area_level_3
oznacza rodzaj 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 cywilny rządu 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 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 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 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
oznacza często używaną nazwę alternatywną. danego podmiotu.locality
oznacza miasto lub miejscowości, na terenie których funkcjonuje podmiotu zabezpieczeń.sublocality
oznacza podmiot cywilny pierwszego rzędu pod lokalizacji. W przypadku niektórych lokalizacji mogą pojawić się dodatkowe typy lokalizacji:sublocality_level_1
dosublocality_level_5
. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejsze obszar geograficzny.neighborhood
oznacza nazwany dzielnicępremise
wskazuje nazwane lokalizację, zwykle budynek lub zespół budynków o takiej samej nazwiesubpremise
oznacza element pierwszego rzędu pod nazwanym lokalizacji, zwykle pojedynczego budynku w obrębie zespołu budynków imię i nazwiskoplus_code
oznacza zakodowane odniesienie do lokalizacji, pochodne od szerokości i długości geograficznej. Kody Plus Code mogą zastąpić: adresów w miejscach, gdzie nie istnieją (gdzie budynki nie są numerowane lub ulice nie mają nazwy). Zobacz https://plus.codes. .postal_code
oznacza kod pocztowy używany do adresowania. na terenie tego 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 dobrze widoczne obiekty lokalne, które nie zawsze w innej kategorii, takiej jak „Empire State Building” czy „wieża Eiffla”.
Pusta lista typów oznacza, że nie ma znanych typów dla danego składnika adresu, np. Lieu-dit we Francji.
Oprócz powyższych elementów składowe adresu mogą zawierać wymienione tu typy. Ta lista jest nie jest wyczerpujący i może ulec zmianie.
floor
wskazuje piętro w adresie budynku.establishment
zwykle oznacza miejsce, w którym nie ma jeszcze została sklasyfikowana.landmark
wskazuje miejsce w pobliżu, które jest używane jako odniesienie. i ułatwi nawigację.point_of_interest
wskazuje nazwane miejsce.parking
oznacza parking.post_box
oznacza konkretną skrzynkę pocztową.postal_town
oznacza grupę obszarów geograficznych, takich jaklocality
isublocality
, używane w adresach 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ę autobusu, pociągu lub środka transportu publicznego przystanek.
Promowanie widocznego obszaru
W żądaniu Geocoding można poinstruować usługę Geocoding, że preferuje
wyników w danym obszarze widocznym (wyrażonym jako ramka ograniczająca). Robisz to
w adresie URL żądania za pomocą parametru bounds
.
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ą linii
(|
) do rozdzielenia współrzędnych.
Na przykład kod geograficzny „Waszyngton”. zwraca zwykle stan USA 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"
}
Dodanie argumentu bounds
definiującego ramkę ograniczającą
północno-wschodnią część USA daje wynik tego geokodu, który zwraca miasto
Waszyngton, D.C:
Prośba:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Odpowiedź:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Promowanie regionu
W żądaniu Geocoding możesz nakazać usłudze Geocoding, aby zwracała ona
wyników dla określonego regionu za pomocą funkcji region
. Ten parametr przyjmuje domenę ccTLD (kodu kraju najwyższego poziomu)
domena) określający odchylenie regionalne. Większość kodów ccTLD jest taka sama jak
kodów ISO 3166-1 z kilkoma wyjątkami. Na przykład Stany Zjednoczone
domena ccTLD królestwa to „uk” (.co.uk
), a jej kod ISO 3166-1 to „gb”
(technicznie dla podmiotu „Wielkiej Brytanii Wielkiej Brytanii i
Irlandia Północna”).
Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której główny Aplikacja Mapy Google została oficjalnie uruchomiona. Pamiętaj, że odchylenie dotyczy tylko preferuje wyniki z konkretnej domeny; jeśli istnieją trafniejsze wyniki spoza tej domeny, mogą zostać uwzględnione.
Na przykład geokod dla „Toledo”. domyślnie zwraca ten wynik. domena dla 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)
zwraca 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 zwrócić adres
wyników ograniczonych do konkretnego obszaru. Ograniczenie możesz określić za pomocą atrybutu
filtr components
. Filtr składa się z listy:
component:value
par rozdzielone pionową kreską (|
).
Wartości filtrów obsługują te same metody poprawy pisowni oraz częściowe sprawdzanie pisowni
tak jak inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie dla wartości
filtra komponentów, odpowiedź będzie zawierać pole partial_match
.
Wartości, które można filtrować (components
) to:
postal_code
pasuje do:postal_code
ipostal_code_prefix
.- Wyrażenie
country
odpowiada nazwie kraju lub dwuliterom ISO 3166-1 dla danego kraju. Interfejs API jest zgodny ze standardem ISO dla definiują kraje, a filtrowanie działa najlepiej przy z odpowiednim kodem ISO kraju.
Te components
mogą być używane do wpływania na wyniki, ale nie będą
egzekwowane:
route
odpowiada długą lub krótką nazwą trasy.- Mecze
locality
zlocality
isublocality
typy. administrative_area
pasuje do wszystkichadministrative_area
poziomów.
Uwagi na temat filtrowania komponentów:
- Nie powtarzaj tych filtrów komponentów w żądaniach – inaczej interfejs API zwróci
Invalid_request
:country
,postal_code
,route
- Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API je oceni użyj operatora I, a nie LUB.
- Wyniki są zgodne z Mapami Google, co czasem zwraca
nieoczekiwane odpowiedzi
ZERO_RESULTS
. Korzystanie z autouzupełniania miejsc w niektórych przypadkach może zapewnić lepsze wyniki. Więcej informacji: to Najczęstsze pytania. - Dla każdego komponentu adresu określ go w polu
address
lub w filtrzecomponents
, ale nie w obu tych przypadkach. Określanie Takie same wartości w obu mogą skutkować wynikiemZERO_RESULTS
.
Geokod dla „High Street, Hastings” dzięki components=country:GB
zwraca wynik w Hastings (Wielka Brytania), 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"
}
Żądanie geokodu dla rejonu „Santa Cruz” dzięki 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 zastosujesz 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"
}
Prawidłowe zapytania możesz wykonywać bez parametru address, używając parametru
Filtr: components
. (Przy geokodowaniu 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"
}