Żą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 prośbie 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 w formacie 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 pionowym (|). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podano parametr address. Każdy element w filtrze komponentów składa się z pary component:value i pełną rezygnuje z wyników geokodowania. Poniżej znajdziesz więcej informacji o filtrowaniu komponentów.

Aby uzyskać więcej informacji, zapoznaj się z najczęstszymi pytaniami.

Parametry opcjonalne w prośbie o geokodowanie:

  • bounds – pole ograniczające widok, w którym mają być wyświetlane wyniki geokodowania. Ten parametr będzie tylko wpływać na wyniki geokodowania, a 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, więc może ona nie być pełna.
    • 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, który jest 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 zwróconych przez interfejs API oraz na kolejność ich wyświetlania. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty nazw 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 w zależności od 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 o odpowiedź na zapytanie dotyczące adresu „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 dotyczące żądania. Poniżej znajdziesz kod stanu.
  • "results" zawiera tablicę z gekodowanymi 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. Zapoznaj się z artykułem Parsowanie XML za pomocą XPath, aby poznać zalecane wzorce projektowania na potrzeby przetwarzania danych wyjściowych.

  • Wyniki XML są zawijane w element główny <GeocodeResponse>.
  • W pliku JSON wpisy z większą liczbą elementów są oznaczone tablicami w liczbie mnogim (types), a w pliku XML – elementami w liczbie pojedynczym (<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 opcji:
    • 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 naprawić, 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.
  • "INVALID_REQUEST" zazwyczaj oznacza, ż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 geokodowania może się pojawić 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 (w formacie JSON). Nawet jeśli geokoder nie zwróci żadnych wyników (np. gdy adres nie istnieje), zwróci pusty tablicę results. (odpowiedzi XML mogą zawierać 0 lub więcej elementów <result>).

Typowy wynik zawiera te pola:

  • Tablica types[] wskazuje typ zwróconego wyniku. Ten tablicowy zawiera co najmniej 1 tag, który identyfikuje typ atrybutu zwróconego w wyniku. Na przykład geokod „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co oznacza, że jest to jednostka polityczna. Jeśli nie ma żadnych znanych typów dla danego elementu adresu, komponenty mogą mieć pusty tablice types. 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 dla stanu Alaska może mieć long_name „Alaska” i short_name „AK” za pomocą 2-literowego skrótu pocztowego.

    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, poza tymi, które są uwzględnione w formatted_address. Aby pobrać wszystkie jednostki polityczne zawierające określony adres, użyj 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_components zależ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 maksymalnie 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 szerokość geograficzną i długość geograficzną po geokodowaniu. 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" oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji dokładne do adresu ulicy.
      • "RANGE_INTERPOLATED" wskazuje, ż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. łamany (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. 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 ograniczający prostokąt, który może w pełni zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanym wymiarom widoku. (np. 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 plusowy, 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 do ulicy Henry Street i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, usługa geokodowania może zaproponować alternatywny adres. Sugestie 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ć 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.
Pole navigation_points w odpowiedzi na geokodowanie zawiera listę punktów, które są przydatne do nawigacji do danego miejsca. W szczególności powinny one służyć jako punkty początkowe lub końcowe podczas wyznaczania trasy na sieci drogowej do lub z danego miejsca. Każdy punkt nawigacyjny zawiera te wartości:
  • location zawiera szerokość geograficzną i długość geograficzną punktu nawigacyjnego. Ta lokalizacja będzie zawsze bardzo blisko sieci drogowej i stanowi idealny punkt początkowy lub końcowy nawigacji do i z danego miejsca. Punkt jest celowo przesunięty od osi drogi, aby wyraźnie zaznaczyć, po której stronie drogi znajduje się dane miejsce.
  • restricted_travel_modes to lista trybów podróży, w których punkt nawigacji jest niedostępny:
    • "DRIVE" to tryb podróży odpowiadający wskazówkom dojazdu.
    • "WALK" to środek transportu odpowiadający wskazówkom dojścia pieszo.

Typy adresów i typy ich komponentów

Tablica types[] w wyniku wskazuje typ adresu. Przykłady typów adresów to adres ulicy, kraj lub podmiot polityczny. W elementach address_components[] znajduje się też tablica types[], która wskazuje typ każdej części adresu. Przykłady: numer ulicy lub kraj. (poniżej znajdziesz pełną listę typów). Adresy mogą być różnych typów. Typy mogą być uznawane za „tagi”. Wiele miast jest np. oznaczonych typem political i locality.

Geokoder obsługuje i zwraca te typy w obiektach typu address type i address component type:

  • street_address oznacza dokładny adres ulicy.
  • route wskazuje nazwaną trasę (np. „US 101”).
  • intersection wskazuje główne skrzyżowanie, zwykle dwóch głównych dróg.
  • political oznacza podmiot polityczny. Zwykle ten typ wskazuje poligon administracji cywilnej.
  • 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 czwarty poziom podmiotu cywilnego 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 zarejestrowaną jednostkę polityczną miasta lub miasteczka.
  • sublocality oznacza jednostkę cywilną pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji może być używany 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 wskazuje zakodowany identyfikator lokalizacji, który jest wyprowadzony z szerokości i długości geograficznej. 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, aby ułatwić nawigację.
  • point_of_interest wskazuje nazwane miejsce docelowe.
  • parking oznacza parking lub parking wielopoziomowy.
  • post_box wskazuje konkretny skrytka pocztowa.
  • 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 domu.
  • 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 ukośnika (|) 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, który definiuje prostokąt ograniczający w 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 (krajowa domena 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 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 główna aplikacja Mapy Google została oficjalnie udostępniona. Pamiętaj, że ustawienie preferencji preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną istnieją bardziej odpowiednie 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"
}

Żądanie geokodowania „Toledo” z 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 interfejsu Geocoding API mogą być zwracane 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 pionową kreską (|). Wartości filtra obsługują te same metody poprawiania pisowni i częściowego dopasowywania 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ć, to:

  • 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ą mieć wpływ 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 o filtrowaniu 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 interpretuje te filtry jako filtry typu 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. Więcej informacji znajdziesz w tych odpowiedziach 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 parametrem 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 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"
}