Geokodowanie przekształca adres w lokalizację na mapie. Gdy geokodujesz adres, odpowiedź zawiera:
- Identyfikator miejsca lokalizacji
- Współrzędne szerokości i długości geograficznej lokalizacji
- Plus Code lokalizacji
- Rozszerzone szczegóły adresu
Prośba o geokodowanie
Żądanie geokodowania to żądanie GET HTTP. Możesz podać adres 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 adresów 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ć błędy w odpowiedziach 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 częstym przykładem jest znak „#”, np. „9500 W Bryn Mawr Ave #650, Rosemont”. Zakoduj znak „#” 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 Code 849VCWC8+R4. Upewnij się, że znak „+” jest zakodowany 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ć protokołu OAuth z interfejsem Geocoding API, token OAuth musi mieć 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 tworzenia aplikacji, ale nie w przypadku aplikacji produkcyjnych, 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.
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 szerokości i długości geograficznej 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 adres „24 Sussex Drive Ottawa ON” możesz przekazać 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 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 wyznacza południowo-zachodni róg prostokąta, a punkt górny – północno-wschodni róg prostokąta.
Widoczny obszar jest uważany za zamknięty region, 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 jednego 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 ihigh.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.
Musisz podać dolną i górną wartość, 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, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. 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 wartość dwuznakowego kodu CLDR. Nie ma wartości domyślnej. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.
Podczas geokodowania adresu, czyli geokodowania do przodu, ten parametr może wpływać na wyniki usługi, ale nie może ich w pełni ograniczać do określonego regionu. Podczas geokodowania lokalizacji lub miejsca, odwrotnego geokodowania lub geokodowania miejsca ten parametr może służyć do formatowania adresu. W każdym przypadku 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 szerokości i długości geograficznej południowo-zachodniego i północno-wschodniego rogu tej ramki ograniczającej.
Na przykład żądanie geokodowania adresu „Washington” może zwrócić wyniki dla Waszyngtonu (stolicy USA) i stanu Waszyngton:
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.
Wartość domyślna parametru regionCode nie jest określona. Na przykład geokod „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