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 zakresu https://www.googleapis.com/auth/cloud-platform
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.
Odpowiedzi Geocoding API zawierają tablice types 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 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 oznacza 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, 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.
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 ogranicza ich całkowicie 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