Żądanie geokodowania i odpowiedź

Żądanie

Żądanie Geocoding API ma następującą postać:

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 JavaScript Object Notation (JSON);
  • xml oznacza dane wyjściowe w formacie XML

Wymagane jest HTTPS.

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

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

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

Wymagane parametry w prośbie o geokodowanie:

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

  • W żądaniu musisz podać wartość address lub components lub obie te wartości:

    • address – adres ulicy lub kod Plus Code, który chcesz zgeokodować. Określ adresy zgodnie z formatem używanym przez krajową pocztę danego kraju. Należy unikać dodatkowych elementów adresu, takich jak nazwy firm czy numery pokoi, apartamentów lub pięter. Elementy adresu ulicy powinny być rozdzielone spacjami (tutaj zapisane w sposób ujęty w składnie adresu URL: %20): 
      address=24%20Sussex%20Drive%20Ottawa%20ON
       Formatuj kody plusa w ten sposób (znaki plusa są zastępowane w adresie URL przez %2B, a spacje przez %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 kod lokalny o długości co najmniej 6 znaków z wyraźną lokalizacją (CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).
    • components – filtr komponentów z elementami rozdzielonymi znakiem ukośnika (|). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podano address. Każdy element w filtrze komponentów składa się z pary component:value i pełną rezygnuje z wyników geokodowania. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.

Więcej informacji znajdziesz w sekcji Najczęstsze pytania.

Parametry opcjonalne w prośbie o geokodowanie:

  • bounds – pole ograniczające widocznego obszaru, w którym wyniki geokodowania mają być bardziej widoczne. Ten parametr będzie miał wpływ na wyniki geokodowania, ale nie będzie ich w pełni ograniczał. (Więcej informacji znajdziesz poniżej w sekcji Uwzględnianie wielkości widoku).
  • language – język, w którym mają być wyświetlane wyniki.
    • Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, dlatego 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 domyślnego języka domeny, z której wysłano żądanie.
    • Geokoder dokłada wszelkich starań, aby podać adres ulicy czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby to osiągnąć, zwraca adresy ulicy w języku lokalnym, transliterowane do postaci zrozumiałej dla użytkownika w odpowiednim języku. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie elementy adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego elementu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder stosuje najbliższe dopasowanie.
    • Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz na ich kolejność. Geokodownik 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 słowa utca i tér to synonimy słowa „ulica” w języku węgierskim.
  • region – kod regionu podany jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Ten parametr będzie tylko wpływać na wyniki geokodowania, a nie je w pełni ograniczać. (więcej informacji znajdziesz poniżej w sekcji Uwzględnianie regionów). Parametr ten może też wpływać na wyniki na podstawie obowiązujących przepisów.
  • components – filtr komponentów z elementami rozdzielonymi znakiem pionowym (|). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera znaku address. Każdy element w filtrze komponentów składa się z pary component:value i pełną rezygnuje z wyników z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
  • extra_computations – użyj tego parametru, aby określić w odpowiedzi te dodatkowe funkcje: Aby włączyć kilka z tych funkcji w ramach tego samego żądania interfejsu API, dodaj parametr extra_computations w żądaniu dla każdej funkcji, na przykład: 
    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 z zapytaniem o adres „1600 Amphitheatre Parkway, Mountain View, CA”.

To żądanie demonstruje użycie flagi output w pliku JSON:

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

To żądanie demonstruje 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 formacie JSON i XML, kliknij karty poniżej.

JSON

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

Odpowiedź JSON zawiera 2 elementy rdzeniowe:

  • "status" zawiera metadane żądania. Poniżej znajdziesz kod stanu.
  • "results" zawiera tablicę z geokodowanymi informacjami o adresie i informacjami geometrycznymi.

W przypadku wyszukiwania adresów zwracany jest zwykle tylko 1 element tablicy "results", ale jeśli zapytania dotyczące adresu są niejednoznaczne, geokoder może zwrócić kilka wyników.

XML

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

Pamiętaj, że odpowiedź XML składa się z jednego elementu <GeocodeResponse> i 2 elementów najwyższego poziomu:

  • <status> zawiera metadane żądania. Poniżej znajdziesz kody stanu.
  • co najmniej 0 elementów <result>, z których każdy zawiera pojedynczy zbiór informacji o adresie z geokodowaniem i geometrii;

Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Z tego powodu zalecamy użycie flagi wyjściowej json jako preferowanej, chyba że usługa z jakiegoś powodu wymaga flagi xml. Przetwarzanie drzew XML wymaga też pewnej ostrożności, aby odwoływać się do odpowiednich węzłów i elementów. Więcej informacji o zalecanych wzorach projektowania do przetwarzania danych wyjściowych znajdziesz w artykule Parsowanie XML za pomocą XPath.

  • Wyniki XML są zawijane w element główny <GeocodeResponse>.
  • W pliku JSON wpisy z większą liczbą elementów są oznaczone tablicami w liczbie mnogiej (types), a w pliku XML – elementami w liczbie pojedynczej (<type>).
  • Puste elementy są wskazywane przez puste tablice w JSON, ale przez brak takiego elementu w XML. Odpowiedź, która nie zwraca żadnych wyników, zwróci pustą tablicę results w formacie JSON, ale nie będzie zawierać elementów <result> w formacie XML.

Kody stanu

Pole "status" w obiekcie odpowiedzi geokodowania zawiera stan żądania i może zawierać informacje 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ł pomyślnie przeanalizowany i zwrócono co najmniej 1 geokod.
  • "ZERO_RESULTS" oznacza, że geokodowanie się udało, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał nieistniejący adres address.
  • OVER_DAILY_LIMIT oznacza dowolną z tych wartości:
    • Brak klucza interfejsu API lub jest on nieprawidłowy.
    • Na Twoim koncie nie włączono płatności.
    • Przekroczono ustalony przez Ciebie limit wykorzystania.
    • podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność);

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

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

Komunikaty o błędach

Jeśli geokoder zwróci kod stanu inny niż OK, w obiekcie odpowiedzi usługi geokodowania może się pojawić dodatkowe pole error_message. To pole zawiera więcej szczegółowych informacji o przyczynach danego kodu stanu.

Wyniki

Gdy geokoder zwraca wyniki, umieszcza je w tablicy results (JSON). Nawet jeśli geokoder nie zwróci żadnych wyników (np. gdy adres nie istnieje), zwróci pustą tablicę results. (odpowiedzi XML mogą składać się z zera lub większej liczby elementów <result>).

Typowy wynik zawiera te pola:

  • Tablica types[] wskazuje typ zwróconego wyniku. Ten tablicowy zbiór zawiera co najmniej 1 znacznik, który identyfikuje typ zwracanej w wyniku funkcji. Na przykład geokod „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co oznacza, że jest to jednostka polityczna. Komponenty mogą mieć pusty tablice typów, jeśli nie ma znanych typów dla danego komponentu adresu. W razie potrzeby interfejs API może dodawać nowe wartości typu. Więcej informacji znajdziesz w artykule Typy adresów i ich elementy.
  • formatted_address to ciąg tekstowy zawierający adres tej lokalizacji w zrozumiałej dla człowieka formie.

    Często jest to adres pocztowy. 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 1 elementu adresu. Na przykład adres „111 8th Avenue, Nowy Jork, NY” składa się z tych elementów: „111” (numer domu), „8th Avenue” (ulica), „Nowy Jork” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu za pomocą kodu. Zamiast tego użyj poszczególnych elementów adresu, które są zawarte w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.

  • address_components[] to tablica zawierająca oddzielne komponenty stosowane w przypadku tego adresu.

    Każdy element adresu zawiera zwykle te pola:

    • types[] to tablica wskazująca typ elementu adresu. Zobacz listę obsługiwanych typów.
    • long_name to pełny tekst opisu lub nazwa komponentu adresu zwróconego przez geokoder.
    • short_name to skrócona nazwa tekstowa składnika adresu (jeśli jest dostępna). Na przykład element adresu w przypadku stanu Alaska może mieć long_name „Alaska” i short_name „AK” (2-literowy skrót pocztowy).

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

    • Tablica elementów adresu może zawierać więcej elementów niż formatted_address.
    • Tablica niekoniecznie zawiera wszystkie podmioty polityczne, które zawierają adres, z wyjątkiem tych, które są uwzględnione w tablicy formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, należy użyć odwrotnego geokodowania, przekazując szerokość/długość geograficzną adresu jako parametr żądania.
    • Nie ma gwarancji, że format odpowiedzi będzie taki sam w przypadku różnych żądań. W szczególności liczba address_componentszależy od adresu, którego dotyczy żądanie, i może się z czasem zmieniać w przypadku tego samego adresu. Element 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 parsowaniu odpowiedzi.

  • postcode_localities[] to tablica zawierająca do 100 miejscowości zawartych w kodzie pocztowym. Jest to możliwe tylko wtedy, gdy wynik to kod pocztowy zawierający wiele miejscowości.
  • geometry zawiera te informacje:
    • location zawiera geokodowaną szerokość geograficzną i długość geograficzną. W przypadku zwykłego wyszukiwania adresu to pole jest zwykle najważniejsze.

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

      • "ROOFTOP" wskazuje, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji dokładne do adresu ulicy.
      • "RANGE_INTERPOLATED" oznacza, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Interpolowane wyniki są zwykle zwracane, gdy kody geograficzne dachów są niedostępne dla adresu ulicznego.
      • "GEOMETRIC_CENTER" oznacza, że zwrócony wynik to środek geometryczny wyniku, np. wielolinii (np. ulicy) lub wielokąta (regionu).
      • "APPROXIMATE" oznacza, że zwrócony wynik jest przybliżony.
    • viewport zawiera zalecany widoczny obszar do wyświetlania zwróconego wyniku. Jest on określony przez 2 wartości szerokości i długości geograficznej, które definiują kąt southwest oraz kąt northeast narożnika obszaru ograniczonego widocznego obszaru. Zazwyczaj widok strony służy do kadrowania wyniku podczas wyświetlania go użytkownikowi.
    • bounds (opcjonalnie zwracany) przechowuje prostokąt ograniczający, który może w pełni zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanej przez Google przeglądarce. (na przykład San Francisco obejmuje wyspy Farallon, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być uwzględniane w widoku).
  • plus_code (patrz Open Location Code i kod plus) to zakodowany punkt odniesienia lokalizacji wyprowadzony ze współrzędnych szerokości i długości geograficznej, który reprezentuje obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m na 14 m na równiku) lub mniejszy. Kody Plus Code mogą zastępować adresy w miejscach, w których nie ma adresów (gdzie budynki nie są numerowane, a ulice nie mają nazw). Interfejs API nie zawsze zwraca kodów plus.

    Gdy usługa zwróci kod plus, będzie on sformatowany jako kod globalny i kod złożony:

    • global_code to 4-znakowy kod obszaru i 6-znakowy kod lokalny (849VCWC8+R9).
    • compound_code to kod lokalny o długości co najmniej 6 znaków z wyraźną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści za pomocą programu.
    W przypadku, gdy jest to możliwe, interfejs API zwraca zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik znajduje się w odległym miejscu (np. na oceanie lub pustyni), zwracany może być 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. Możesz sprawdzić pierwotną prośbę, aby sprawdzić, czy nie zawiera ona literówek ani niepełnego adresu.

    Częściowe dopasowania występują najczęściej w przypadku adresów ulic, które nie istnieją w miejscowości podanej w żądaniu. W przypadku dopasowania do co najmniej 2 lokalizacji w tej samej miejscowości mogą być zwracane również częściowe dopasowania. Na przykład wyszukiwanie „Hillpar St, Bristol, UK” zwróci dopasowanie częściowe zarówno do Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, usługa geokodowania może zaproponować alternatywny adres. Propozycje wygenerowane w ten sposób będą też oznaczone jako częściowe dopasowanie.

  • place_id to unikalny identyfikator, którego można używać w innych interfejsach API Google. Możesz na przykład użyć parametru place_id w żądaniu Places API, aby uzyskać szczegóły dotyczące lokalnego przedsiębiorstwa, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zapoznaj się z omówieniem identyfikatora miejsca.

Typy adresów i typy elementów adresu

Tablica types[] w wyniku wskazuje typ adresu. Przykłady typów adresów to adres ulicy, kraj lub jednostka polityczna. W elementach address_components[] znajduje się też tablica types[], która wskazuje typ poszczególnych części adresu. Przykłady: numer domu lub kraj. (poniżej znajdziesz pełną listę typów). Adresy mogą mieć różne typy. Typy mogą być uznawane za „tagi”. Na przykład wiele miast ma tagi typu political i locality.

Geokodowanie obsługuje i zwraca te typy w tablicach typów adresów i typów elementów adresu:

  • street_address oznacza dokładny adres.
  • route wskazuje nazwaną trasę (np. „US 101”).
  • intersection wskazuje główne skrzyżowanie, zwykle 2 głównych dróg.
  • political oznacza podmiot polityczny. Zwykle ten typ wskazuje wielokąt administracyjny.
  • country wskazuje podmiot polityczny o charakterze krajowym i zwykle jest najwyższym typem zwracanym przez geokoder.
  • administrative_area_level_1 wskazuje podmiot prawny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany. Nie wszystkie kraje mają te poziomy administracyjne. W większości przypadków krótkie nazwy administrative_area_level_1 będą bardzo zbliżone do podziałów ISO 3166-2 i innych powszechnie używanych list. Nie jest to jednak gwarantowane, ponieważ nasze wyniki geokodowania opierają się na różnych sygnałach i danych dotyczących lokalizacji.
  • administrative_area_level_2 oznacza jednostkę prawną drugiego rzędu na poziomie niższym niż kraj. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_3 oznacza podmiot prawny trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_4 oznacza podmiot prawny czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_5 wskazuje podmiot prawny piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_6 wskazuje podmiot prawny szóstego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
  • administrative_area_level_7 wskazuje podmiot prawny siódmego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
  • colloquial_area wskazuje powszechnie używaną nazwę alternatywną podmiotu.
  • locality oznacza zarejestrowany podmiot polityczny miasta.
  • sublocality oznacza jednostkę cywilną pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji może być wymagany jeden z dodatkowych typów: sublocality_level_1 do sublocality_level_5. Każdy poziom podregionu jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny.
  • neighborhood oznacza nazwę dzielnicy.
  • premise wskazuje nazwę lokalizacji, zwykle budynku lub grupy budynków o wspólnej nazwie.
  • subpremise wskazuje element, który można zidentyfikować na poziomie niższym niż budynek, na przykład mieszkanie, lokal lub apartament.
  • plus_code oznacza zakodowany identyfikator lokalizacji, który jest wyprowadzony ze współrzędnych geograficznych. Kody Plus Code mogą zastępować adresy ulicy w miejscach, w których ich nie ma (gdzie budynki nie mają numerów lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
  • postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
  • natural_feature wskazuje charakterystyczny element przyrodniczy.
  • airport oznacza lotnisko.
  • park oznacza park o nazwie.
  • point_of_interest wskazuje nazwane miejsce docelowe. Zwykle są to znane obiekty lokalne, które nie pasują do żadnej innej kategorii, np. „Empire State Building” czy „Wieża Eiffla”.

Pusta lista typów wskazuje, że nie ma żadnych znanych typów dla danego elementu adresu, na przykład Lieu-dit we Francji.

Oprócz wymienionych powyżej elementy adresu mogą obejmować typy wymienione poniżej. Ta lista nie jest wyczerpująca i może ulec zmianie.

  • floor wskazuje piętro adresu budynku.
  • establishment zwykle oznacza miejsce, które nie zostało jeszcze skategoryzowane.
  • landmark wskazuje miejsce w pobliżu, które służy jako punkt odniesienia do ułatwienia nawigacji.
  • point_of_interest wskazuje nazwane miejsce docelowe.
  • parking oznacza parking lub parking wielopoziomowy.
  • post_box oznacza konkretny skrypt pocztowy.
  • postal_town wskazuje grupę obszarów geograficznych, takich jak locality i sublocality, używaną do adresów pocztowych w niektórych krajach.
  • room wskazuje pokój w budynku.
  • street_number oznacza dokładny numer budynku.
  • bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, kolejowego lub przystanku transportu publicznego.

Wpływ widocznego obszaru

W żądaniu geokodowania możesz zlecić usłudze geokodowania preferowanie wyników w danym widoku (wyrażonym jako ograniczony obszar). Aby to zrobić, ustaw parametr bounds w adresie URL żądania.

Parametr bounds definiuje współrzędne szerokości i długości geograficznej narożników południowo-zachodniego i północno-wschodniego tego prostokąta ograniczającego, używając znaku kreski pionowej (|) do oddzielania współrzędnych.

Na przykład geokodowanie „Washington” zwykle zwraca stan amerykański: 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"
}

