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/v4beta/geocode/address/ADDRESS_STRING
lub jako uporządkowany zestaw komponentów adresu reprezentowanych przez parametry zapytania:
https://geocode.googleapis.com/v4beta/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 nagłówkach jako część żądania GET (w przypadku parametrów takich jak klucz interfejsu API i maska pola).
Przekazywanie nieustrukturyzowanego ciągu adresu
Nieustrukturyzowany adres to adres sformatowany jako ciąg znaków lub kod Plus Code. Na przykład poniższy kod przekazuje zakodowany adres „1600 Amphitheatre Parkway, Mountain View, CA”:
https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/geocode/address/7%2F1+King+St,+Concord+West?key=API_KEY
Innym częstym przykładem jest znak „#”, np. w adresie „9500 W Bryn Mawr Ave #650, Rosemont”. Zakoduj znak „#” jako %2FE:
https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY
W następnym przykładzie jako kod Plus Code 849VCWC8+R4 podajesz nieustrukturyzowany ciąg adresu. Upewnij się, że znak „+” jest zakodowany w adresie URL jako %2B:
https://geocode.googleapis.com/v4beta/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 niektórych lub wszystkich komponentów adresu w żądaniu jako poszczególnych parametrów zapytania.
Aby na przykład określić tylko kod pocztowy adresu, którego używasz:PostalAddress.postalCode
https://geocode.googleapis.com/v4beta/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/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View &address.administrativeArea=CA &key=API_KEY
Wysyłanie żądania za pomocą protokołu 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, 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 punktami końcowymi 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 punktów końcowych 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 punktów końcowych.
Więcej informacji i przykładów znajdziesz w sekcji Używanie 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. 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 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 się mieścić w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi się mieścić 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.
Musisz podać dolną i górną wartość, a reprezentowane pole nie może być puste. Pusty obszar wyświetlania 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 w określonym regionie, ale nie może ich całkowicie ograniczać. 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.
Preferowanie lokalizacji
Użyj parametru locationBias, aby poinstruować usługę Geocoding, aby preferowała wyniki w danym obszarze widoku (wyrażonym jako pole ograniczające).
Parametr locationBias określa współrzędne szerokości i długości geograficznej południowo-zachodniego i północno-wschodniego rogu tego prostokąta.
Na przykład żądanie geokodowania adresu „Washington” może zwrócić wyniki dla Waszyngtonu (stolicy USA) i stanu Waszyngton:
https://geocode.googleapis.com/v4beta/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 pole ograniczenia wokół północno-wschodniej części Stanów Zjednoczonych powoduje jednak, że ten geokod zwraca tylko miasto Waszyngton:
https://geocode.googleapis.com/v4beta/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, która określa 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/v4beta/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/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY