Geokodowanie przekształca adres w lokalizację na mapie. Gdy geokodujesz adres, odpowiedź zawiera:
- Identyfikator miejsca lokalizacji
- Współrzędne geograficzne lokalizacji.
- Plus Code lokalizacji
- Rozszerzone szczegóły adresu
Prośba o geokodowanie
Żądanie geokodowania to żądanie HTTP GET. Adres możesz podać jako nieustrukturyzowany ciąg znaków:
https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING
lub jako uporządkowany zestaw komponentów adresu reprezentowanych przez parametry zapytania:
https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS
Format strukturalny jest zwykle używany podczas przetwarzania komponentów adresu przechwyconych w formularzu HTML.
Wszystkie pozostałe parametry przekazuj jako parametry adresu URL lub, w przypadku parametrów takich jak klucz interfejsu API i maska pola, w nagłówkach w ramach żądania GET.
Przekazywanie nieustrukturyzowanego ciągu adresu
Nieustrukturyzowany adres to adres sformatowany jako ciąg znaków lub kod Plus Code. Geokodowanie adresu nie rozwiązuje współrzędnych szerokości i długości geograficznej ani innych nieustrukturyzowanych ciągów znaków, które nie reprezentują adresu ani kodu Plus Code. Żądania korzystające z takich ciągów znaków nie są obsługiwane i mogą powodować zwracanie odpowiedzi o błędach lub nieokreślone zachowania. Przykłady nieobsługiwanych zapytań:
| Typ zapytania | Przykład |
|---|---|
| współrzędne geograficzne szerokości i długości, Zamiast tego użyj odwrotnego geokodowania. | "37.422131,-122.084801" |
| Zbyt wiele pojęć lub ograniczeń, np. nazwy wielu miejsc, dróg lub miast w jednym zapytaniu | „Market Street San Francisco San Jose Airport” |
| Elementy adresu pocztowego nie są reprezentowane w Mapach Google | „C/O John Smith 123 Main Street” „P.O. Box 13 San Francisco” |
| 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 z wieloma interpretacjami | „Oddanie ładowarki” |
| Nazwy historyczne, które nie są już używane | "Middlesex, Wielka Brytania" |
| Elementy lub intencje niezwiązane z geoprzestrzenią | „Ile łodzi jest w porcie Ventura?” |
| Nieoficjalne lub wymyślone nazwy | „The Jenga” „The Helter Skelter” |
Na przykład poniższy kod przekazuje zakodowany adres „1600 Amphitheatre Parkway, Mountain View, CA”:
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY
Zwróć uwagę, że znak „+” w adresie URL jest przekształcany w spację.
Możesz też wysłać żądanie za pomocą polecenia curl:
curl -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
Adresy mogą zawierać wiele rodzajów znaków specjalnych. Na przykład „/” w adresie „7/1 King St, Concord West”. Zakoduj znak „/” jako %2F:
https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West?key=API_KEY
Innym typowym przykładem jest znak „#”, np. „9500 W Bryn Mawr Ave #650, Rosemont”. Zakoduj znak „#” w adresie URL jako %2FE:
https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY
W następnym przykładzie określasz nieustrukturyzowany ciąg adresu jako kod plus 849VCWC8+R4. Pamiętaj, aby zakodować znak „+” w adresie URL jako %2B:
https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY
Przekazywanie ustrukturyzowanego adresu
Określ adres strukturalny za pomocą parametru zapytania address typu PostalAddress.
Obiekt PostalAddress umożliwia określenie w żądaniu niektórych lub wszystkich komponentów adresu jako poszczególnych parametrów zapytania.
Aby na przykład podać tylko kod pocztowy adresu, którego używasz:PostalAddress.postalCode
https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY
Aby określić wiele komponentów adresu, np. komponenty adresu przechwycone w formularzu HTML, użyj wielu parametrów zapytania:
https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View &address.administrativeArea=CA &key=API_KEY
Wysyłanie żądania za pomocą OAuth
Interfejs Geocoding API w wersji 4 obsługuje OAuth 2.0 na potrzeby uwierzytelniania. Aby używać OAuth z interfejsem Geocoding API, tokenowi OAuth musi być przypisany odpowiedni zakres. Geocoding API obsługuje te zakresy do geokodowania do przodu:
https://www.googleapis.com/auth/maps-platform.geocode– używaj ze wszystkimi metodami Geocoding API.https://www.googleapis.com/auth/maps-platform.geocode.address– używaj tylko z parametremGeocodeAddressw przypadku geokodowania do przodu.
Możesz też użyć ogólnego https://www.googleapis.com/auth/cloud-platformzakresu dla wszystkich metod interfejsu Geocoding API. Ten zakres jest przydatny podczas programowania, ale nie w środowisku produkcyjnym, ponieważ jest to zakres ogólny, który umożliwia dostęp do wszystkich metod.
Więcej informacji i przykładów znajdziesz w sekcji Korzystanie z OAuth.
Odpowiedź geokodowania
Geokodowanie zwraca obiekt GeocodeAddressResponse zawierający tablicę results obiektów GeocodeResult. Każdy obiekt GeocodeResult reprezentuje jedno miejsce.
Odpowiedzi Geocoding API zawierają types tablice w 2 głównych miejscach w GeocodeResult:
GeocodeResult.types: ta tablica wskazuje ogólne typy wyniku. Możliwe wartości pochodzą z tabeli A i B na stronie Typy miejsc (nowe).GeocodeResult.addressComponents[].types: każdy komponent adresu ma tablicętypeswskazującą typ tej konkretnej części adresu. Te wartości pochodzą z tabeli Typy adresów i typy komponentów adresu na stronie Typy miejsc (nowe).
Pełny obiekt JSON ma postać:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, ... ], "types": [ "street_address" ], "plusCode": { "globalCode": "849VCWC8+R4", "compoundCode": "CWC8+R4 Mountain View, CA, USA" } } ] }
Wymagane parametry
address– adres ulicy lub kod Plus Code, który chcesz przekształcić w współrzędne geograficzne. Uwaga: geokodowanie adresu nie rozwiązuje współrzędnych geograficznych ani innych nieustrukturyzowanych ciągów znaków, które nie reprezentują adresu ani kodu Plus Code. Więcej informacji i przykłady nieobsługiwanych zapytań znajdziesz w sekcji Przekazywanie nieustrukturyzowanego ciągu adresu. Adresy należy podawać w formacie używanym przez krajową pocztę w danym kraju. Należy unikać dodatkowych elementów adresu, takich jak nazwy firm oraz numery lokali, apartamentów lub pięter. Elementy adresu powinny być oddzielone spacjami zakodowanymi na potrzeby adresu URL jako%20. Na przykład przekaż adres „24 Sussex Drive Ottawa ON” w ten sposób:24%20Sussex%20Drive%20Ottawa%20ON
%2B, a spacje jako%20:- Kod globalny to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny. Na przykład zakoduj „849VCWC8+R9” jako
849VCWC8%2BR9. - Kod złożony to kod lokalny składający się z co najmniej 6 znaków, który zawiera wyraźną lokalizację. Na przykład zakoduj „CWC8+R9 Mountain View, CA, USA”
jako
CWC8%2BR9%20Mountain%20View%20CA%20USA.
- Kod globalny to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny. Na przykład zakoduj „849VCWC8+R9” jako
Parametry opcjonalne
locationBias
Określa obszar wyszukiwania jako
Viewport. Ta lokalizacja służy jako punkt odniesienia, co oznacza, że mogą być zwracane wyniki dotyczące miejsc w pobliżu określonej lokalizacji, w tym wyniki dotyczące miejsc znajdujących się w pobliżu, ale poza tym obszarem.Określ region jako prostokątny widoczny obszar. Prostokąt to widoczny obszar określony przez współrzędne geograficzne, reprezentowany przez 2 przeciwległe punkty o niskich i wysokich wartościach. Punkt dolny oznacza południowo-zachodni róg prostokąta, a punkt górny – północno-wschodni róg prostokąta.
Widok jest uważany za zamknięty obszar, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi mieścić się w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi mieścić się w przedziale od -180 do 180 stopni włącznie:
- Jeśli
low=high, widoczny obszar składa się z tego pojedynczego punktu. - Jeśli
low.longitude>high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przekracza linię długości geograficznej 180 stopni). - Jeśli
low.longitude= -180 stopni, ahigh.longitude= 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne. - Jeśli
low.longitude= 180 stopni, ahigh.longitude= -180 stopni, zakres długości geograficznej jest pusty. - Jeśli
low.latitude>high.latitude, zakres szerokości geograficznej jest pusty.
Wartości low i high muszą być wypełnione, a reprezentowane pole nie może być puste. Pusty widoczny obszar powoduje błąd.
Na przykład ten ciąg zapytania definiuje obszar widoku, który w całości obejmuje Nowy Jork:
?locationBias.rectangle.low.latitude=40.477398
&locationBias.rectangle.low.longitude=-74.259087 &locationBias.rectangle.high.latitude=40.91618 &locationBias.rectangle.high.longitude=-73.70018 - Jeśli
languageCode
Język, w którym mają być zwracane wyniki.
- Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być kompletna.
-
Jeśli nie podasz wartości
languageCode, interfejs API domyślnie użyje wartościen. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błądINVALID_ARGUMENT. - Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i mieszkańców. Aby to osiągnąć, zwraca adresy 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 na podstawie pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
- Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one 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.
regionCode
Kod regionu jako dwuznakowy kod CLDR. Nie ma wartości domyślnej. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.
W przypadku geokodowania adresu, czyli geokodowania wyprzedzającego, ten parametr może wpływać na wyniki usługi, ale nie ogranicza ich w pełni do określonego regionu. W przypadku geokodowania lokalizacji lub miejsca, czyli odwrotnego geokodowania lub geokodowania miejsca, ten parametr może służyć do formatowania adresu. We wszystkich przypadkach ten parametr może wpływać na wyniki na podstawie obowiązujących przepisów.
-
FieldMask
Utwórz maskę pola odpowiedzi, aby określić pola, które mają zostać zwrócone w odpowiedzi. Przekaż maskę pola odpowiedzi do metody, używając parametru adresu URL
$fieldslubfieldsalbo nagłówka HTTPX-Goog-FieldMask. Na przykład poniższe żądanie zwróci tylko poleplaceIDodpowiedzi.curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
Więcej informacji znajdziesz w sekcji Wybieranie pól do zwrócenia.
Preferowanie lokalizacji
Użyj parametru locationBias, aby poinstruować usługę Geokodowania, aby preferowała wyniki w danym widocznym obszarze (wyrażonym jako ramka ograniczająca).
Parametr locationBias określa współrzędne geograficzne południowo-zachodniego i północno-wschodniego rogu tego pola ograniczenia.
Na przykład żądanie geokodowania adresu „Washington” może zwrócić wyniki dla Waszyngtonu i stanu Waszyngton w USA:
https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY
Odpowiedź ma postać:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "location": { "latitude": 38.9071923, "longitude": -77.0368707 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "bounds": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "formattedAddress": "Washington, DC, USA", "addressComponents": [ { "longText": "Washington", "shortText": "Washington", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "location": { "latitude": 47.7510741, "longitude": -120.7401386 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024945, "longitude": -116.91607109999998 } }, "bounds": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024442, "longitude": -116.91607109999998 } }, "formattedAddress": "Washington, USA", "addressComponents": [ { "longText": "Washington", "shortText": "WA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, ... ], "types": [ "administrative_area_level_1", "political" ] } ] }
Dodanie parametru locationBias określającego ramkę ograniczającą wokół północno-wschodniej części Stanów Zjednoczonych powoduje jednak, że ten kod geograficzny zwraca tylko miasto Waszyngton:
https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72 &locationBias.rectangle.high.latitude=43.39 &locationBias.rectangle.high.longitude=-65.90 &key=API_KEY
Preferowanie regionu
W żądaniu geokodowania możesz poinstruować usługę geokodowania, aby zwracała wyniki z uwzględnieniem określonego regionu, używając parametru regionCode. Ten parametr przyjmuje wartość
dwuznakowego kodu CLDR określającego preferencje regionalne. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.
W przypadku parametru regionCode nie ma wartości domyślnej. Na przykład geokodowanie hasła „Toledo” zwraca wyniki dla Stanów Zjednoczonych i Hiszpanii:
https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY
Odpowiedź:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "location": { "latitude": 41.652805199999996, "longitude": -83.5378674 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "bounds": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "formattedAddress": "Toledo, OH, USA", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM", "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM", "location": { "latitude": 39.8628296, "longitude": -4.0273067 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "bounds": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "formattedAddress": "Toledo, España", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "administrative_area_level_4", "political" ], "languageCode": "es" }, ... ], "types": [ "administrative_area_level_4", "political" ] }, ... ] }
Żądanie geokodowania dla „Toledo” z parametrem regionCode=es (Hiszpania) zwraca tylko wyniki z Hiszpanii:
https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY