Żądanie geokodowania i odpowiedź

Żądanie

Żądanie Geocoding API ma następującą formę:

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

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

• json (zalecane) oznacza dane wyjściowe w formacie JSON (JavaScript Object Notation); lub
• xml oznacza dane wyjściowe w formacie XML

Wymagany jest protokół HTTPS.

Niektóre parametry są wymagane, a inne – opcjonalne. Zgodnie ze standardem adresów URL parametry są rozdzielane znakiem ampersand (&).

W dalszej części tej strony opisujemy oddzielnie geokodowanie i odwrotne geokodowanie, ponieważ w przypadku każdego typu żądania dostępne są inne parametry.

Parametry geokodowania (wyszukiwanie szerokości i długości geograficznej)

Wymagane parametry w prośbie o geokodowanie:

• key – klucz interfejsu API aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

• W żądaniu musisz podać atrybut address lub components albo oba:

  • 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 (w tym przykładzie są one zapisane w formacie URL-encoded jako %20):

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

    Formatuj kody plusowe w sposób pokazany poniżej (znaki plusa są kodowane w adresie URL jako %2B, a spacje jako %20):
    • kod globalny to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9 to 849VCWC8%2BR9).
    • kod złożony to lokalny kod składający się z co najmniej 6 znaków, który zawiera wyraźną lokalizację (CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • components – filtr komponentów z elementami oddzielonymi znakiem potoku (|). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podano parametr address. Każdy element filtra komponentów składa się z pary component:value i całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.

Dodatkowe wytyczne znajdziesz w odpowiedziach na najczęstsze pytania.

Parametry opcjonalne w żądaniu geokodowania:

• bounds – pole ograniczające widocznego obszaru, w którym wyniki geokodowania mają być bardziej widoczne. Ten parametr będzie tylko wpływać na wyniki z geokodera, a nie w pełni je ograniczać. (Więcej informacji znajdziesz poniżej w sekcji Viewport Biasing).
• language – 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 parametr language nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka natywnego domeny, z której wysłano żądanie.
  • Geokoder dokłada wszelkich starań, aby podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla 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, geokoder 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. Na przykład utca i tér to odpowiednio synonimy słów „ulica” i „plac” w języku węgierskim.
• region – kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Ten parametr będzie tylko wpływać na wyniki z geokodera, a nie w pełni je ograniczać. (Więcej informacji znajdziesz w sekcji Region Biasing poniżej). Parametr może też wpływać na wyniki na podstawie obowiązujących przepisów.
• components – filtr komponentów z elementami oddzielonymi znakiem potoku (|). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera parametru address. Każdy element filtra komponentów składa się z pary component:value i całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
• extra_computations – użyj tego parametru, aby określić te dodatkowe funkcje w odpowiedzi:
  • ADDRESS_DESCRIPTORS – Więcej informacji znajdziesz w artykule deskryptory adresów.
  • BUILDING_AND_ENTRANCES – więcej informacji znajdziesz w artykule wejścia i obrysy budynków.
  Aby włączyć kilka z tych funkcji w tym samym żądaniu interfejsu API, w żądaniu uwzględnij parametr extra_computations dla każdej funkcji, np.:

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Odpowiedzi

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

W tym przykładzie interfejs Geocoding API wysyła żądanie json w odpowiedzi na zapytanie dotyczące adresu „1600 Amphitheatre Parkway, Mountain View, CA”.

To żądanie pokazuje użycie flagi JSON output:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

To żądanie pokazuje użycie flagi XML output:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Aby zobaczyć przykładowe odpowiedzi w formatach JSON i XML, wybierz karty poniżej.

{
    "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"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "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 Geocoding zawiera stan żądania i może zawierać informacje do 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ł prawidłowo przeanalizowany i zwrócono co najmniej jeden geokod.
• "ZERO_RESULTS" oznacza, że geokodowanie się powiodło, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał nieistniejący address.
• Symbol OVER_DAILY_LIMIT oznacza jedną z tych wartości:
  • Brak klucza interfejsu API lub jest on nieprawidłowy.
  • Na Twoim koncie nie włączono płatności.
  • Przekroczono samodzielnie ustalony limit wykorzystania.
  • Podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność).

  Aby dowiedzieć się, jak to naprawić, zapoznaj się z najczęstszymi pytaniami dotyczącymi Map.

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

Komunikaty o błędach

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

Wyniki

Gdy geokoder zwróci wyniki, umieści je w tablicy (JSON) results. Nawet jeśli geokoder nie zwróci żadnych wyników (np. gdy adres nie istnieje), zwróci pustą tablicę results. (Odpowiedzi XML składają się z 0 lub większej liczby elementów <result>).

Typowy wynik zawiera te pola:

• Tablica types[] wskazuje typ zwróconego wyniku. Ta tablica zawiera zestaw tagów (co najmniej 1) określających typ funkcji zwróconej w wyniku. Na przykład kod geograficzny „Chicago” zwraca wartość „locality”, która wskazuje, że „Chicago” to miasto, a także wartość „political”, która wskazuje, że jest to jednostka polityczna. Komponenty mogą mieć pustą tablicę typów, jeśli nie ma znanych typów dla tego komponentu adresu. W razie potrzeby interfejs API może dodawać nowe wartości typu. Więcej informacji znajdziesz w sekcji Typy adresów i składniki adresu.
• formatted_address to ciąg tekstowy zawierający adres tej lokalizacji w formacie czytelnym dla człowieka.

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

  Sformatowany adres składa się logicznie z co najmniej 1 komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych komponentów: „111” (numer domu), „8th Avenue” (ulica), „New York” (miasto) i „NY” (stan w USA).

  Nie analizuj sformatowanego adresu programowo. Zamiast tego używaj poszczególnych komponentów adresu, które są uwzględniane w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.

• address_components[] to tablica zawierająca poszczególne komponenty, które mają zastosowanie do tego adresu.

  Każdy komponent adresu zawiera zwykle te pola:

  • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
  • long_name to pełny tekst opisu lub nazwa komponentu adresu zwrócona przez geokoder.
  • short_name to skrócona nazwa tekstowa komponentu adresu, jeśli jest dostępna. Na przykład komponent adresu dla stanu Alaska może mieć wartość long_name „Alaska” i wartość short_name „AK” przy użyciu 2-literowego skrótu pocztowego.

  Pamiętaj o tych informacjach dotyczących tablicy address_components[]:

  • Tablica komponentów adresu może zawierać więcej komponentów niż formatted_address.
  • Tablica nie musi zawierać wszystkich jednostek politycznych, które zawierają adres, z wyjątkiem tych, które są uwzględnione w formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj geokodowania zwrotnego, przekazując szerokość i długość geograficzną adresu jako parametr żądania.
  • Format odpowiedzi nie musi być taki sam w przypadku różnych żądań. W szczególności liczba address_components zależy od żądanego adresu i może się zmieniać z czasem w przypadku tego samego adresu. Komponent może zmienić pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować określonego komponentu.

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

• postcode_localities[] to tablica zawierająca maksymalnie 100 miejscowości w danym kodzie pocztowym. Jest to widoczne tylko wtedy, gdy wynikiem jest kod pocztowy obejmujący kilka miejscowości.
• geometry zawiera te informacje:
  • location zawiera zakodowaną geograficznie wartość szerokości i długości geograficznej. W przypadku zwykłych wyszukiwań adresów to pole jest zwykle najważniejsze.

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

    • "ROOFTOP" oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji o dokładności adresu ulicy.
    • "RANGE_INTERPOLATED" oznacza, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowaniami). Interpolowane wyniki są zwykle zwracane, gdy w przypadku adresu ulicy nie są dostępne geokody dachu.
    • "GEOMETRIC_CENTER" oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak linia łamana (np. ulica) lub wielokąt (region).
    • "APPROXIMATE" oznacza, że zwrócony wynik jest przybliżony.
  • viewport zawiera zalecany widoczny obszar do wyświetlania zwróconego wyniku, określony jako 2 wartości szerokości i długości geograficznej,które definiują rogi southwest i northeast ramki ograniczającej widoczny obszar. Zwykle podczas wyświetlania wyniku użytkownikowi używany jest widoczny obszar.
  • bounds (opcjonalnie zwracany) przechowuje pole ograniczające, które może w pełni zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie pasować do zalecanego obszaru wyświetlania. (Na przykład San Francisco obejmuje wyspy Farallon, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być zwracane w obszarze widocznym).
• plus_code (patrz Open Location Code i kody plus) to zakodowany odnośnik do lokalizacji, który jest wyznaczany na podstawie współrzędnych geograficznych i reprezentuje obszar o wielkości 1/8000 stopnia szerokości i 1/8000 stopnia długości geograficznej (około 14 m × 14 m na równiku) lub mniejszy. Kody Plus Code mogą zastępować adresy ulic w miejscach, w których nie ma adresów (budynki nie mają numerów, a ulice nie mają nazw). Interfejs API nie zawsze zwraca kody plus.

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

  • global_code to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9).
  • compound_code to 6-znakowy lub dłuższy kod lokalny z określoną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
  Jeśli to możliwe, interfejs API zwraca zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik znajduje się w odległej lokalizacji (np. na oceanie lub pustyni), może zostać zwrócony tylko kod globalny.

• partial_match – oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Sprawdź, czy w pierwotnym żądaniu nie ma błędów pisowni lub niepełnego adresu.

  Częściowe dopasowania najczęściej występują w przypadku adresów ulic, które nie istnieją w miejscowości przekazywanej w żądaniu. Częściowe dopasowania mogą być też zwracane, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości. Na przykład „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do Henry Street, jak i do Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie napisaną część adresu, usługa geokodowania może zaproponować alternatywny adres. Sugerowane odpowiedzi wywołane w ten sposób będą też oznaczone 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 itp. Zapoznaj się z omówieniem identyfikatora miejsca.

Typy adresów i typy komponentów adresu

Tablica types w odpowiedzi wskazuje typ adresu. Przykłady typów adresów to adres ulicy, kraj lub jednostka polityczna. Tablica types w polu address_component wskazuje typ każdej części adresu. Mogą to być np. numer ulicy lub kraj.

Adresy mogą mieć wiele typów. Typy te można uznać za „tagi”. Na przykład wiele miast jest oznaczonych typami political i locality.

Obsługiwane są te typy, które są zwracane w tablicach typu adresu i typu komponentu adresu:

Pusta lista typów oznacza, że dla danego komponentu adresu nie ma znanych typów (np. Lieu-dit we Francji).

Oprócz powyższych komponenty adresu mogą obejmować typy wymienione poniżej.

Sugerowanie widocznego obszaru

W żądaniu geokodowania możesz poinstruować usługę geokodowania, aby preferowała wyniki w danym obszarze widoku (wyrażonym jako pole ograniczające). Możesz to zrobić w adresie URL żądania, ustawiając parametr bounds.

Parametr bounds określa współrzędne szerokości i długości geograficznej południowo-zachodniego i północno-wschodniego rogu tego pola ograniczenia. Współrzędne są rozdzielone znakiem kreski pionowej (|).

Na przykład kod geograficzny dla „Washington” zwykle zwraca stan Waszyngton w Stanach Zjednoczonych:

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

Jednak dodanie argumentu bounds, który definiuje pole ograniczające wokół północno-wschodniej części Stanów Zjednoczonych, powoduje, że ten geokod zwraca miasto Waszyngton:

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

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 region. Ten parametr przyjmuje argument ccTLD (domena krajowa najwyższego poziomu) określający preferencje regionalne. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma znaczącymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

Wyniki geokodowania mogą być obciążone błędem w przypadku każdej domeny, w której główna aplikacja Mapy Google została oficjalnie udostępniona. Pamiętaj, że faworyzowanie tylko preferuje wyniki z określonej domeny. Jeśli istnieją bardziej trafne wyniki poza tą domeną, mogą one zostać uwzględnione.

Na przykład geokod dla „Toledo” zwraca ten wynik, ponieważ domena domyślna interfejsu Geocoding API jest ustawiona na 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 geokodowania dla „Toledo” z parametrem 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 Geocoding API może zwracać wyniki adresów ograniczone do określonego obszaru. Ograniczenie możesz określić za pomocą filtra components. Filtr składa się z listy component:valuepar rozdzielonych znakiem potoku (|). Wartości filtrów obsługują te same metody korekty pisowni i dopasowywania częściowego co inne żądania Geocoding API. Jeśli geokoder znajdzie częściowe dopasowanie do filtra komponentu, 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 pasuje do nazwy kraju lub dwuliterowego kodu kraju w standardzie ISO 3166-1. Interfejs API jest zgodny ze standardem ISO dotyczącym definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Te components mogą wpływać na wyniki, ale nie będą egzekwowane:

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

Uwagi dotyczące filtrowania komponentów:

• Nie powtarzaj tych filtrów komponentó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 je jako warunek AND, a nie OR.
• Wyniki są zgodne z Mapami Google, które czasami generują nieoczekiwane odpowiedziZERO_RESULTS. W niektórych przypadkach użycie autouzupełniania miejsc może dać lepsze wyniki. Więcej informacji znajdziesz w tym artykule.
• W przypadku każdego komponentu adresu podaj go w parametrze address lub w filtrze components, ale nie w obu tych elementach jednocześnie. Podanie tych samych wartości w obu przypadkach może spowodować ZERO_RESULTS.

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

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 geokodowania dla miejscowości „Santa Cruz” z components=country:ES zwraca Santa Cruz de Tenerife na Wyspach Kanaryjskich 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 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"
}

Możesz tworzyć prawidłowe zapytania bez parametru adresu, używając filtra components. (Podczas geokodowania pełnego adresu parametr address jest wymagany, jeśli żądanie zawiera nazwy i numery 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"
}