Żądanie geokodowania i odpowiedź

Żądanie

Żądanie do interfejsu Geocode API ma tę formę:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

gdzie outputFormat może mieć jedną z tych wartości:

• json (zalecane) wskazuje dane wyjściowe w formacie JSON (JavaScript Object Notation),
• xml wskazuje dane wyjściowe w formacie XML

W przypadku żądań korzystających z klucza interfejsu API wymagany jest protokół HTTPS.

Niektóre parametry są wymagane, a inne opcjonalne. Tak jak ma to miejsce w przypadku adresów URL, parametry są rozdzielone znakiem „&”.

W pozostałej części strony omawiamy geokodowanie i odwrotne geokodowanie oddzielnie, ponieważ w przypadku 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 pocztowy lub kod Plus Code, który chcesz zakodować geograficznie; Adresy należy podać zgodnie z formatem obowiązującym w danym kraju. Nie należy używać dodatkowych elementów adresu, takich jak nazwy firm i jednostki, lokale lub piętra. Elementy adresu ulicy powinny być rozdzielone spacjami (przedstawione w adresie URL jako %20):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  Sformatuj kody plus, tak jak pokazano tutaj (znaki plus zamieniają url w %2B, a spacje w adresy URL w %20):
  • kod globalny to 4-znakowy numer kierunkowy i 6 lub więcej znaków lokalnych (849VCWC8 + R9 to 849VCWC8%2BR9).
  • kod złożony to co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components – filtr komponentów z elementami oddzielonymi pionową kreską (|). Jeśli podano address, filtr komponentów jest też opcjonalny. Każdy element w filtrze komponentów składa się z pary component:value i całkowicie ogranicza wyniki z kodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
• key – klucz interfejsu API aplikacji. Ten klucz określa Twoją aplikację na potrzeby zarządzania limitem. Dowiedz się, jak uzyskać klucz.

Dodatkowe wskazówki znajdziesz w Najczęstszych pytaniach.

Opcjonalne parametry w żądaniu geokodowania:

• bounds – ramka ograniczająca widoczny obszar, w którym odchylenie wyników geograficznych jest wyraźniejsze. Ten parametr będzie miał wpływ tylko na wyniki z geokodera, a nie na wszystkie. (Więcej informacji znajdziesz poniżej w sekcji Promowanie ze względu na widoczność).
• language – język, w którym mają być zwracane wyniki.
  • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
  • Jeśli nie zostanie podany parametr language, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka natywnego domeny, z której zostało wysłane żądanie.
  • Geokoder stara się podać adres pocztowy, który będzie czytelny dla użytkowników i użytkowników lokalnych. Aby osiągnąć ten cel, funkcja ta zwraca adresy pocztowe w języku lokalnym, a w razie potrzeby transliterację do skryptu zrozumiałego 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 został wybrany z pierwszego komponentu.
  • Jeśli nazwa jest niedostępna w wybranym języku, geokoder używa najbliższego dopasowania.
  • Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz kolejność ich zwracania. Geokoder interpretuje skróty w zależności od języka, np. skróty dla typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér są synonimami odpowiednio słowa „Street” i „kwadrat” po węgiersku.
• region – kod regionu podany jako ccTLD („domena najwyższego poziomu”). Ten parametr wpływa tylko na wyniki z geokodera, a nie jest w pełni ograniczony. Więcej informacji znajdziesz w sekcji Promowanie według regionu poniżej. Ten parametr może też wpływać na wyniki w zależności od obowiązującego prawa.
• components – filtr komponentów z elementami oddzielonymi pionową kreską (|). Jeśli żądanie nie zawiera pola address, filtr komponentów jest wymagany. Każdy element w filtrze komponentów składa się z pary component:value i całkowicie ogranicza wyniki z kodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.

Odpowiedzi

Odpowiedzi geokodowania są zwracane w formacie określonym przez flagę output w żądaniu adresu URL lub domyślnie w formacie JSON.

W tym przykładzie interfejs Geocoding API wysyła odpowiedź json na zapytanie dotyczące identyfikatora miejsca „ChIJeRpOeF67j4AR9ydy_PIzPuM”. Identyfikator tego miejsca to budynek znajdujący się pod adresem 1600 Amphitheatre Parkway, Mountain View, CA.

To żądanie pokazuje za pomocą flagi JSON output:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

To żądanie przedstawia flagę XML output:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Kliknij poniższe karty, aby zobaczyć przykładowe odpowiedzi w formacie JSON i XML.

{
    "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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

<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>

Kody stanu

Pole "status" w obiekcie odpowiedzi Geocode zawiera stan żądania i może zawierać dane debugowania, które pomogą Ci ustalić, dlaczego geokodowanie nie działa. Pole "status" może zawierać te wartości:

• "OK" oznacza, że nie wystąpiły żadne błędy. Adres został przeanalizowany, a przynajmniej 1 kod geograficzny został zwrócony.
• "ZERO_RESULTS" wskazuje, że udało się przetworzyć dane geograficzne, ale nie znaleziono żadnych wyników. Może tak się zdarzyć, jeśli koder został przekazany jako nieistniejący address.
• OVER_DAILY_LIMIT wskazuje dowolną z tych wartości:
  • Brak klucza interfejsu API lub jest on nieprawidłowy.
  • Płatności nie zostały włączone na Twoim koncie.
  • Samodzielnie ustawiony limit wykorzystania.
  • Podana forma płatności jest już nieważna (np. karta kredytowa straciła ważność).

  Aby dowiedzieć się, jak rozwiązać ten problem, zapoznaj się z najczęstszymi pytaniami dotyczącymi Map Google.

• "OVER_QUERY_LIMIT" oznacza, że został przekroczony limit.
• "REQUEST_DENIED" oznacza, że Twoja prośba została odrzucona.
• "INVALID_REQUEST" zwykle wskazuje, że brakuje zapytania (address, components lub latlng).
• "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Prośba może się udać, jeśli spróbujesz ponownie.

Komunikaty o błędach

Gdy geokoder zwraca kod stanu inny niż OK, w obiekcie odpowiedzi Geocoding może pojawić się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach danego kodu stanu.

Wyniki

Gdy geokoder zwraca wyniki, umieszcza je w tablicy results (JSON). Nawet jeśli geokoder nie zwraca żadnych wyników (na przykład nie istnieje adres), wciąż zwraca pustą tablicę results. (odpowiedzi XML składają się z zera lub większej liczby elementów <result>).

Typowy wynik zawiera następujące pola:

• Tablica types[] wskazuje typ zwróconego wyniku. Tablica zawiera zero lub więcej tagów określających typ cechy zwróconego w wyniku. Na przykład mapa geograficzna słowa „Chicago” zwraca nazwę „locality”, która wskazuje, że „Chicago” jest miastem, a „polityczna” wskazuje, że jest to podmiot polityczny. Komponenty mogą zawierać tablicę pustych typów, jeśli dla danego adresu nie są znane żadne typy. Interfejs API może w razie potrzeby dodawać nowe wartości typu. Więcej informacji znajdziesz w artykule Typy i komponenty adresów.
• formatted_address to ciąg znaków zawierający adres tej lokalizacji czytelny dla człowieka.

  Często jest to odpowiednik adresu pocztowego. Pamiętaj, że niektóre kraje, takie jak Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

  Sformatowany adres składa się z co najmniej jednego komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z następujących elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).

  Nie analizuj automatycznie sformatowanego adresu. Zamiast nich należy używać poszczególnych komponentów adresu, które oprócz odpowiedzi na pole formatowania zawierają odpowiedź interfejsu API.

• address_components[] to tablica zawierająca osobne komponenty mające zastosowanie do tego adresu.

  Każdy komponent adresu zawiera zazwyczaj następujące pola:

  • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
  • long_name to pełny opis lub nazwa komponentu adresu zwracana przez geokoder.
  • short_name to skrócona nazwa tekstowa komponentu adresu (jeśli jest dostępna). Na przykład komponent adresu w stanie Alaska może zawierać wartości long_name „Alaska” i short_name „AK” korzystające z dwuliterowego skrótu kodu pocztowego.

  Zapamiętaj te fakty na temat tablicy address_components[]:

  • Tablica komponentów adresu może zawierać więcej komponentów niż element formatted_address.
  • Tablica nie musi obejmować wszystkich jednostek politycznych zawierających adres oprócz tych uwzględnionych w polu formatted_address. Aby pobrać wszystkie elementy polityczne zawierające konkretny adres, użyj odwrotnego geokodowania. W tym żądaniu podaj szerokość i długość geograficzną adresu.
  • Format odpowiedzi nie może być taki sam między żądaniami. W szczególności liczba obiektów address_components różni się w zależności od żądanego adresu i może się zmienić z upływem czasu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować konkretnego komponentu.

  Aby obsługiwać tablicę komponentów, należy przeanalizować odpowiedź i wybrać odpowiednie wartości za pomocą wyrażeń. Zapoznaj się z przewodnikiem po analizie odpowiedzi.

• postcode_localities[] to tablica wskazująca wszystkie rejony zawarte w kodzie pocztowym. Ten wynik występuje tylko wtedy, gdy wynik jest kodem pocztowym zawierającym wiele lokalizacji.
• geometry zawiera te informacje:
  • location zawiera geograficzną szerokość i długość geograficzną. W przypadku zwykłych wyszukiwań adresów to pole jest zwykle najważniejsze.

  • location_type przechowuje dodatkowe dane na temat określonej lokalizacji. Obecnie obsługiwane są te wartości:

    • "ROOFTOP" wskazuje, że zwrócony wynik to dokładny geokod, w przypadku którego informacje o lokalizacji są dokładne, nawet z dokładnością do adresu ulicy.
    • "RANGE_INTERPOLATED" wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolowane między 2 punktami dokładnymi (na przykład skrzyżowania). Interpolowane wyniki są zwykle zwracane, gdy dane geograficzne z dachu nie są dostępne dla adresu ulicy.
    • "GEOMETRIC_CENTER" wskazuje, że zwrócony wynik jest geometrycznym środkiem wyniku, takim jak linia łamana (np. ulica) lub wielokąt (region).
    • "APPROXIMATE" oznacza, że zwrócony wynik jest przybliżony.
  • viewport zawiera zalecany obszar wyświetlania zwracanego wyniku, zdefiniowany jako 2 wartości szerokości i długości geograficznej,które określają górny róg pola southwest i northeast. Zasadniczo widoczny obszar jest używany do kadrowania wyniku podczas wyświetlania go użytkownikowi.
  • bounds (opcjonalnie) jest przeznaczony do przechowywania ramki ograniczającej, która może zawierać pełny wynik. Te granice mogą nie być zgodne z zalecanym widocznym obszarem. Na przykład San Francisco obejmuje wyspy Fallona, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być zwracane w widocznym obszarze.
• plus_code (patrz Otwórz kod lokalizacji i kody Plus Code) to zakodowane odniesienie do lokalizacji określone na podstawie współrzędnych szerokości i długości geograficznej, reprezentujące obszar: 1/8000 stopnia w 1/8000. stopnia (14 x 14 m w równaniu) lub mniejszego. Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie ma adresów (gdy budynki nie są numerowane lub nie mają nazw ulic). Interfejs API nie zawsze zwraca kody plus.

  Gdy usługa zwraca kod plus, jest on sformatowany jako kod globalny i kod złożony:

  • global_code to 4-cyfrowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).
  • compound_code to co najmniej 6-znakowy kod lokalny z jednoznaczną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tej treści programowo.
  Jeśli jest dostępny, interfejs API zwraca zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik jest w odległym miejscu (na przykład w oceanie lub na pustyni), może zostać zwrócony tylko kod globalny.

• Parametr partial_match wskazuje, że geokoder nie zwracał dokładnego dopasowania do pierwotnego żądania, chociaż mógł go dopasować do części żądanego adresu. Możesz sprawdzić pierwotną prośbę o weryfikację i niepoprawny adres.

  Częściowo pasujące są najczęściej adresy, które nie istnieją w regionie podanym w żądaniu. Częściowe dopasowania mogą się też pojawić, gdy żądanie pasuje do co najmniej dwóch lokalizacji w tym samym regionie. Na przykład wyszukiwanie „Hillpar St, Bristol, Wielka Brytania” zwróci częściowo dopasowania do ulicy Henry Street i ulicy Henrietta. Pamiętaj, że jeśli żądanie zawiera błędnie wpisany komponent adresu, usługa geokodowania może zaproponować inny adres. Sugestie aktywowane w ten sposób również będą oznaczane jako częściowe dopasowanie.

• place_id to unikalny identyfikator, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć place_id w żądaniu Places API, aby uzyskać szczegółowe informacje o lokalnej firmie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników i inne. Zapoznaj się z omówieniem identyfikatora miejsca.

Typy adresów i typy komponentów adresów

Tablica types[] w wyniku wskazuje typ adresu. Przykładowe typy adresów to adresy, kraje lub podmioty polityczne. address_components[] zawiera też tablicę types[], która wskazuje typ każdej części adresu. Może to być na przykład numer domu lub kraj. (poniżej znajdziesz pełną listę typów). Adresy mogą mieć wiele typów. Typy mogą być uznawane za „tagi”. Na przykład wiele miast jest oznaczonych za pomocą typu political i locality.

Te typy są obsługiwane i zwracane przez geokoder zarówno w tablicach typów adresów, jak i ich typach:

• street_address wskazuje dokładny adres.
• route oznacza nazwą trasę (np. „PL 101”).
• intersection wskazuje główne skrzyżowanie, złożone zwykle z 2 głównych dróg.
• political oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt administracji cywilnej.
• country wskazuje krajową instytucję polityczną i jest zwykle najwyższym typem zamówienia zwracanym przez geokoder.
• administrative_area_level_1 wskazuje na pierwszy poziom jednostki cywilnej niższy niż kraj. W Stanach Zjednoczonych są to stany administracyjne. Nie wszystkie kraje mają ten poziom administracyjny. W większości przypadków krótkie nazwy administracyjne_area_level_1 są bardzo zbliżone do podziałów ISO 3166-2 i innych szeroko rozpowszechnianych list. Nie gwarantujemy jednak, że wyniki geokodowania będą oparte na różnych sygnałach i danych o lokalizacji.
• administrative_area_level_2 wskazuje na kolejne kraje poziom cywilny drugiego rzędu. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje mają ten poziom administracyjny.
• administrative_area_level_3 wskazuje podmiot cywilny trzeciego poziomu poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_4 wskazuje na 4. porządek cywilny poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_5 wskazuje jednostkę cywilną o piątej kolejności poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_6 wskazuje na poziomie kraju szósty podmiot cywilny. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_7 wskazuje podmiot cywilny 7 poziomu poniżej kraju. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• colloquial_area wskazuje powszechnie używaną alternatywną nazwę elementu.
• locality wskazuje spółkę państwową, która jest częścią miasta.
• sublocality oznacza podmiot cywilny pierwszego stopnia znajdujący się niżej w okolicy. W przypadku niektórych lokalizacji może pojawić się dodatkowy typ: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu to podmiot cywilny. Większe liczby oznaczają mniejszy obszar geograficzny.
• neighborhood wskazuje na nazwaną dzielnicę
• premise wskazuje nazwane miejsce, zwykle budynek lub zbiór budynków o wspólnej nazwie
• subpremise wskazuje encję pierwszego stopnia poniżej nazwanej lokalizacji. Zazwyczaj jest to pojedynczy budynek w kolekcji budynków o takiej samej nazwie.
• plus_code wskazuje zakodowane odwołanie do lokalizacji pobrane na podstawie szerokości i długości geograficznej. Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie istnieją (gdy budynki nie są numerowane lub nie mają nazw ulic). Szczegółowe informacje znajdziesz na https://plus.codes.
• postal_code to kod pocztowy, który jest używany do obsługi poczty w danym kraju.
• natural_feature wskazuje charakterystyczną cechę naturalną.
• airport oznacza lotnisko.
• park wskazuje nazwany park.
• point_of_interest wskazuje na wybrane miejsce. Są to zwykle ważne lokalne obiekty, które nie pasują do żadnej kategorii, np. „Empire State Building” lub „Eiffel Tower”.

Pusta lista typów oznacza, że nie ma znanych typów poszczególnych komponentów adresu, np. Lieu-dit we Francji.

Oprócz wymienionych powyżej komponentów adresowych mogą obejmować podane tutaj typy. Ta lista nie jest pełna i może ulec zmianie.

• floor – piętro adresu budynku.
• establishment zwykle oznacza miejsce, które nie zostało jeszcze sklasyfikowane.
• landmark wskazuje miejsce w pobliżu używane jako odniesienie, które ułatwia nawigację.
• point_of_interest wskazuje na wybrane miejsce.
• parking wskazuje parking.
• post_box oznacza konkretną skrzynkę pocztową.
• postal_town oznacza grupę obszarów geograficznych, takich jak locality i sublocality, używane do określania adresów pocztowych w niektórych krajach.
• room oznacza salę z budynkiem.
• street_number wskazuje dokładny numer domu.
• bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, pociągowego lub publicznego.

Promowanie zakresu danych

W żądaniu geokodowania możesz poinstruować usługę geokodowania, aby preferowała wyniki z danego obszaru roboczego (wyrażonego jako ramka ograniczająca). Aby to zrobić, w adresie URL żądania ustaw parametr bounds.

Parametr bounds definiuje szerokość i długość geograficzną południowo-wschodniego i północnego wschodu ramki ograniczającej, rozdzielając je pionową kreską (|).

Na przykład kod geograficzny „Washington” zwykle zwraca stan USA „Washington”:

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 określającego ramkę ograniczającą wokół północno-wschodniej części Stanów Zjednoczonych powoduje, że kod geograficzny zwraca miasto Waszyngton w stanie 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 Geocode możesz poinstruować usługę Geocode, aby zwracała wyniki odchylenia do określonego regionu za pomocą parametru region. Ten parametr przyjmuje argument ccTLD (domena krajowa najwyższego poziomu) określającą odchylenie regionu. Większość kodów ccTLD jest taka sama jak kody ISO 3166-1, ale istnieją pewne wyjątki. Na przykład krajowa domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).

Wyniki geokodowania mogą być podawane w przypadku każdej domeny, w której oficjalnie wdrażana jest główna aplikacja Map Google. Promowanie wyników preferowanych tylko dla określonej domeny. Można dodać bardziej trafne wyniki spoza tej domeny.

Na przykład kod geograficzny „Toledo” zwraca ten wynik, ponieważ domyślną lokalizacją interfejsu Geocoding API jest 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 geokodu dla „Toledo” dla region=es (Hiszpania) zwróci hiszpańskie miasto.

Prośba:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=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 geokodowania interfejs Geocoding API może zwracać wyniki dotyczące adresów ograniczone do określonego obszaru. Ograniczenie możesz określić za pomocą filtra components. Filtr składa się z listy par component:value rozdzielonych pionową kreską (|). Wartości filtrów obsługują te same metody poprawiania pisowni i dopasowywania częściowego co inne żądania Geocode. Jeśli geokoder znajdzie częściowe dopasowanie dla filtra komponentów, odpowiedź będzie zawierać pole partial_match.

components, które można filtrować, to:

• postal_code pasuje do postal_code i postal_code_prefix.
• country jest zgodny z nazwą kraju lub dwuliterowym kodem kraju ISO 3166-1. Interfejs API jest zgodny ze standardem ISO definiującym kraje, a filtrowanie działa najlepiej, gdy używasz odpowiadającego mu kodu ISO.

components może mieć wpływ na wyniki, ale nie będzie egzekwowana:

• route pasuje do długiej lub krótkiej nazwy trasy.
• locality pasuje do typów locality i sublocality.
• administrative_area pasuje do wszystkich poziomów administrative_area.

Uwagi dotyczące filtrowania komponentów:

• Nie powtarzaj tych filtrów w żądaniach, ponieważ interfejs API zwróci Invalid_request: country, postal_code, route
• Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API ocenia te filtry jako operator ORAZ, a nie LUB.
• Wyniki są spójne z Mapami Google, które czasami zwracają nieoczekiwane odpowiedzi ZERO_RESULTS. Korzystanie z autouzupełniania miejsc może w niektórych przypadkach przynieść lepsze wyniki. Więcej informacji znajdziesz w najczęstszych pytaniach.
• W przypadku każdego komponentu adresu określ go w parametrze address lub w filtrze components, ale nie w obu naraz. Podanie tych samych wartości w obu przypadkach może spowodować ustawienie ZERO_RESULTS.

Geokod dla „High St, Hastings” z components=country:GB zwraca wynik w Hastings w Anglii, a nie w Hastings-On-Hudson, USA.

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 miejscowości „Santa Cruz” z adresem components=country:ES zwraca Santa Cruz de Tenerife na Wyspy Kanaryjskie 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 podasz 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"
}

Filtr components pozwala tworzyć prawidłowe zapytania bez parametru adresu. (W przypadku geokodowania pełnego adresu parametr address jest wymagany, jeśli żądanie zawiera nazwy i liczby 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"
}