Jednak dodanie argumentu bounds definiującego prostokąt ograniczający wokół północno-wschodniej części USA powoduje, że 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"
}

Uwzględnianie regionu

W żądaniu geokodowania możesz polecić usłudze geokodowania zwrócenie wyników 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 wyjątkami. Na przykład ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której oficjalnie udostępniono główną aplikację Mapy Google. Pamiętaj, że ustawienie preferencji preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną istnieją bardziej trafne wyniki, mogą one zostać uwzględnione.

Na przykład geokodowanie „Toledo” zwraca ten wynik, ponieważ domyślna domena 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"
}

Prośba o geokodowanie „Toledo” z region=es (Hiszpania) zwróci miasto w Hiszpanii.

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 wyszukiwania adresu ograniczone do określonego obszaru. Ograniczenie możesz określić za pomocą filtra components. Filtr składa się z listy par component:value rozdzielonych znakiem pionowym (|). Wartości filtrów obsługują te same metody poprawiania pisowni i częściowego dopasowania co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie do filtra komponentu, odpowiedź będzie zawierać pole partial_match.

components, które można filtrować:

  • postal_code pasuje do postal_code i postal_code_prefix.
  • country pasuje do nazwy kraju lub dwuliterowego kodu kraju ISO 3166-1. Interfejs API stosuje standard ISO do definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Na wyniki mogą wpływać te components, ale nie będą one egzekwowane:

  • 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 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 te filtry jako AND, a nie OR.
  • Wyniki są zgodne z Mapami Google, które czasami zwracają nieoczekiwane odpowiedzi.ZERO_RESULTS W niektórych przypadkach autouzupełnianie miejsc może przynieść lepsze wyniki. Aby dowiedzieć się więcej, zapoznaj się z tymi odpowiedziami na najczęstsze pytania.
  • W przypadku każdego elementu adresu podaj go w parametrze address lub w filtrze components, ale nie w obu tych miejscach. Podanie tych samych wartości w obu przypadkach może spowodować ZERO_RESULTS.

Geokodowanie adresu „High St, Hastings” z użyciem components=country:GBzwraca wynik w Hastings w Anglia, 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 lokalizacji „Santa Cruz” z components=country:ESzwraca 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ę wzajemnie 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 wysyłać prawidłowe zapytania bez parametru address, korzystając z 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"
}