Żądanie geokodowania i odpowiedź

Prośba

Żądanie do Geocoding API ma taką formę:

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

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

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

Protokół HTTPS jest wymagany.

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

W pozostałej części tej strony omówiono oddzielnie geokodowanie i odwrotne geokodowanie, ponieważ dla każdego typu żądania dostępne są inne parametry.

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

Parametry wymagane w żądaniu geokodowania:

  • address – adres lub kod plus, na który chcesz geokodować. Podaj adresy zgodnie z formatem używanym przez krajową usługę pocztową w danym kraju. Należy unikać dodatkowych elementów adresu, takich jak nazwy firm, lokale, lokale czy piętra. Elementy adresu pocztowego powinny być rozdzielone spacjami (w tym przypadku adresy URL ze zmianą znaczenia do %20): 
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Sformatuj kody plus w taki sposób, jak pokazano tutaj (znak plusa to %2B ze zmianą znaczenia, a spacje są znakami zmiany znaczenia do ciągu %20):
    • Kod globalny to 4-znakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9 to 849VCWC8%2BR9).
    • Kod złożony to co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).

    --OR--
    components – filtr komponentów z elementami rozdzielonymi pionową kreską (|). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podano address. Każdy element filtra komponentów składa się z pary component:value. W pełni ogranicza wyniki generowane przez geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
  • key – klucz interfejsu API aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

Więcej informacji znajdziesz w najczęstszych pytaniach.

Parametry opcjonalne w żądaniu geokodowania:

  • bounds – ramka ograniczająca widocznego obszaru, w którym lepiej widać odchylenie wyników geograficznych. Ten parametr ma wpływ tylko na wyniki generowane przez geokodera, a nie na pełne ograniczanie wyników. Więcej informacji znajdziesz w sekcji Promowanie widocznego obszaru poniżej.
  • language – język, w którym mają być zwracane wyniki.
    • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być pełna.
    • Jeśli language nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka ojczystego domeny, z której wysłane jest żądanie.
    • Geokoder dokłada wszelkich starań, aby podać czytelny adres zarówno dla użytkownika, jak i lokalnego. W tym celu funkcja zwraca adresy w języku lokalnym, transliterację do skryptu zrozumiałego dla użytkownika (w razie potrzeby) z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. Komponenty adresu są zwracane w tym samym języku, który jest wybierany z 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 zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność ich zwracania. Geokoder interpretuje skróty różnie w zależności od języka, np. rodzaje skrótów nazw 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 synonimy odpowiednio ulicy i kwadratu w języku węgierskim.
  • region – kod regionu, podany jako dwuznakowa wartość domeny ccTLD („domena najwyższego poziomu”). Ten parametr ma wpływ tylko na wyniki generowane przez geokodera, a nie na pełne ograniczanie wyników. (Więcej informacji znajdziesz poniżej w sekcji Promowanie regionu). Parametr może również wpływać na wyniki zgodnie z obowiązującym prawem.
  • components – filtr komponentów z elementami rozdzielonymi pionową kreską (|). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera elementu address. Każdy element filtra komponentów składa się z pary component:value. W pełni ogranicza wyniki generowane przez geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.

Odpowiedzi

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

W tym przykładzie interfejs Geocoding API wysyła żądanie odpowiedzi json na zapytanie o identyfikator miejsca „ChIJeRpOeF67j4AR9ydy_PIzPuM”. Ten identyfikator miejsca dotyczy budynku przy ulicy 1600 Amphitheatre Parkway, Mountain View, CA.

To żądanie pokazuje, jak używać flagi JSON output:

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

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

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

Wybierz karty poniżej, aby zobaczyć przykładowe odpowiedzi JSON i XML.

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

Zwróć uwagę, że odpowiedź JSON zawiera 2 elementy główne:

  • "status" zawiera metadane żądania. Zobacz Kody stanu poniżej.
  • "results" zawiera tablicę geokodowanych danych adresowych i danych geometrycznych.

Podczas wyszukiwania adresów zwracany jest tylko jeden wpis w tablicy "results", choć geokoder może zwrócić kilka wyników,gdy zapytania o adresy są niejednoznaczne.

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>

Zwróć uwagę, że odpowiedź XML składa się z 1 elementu <GeocodeResponse> i 2 elementów najwyższego poziomu:

  • <status> zawiera metadane żądania. Zobacz Kody stanu poniżej.
  • 0 lub więcej elementów <result>, z których każdy zawiera zbiór geokodowanych danych adresowych i danych geometrycznych.

Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Dlatego zalecamy użycie flagi json jako preferowanego wyniku, chyba że usługa z jakiegoś powodu wymaga xml. Dodatkowo przetwarzanie drzew XML wymaga pewnej ostrożności, aby odwoływać się do odpowiednich węzłów i elementów. Niektóre zalecane wzorce projektowe przetwarzania danych wyjściowych znajdziesz w artykule o analizowaniu kodu XML za pomocą XPath.

  • Wyniki XML są zawarte w elemencie głównym <GeocodeResponse>.
  • Plik JSON oznacza wpisy z wieloma elementami za pomocą tablic liczby mnogiej (types), a XML – przy użyciu wielu elementów pojedynczych (<type>).
  • Puste elementy są oznaczone w formacie JSON przez puste tablice, ale przez brak jakiegokolwiek takiego elementu w pliku XML. Odpowiedź, która nie generuje żadnych wyników, zwróci pustą tablica results w formacie JSON, ale nie zwrócimy na przykład elementów <result> w pliku XML.

Kody stanu

Pole "status" w obiekcie odpowiedzi Geocoding zawiera stan żądania i może zawierać informacje debugowania, które mogą pomóc w ustaleniu, 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ócony co najmniej jeden geokod został zwrócony.
  • "ZERO_RESULTS" oznacza, że geokod został przetworzony, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder został przekazany z kodem, który nie istnieje: address.
  • OVER_DAILY_LIMIT oznacza:
    • Brak klucza interfejsu API lub jest on nieprawidłowy.
    • Płatności nie zostały włączone na Twoim koncie.
    • Nałożony przez Ciebie limit wykorzystania został przekroczony.
    • Podana forma płatności straciła ważność (np. wygasła karta kredytowa).

    Aby dowiedzieć się, jak rozwiązać ten problem, zapoznaj się z najczęstszymi pytaniami na temat Map.

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

Komunikaty o błędach

Gdy geokoder zwraca kod stanu inny niż OK, w obiekcie odpowiedzi Geocoding może znajdować się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach pojawienia się 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. jeśli adres nie istnieje), zwróci pustą tablicę results. (Odpowiedzi XML zawierają 0 lub więcej elementów <result>).

Typowy wynik zawiera te pola:

  • Tablica types[] wskazuje typ zwracanego wyniku. Ta tablica zawiera zestaw tagów zawierających 0 lub więcej tagów identyfikujących typ cechy zwracanej w wyniku. Na przykład kod geograficzny „Chicago” zwraca wartość „locality”, która wskazuje, że „Chicago” jest miastem, i zwraca też „polityczne”, które oznacza, że jest podmiotem politycznym. 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 dodać nowe wartości typu. Więcej informacji znajdziesz w artykule Typy adresów i komponenty adresów.
  • formatted_address to ciąg znaków zawierający zrozumiały dla człowieka adres tej lokalizacji.

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

    Sformatowany adres składa się logicznie z co najmniej jednego komponentu adresu. Na przykład adres „111 8th Avenue, Nowy Jork, NY” składa się z tych komponentów: „111” – numer domu, „8 Aleja” (trasa), „Nowy Jork” – miasto i „NY” (stan w USA).

    Nie analizuj automatycznie sformatowanego adresu. Zamiast tego użyj poszczególnych komponentów adresu, które zawiera odpowiedź interfejsu API oprócz sformatowanego pola adresu.

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

    Każdy komponent adresu zwykle zawiera te pola:

    • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
    • long_name to pełny opis lub nazwa komponentu adresu zwracana przez geokodera.
    • short_name to skrócona nazwa tekstowa komponentu adresu (jeśli jest dostępna). Na przykład składnik adresu dla stanu Alaska może mieć atrybut long_name o nazwie „Alaska” i zasadę short_name o nazwie „AK” z dwuliterowym skrótem pocztowym.

    Zwróć uwagę na te informacje o tablicy address_components[]:

    • Tablica komponentów adresu może zawierać więcej komponentów niż formatted_address.
    • Tablica nie musi zawierać wszystkich jednostek politycznych z adresem (z wyjątkiem tych uwzględnionych w elemencie formatted_address). Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj odwrotnego geokodowania, przesyłając szerokość i długość geograficzną adresu jako parametr w żądaniu.
    • Nie ma gwarancji, że format odpowiedzi pozostanie taki sam między żądaniami. Liczba address_components różni się w zależności od żądanego adresu i może się z czasem zmienić dla tego samego adresu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmieniać. Konkretnego komponentu może brakować w późniejszej odpowiedzi.

    Aby obsługiwać tablicę komponentów, przeanalizuj odpowiedź i wybierz odpowiednie wartości za pomocą wyrażeń. Zapoznaj się z przewodnikiem na temat analizowania odpowiedzi.

  • postcode_localities[] to tablica oznaczająca maksymalnie 100 miejscowości w danym kodzie pocztowym. Jest ona widoczna tylko wtedy, gdy wynik to kod pocztowy zawierający kilka regionów.
  • geometry zawiera te informacje:
    • location zawiera geokodowaną wartość szerokości i długości geograficznej. W przypadku normalnego wyszukiwania adresów to pole jest zazwyczaj najważniejsze.

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

      • Wartość "ROOFTOP" wskazuje, że zwrócony wynik to dokładny geokod, w przypadku którego informacje o lokalizacji są precyzyjne z dokładnością do adresu.
      • "RANGE_INTERPOLATED" wskazuje, że wynik to przybliżenie (zwykle na drodze) z interpolacją między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachowe są niedostępne dla adresu.
      • "GEOMETRIC_CENTER" wskazuje, że zwrócony wynik jest środkiem geometrycznym wyniku, np. linia łamana (na przykład ulica) lub wielokątem (region).
      • "APPROXIMATE" oznacza, że zwrócony wynik jest przybliżony.
    • viewport zawiera zalecany widoczny obszar do wyświetlania zwracanego wyniku, określony w postaci 2 wartości szerokości i długości geograficznej wyznaczających narożnik southwest i northeast ramki ograniczającej widoczny obszar. Ogólnie widoczny obszar służy do umieszczania wyniku w ramce podczas wyświetlania go użytkownikowi.
    • bounds (zwrócony opcjonalnie) przechowuje ramkę ograniczającą, która może w całości zawierać zwrócony wynik. Pamiętaj, że te progi mogą się różnić od zalecanego widocznego obszaru. (Na przykład San Francisco obejmuje wyspy Farallona, które technicznie są częścią miasta, ale prawdopodobnie nie powinny być zwracane w widocznym obszarze).
  • plus_code (zobacz Open Location Code i kody plus) to zakodowane odniesienie do lokalizacji, pobierane ze współrzędnych geograficznych, które reprezentuje obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m x 14 m na równiku) lub mniejsze. Kody Plus Code mogą zastąpić adresy ulic w miejscach, gdzie adresy nie istnieją (gdzie budynki nie mają numerów lub ulic nie mają nazw). Interfejs API nie zawsze zwraca kody plus.

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

    • global_code to 4-znakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).
    • compound_code to co najmniej 6-znakowy 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, chociaż był w stanie dopasować część żądanego adresu. Warto sprawdzić pierwotne żądanie pod kątem błędów pisowni lub niekompletnego adresu.

    Dopasowania częściowe najczęściej występują w przypadku adresów, których nie ma w rejonie podanym w żądaniu. Dopasowania częściowe mogą być również zwracane, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej okolicy. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie dla Henry Street i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie wpisany komponent adresu, usługa geokodowania może zasugerować alternatywny adres. Sugestie aktywowane w ten sposób będą również oznaczane jako dopasowania częściowe.

  • 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ć informacje o firmie lokalnej, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Przeczytaj omówienie identyfikatora miejsca.

Typy adresów i typy komponentów adresu

Tablica types[] w wyniku wskazuje typ adresu. Przykładowe typy adresów to adres, kraj lub podmiot polityczny. W address_components[] znajduje się też tablica types[], która wskazuje typ każdej części adresu. Może to być na przykład numer domu lub numer domu. Poniżej znajdziesz pełną listę typów. Adresy mogą mieć kilka typów. Te typy mogą być uznawane za „tagi”. Na przykład wiele miast jest oznaczonych tagami political i locality.

Geokoder obsługuje i zwraca te typy zarówno w tablicach typu adresu, jak i typów komponentu adresu:

  • street_address wskazuje dokładny adres.
  • route wskazuje nazwaną trasę (np. „US 101”).
  • intersection to główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.
  • political oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt związany z administracją cywilną.
  • country wskazuje krajowy podmiot polityczny i zazwyczaj jest to najwyższy typ kolejności zwracany przez geokodera.
  • administrative_area_level_1 oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to stany. Nie we wszystkich krajach obowiązują te poziomy administracyjne. W większości przypadków krótkie nazwy admin_area_level_1 są ściśle dopasowane do podziałów według normy ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy jednak zagwarantować, że wyniki z kodowania geograficznego są uzależnione od różnych sygnałów i danych o lokalizacji.
  • administrative_area_level_2 oznacza podmiot cywilny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_3 oznacza podmiot cywilny trzeciego poziomu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_4 oznacza podmiot cywilny czwartego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_5 oznacza podmiot cywilny piątego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_6 oznacza podmiot cywilny szóstego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_7 oznacza podmiot cywilny siódmego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • colloquial_area wskazuje często używaną alternatywną nazwę encji.
  • locality oznacza miasto lub miejscowość, w której on działa.
  • sublocality wskazuje podmiot cywilny pierwszego rzędu poniżej danego rejonu. W przypadku niektórych lokalizacji może pojawić się jeden z dodatkowych typów: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
  • neighborhood wskazuje nazwę okolicy
  • premise oznacza nazwaną lokalizację, zwykle budynek lub zespół budynków o wspólnej nazwie
  • subpremise wskazuje element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle pojedynczy budynek w zbiorze budynków o wspólnej nazwie
  • plus_code to zakodowane odwołanie do lokalizacji pobrane na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastąpić adresy w miejscach, gdzie nie istnieją (gdzie budynki nie są numerowane lub nie mają nazw ulic). Więcej informacji znajdziesz na stronie https://plus.codes.
  • postal_code wskazuje kod pocztowy używany w danym kraju do adresowania przesyłek pocztowych.
  • natural_feature oznacza ważny obiekt naturalny.
  • airport wskazuje lotnisko.
  • park wskazuje park nazwany.
  • point_of_interest wskazuje nazwane miejsce. Są to zwykle ważne lokalne jednostki, których nie da się łatwo umieścić w innych kategoriach, np. „Empire State Building” lub „wieża Eiffla”.

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

Oprócz powyższych typów komponenty adresu mogą obejmować te typy. Ta lista nie jest pełna i może ulec zmianie.

  • floor wskazuje piętro adresu budynku.
  • establishment zwykle oznacza miejsce, które nie zostało jeszcze sklasyfikowane.
  • landmark wskazuje miejsce w pobliżu, które jest używane jako punkt odniesienia, aby ułatwić nawigację.
  • point_of_interest wskazuje nazwane miejsce.
  • parking oznacza parking lub obiekt parkingowy.
  • post_box oznacza konkretną skrytkę pocztową.
  • postal_town oznacza grupę obszarów geograficznych, np. locality i sublocality, używaną w adresach pocztowych w niektórych krajach.
  • room wskazuje pomieszczenie przypisane do danego adresu budynku.
  • street_number wskazuje dokładną ulicę i numer.
  • bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, pociągu lub transportu publicznego.

Promowanie widocznego obszaru

W żądaniu Geocoding możesz poinstruować usługę Geocoding, aby preferowała wyniki na danym obszarze (wyrażonym w ramce ograniczającej). Możesz to zrobić w ramach adresu URL żądania, ustawiając parametr bounds.

Parametr bounds określa współrzędne geograficzne południowo-zachodnich i północno-wschodnich narożników tej ramki ograniczającej, rozdzielając je pionową kreską (|).

Na przykład kod geograficzny dla hasła „Waszyngton” zwraca zwykle stan Waszyngton w USA:

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 ramkę ograniczającą wokół północno-wschodniej części Stanów Zjednoczonych spowoduje zwrócenie tego geokoda, który zwraca miasto Waszyngton, D.C.:

Prośba:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

Odpowiedź:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Promowanie regionu

W żądaniu Geocoding możesz poinstruować usługę Geocoding, aby przy użyciu parametru region zwracała wyniki uprzedzenia dotyczące konkretnego regionu. Ten parametr przyjmuje argument ccTLD (domena najwyższego poziomu kodu kraju) określający promowanie regionu. Większość kodów domen ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma ważnymi wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznacza to „Wielka Brytania i Irlandia Północna”).

Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której oficjalnie uruchomiono główną aplikację Map Google. Pamiętaj, że promowanie wyników preferuje tylko wyniki z konkretnej domeny. Jeśli bardziej trafne wyniki występują poza tą domeną, mogą zostać uwzględnione.

Na przykład kod geograficzny dla hasła „Toledo” zwraca ten wynik, ponieważ domyślną domeną interfejsu Geocoding API jest Stany Zjednoczone. Prośba:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Odpowiedź:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Żądanie geokodowania dla „Toledo” wysłane do użytkownika 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 dotyczące 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 filtrów obsługują te same metody poprawiania pisowni i dopasowania częściowego co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie dla filtra komponentów, odpowiedź będzie zawierać pole partial_match.

components, które można filtrować:

  • postal_code pasuje do wymiarów postal_code i postal_code_prefix.
  • country to nazwa kraju lub dwuliterowy kod kraju zgodny ze standardem ISO 3166-1. Interfejs API jest zgodny z normą ISO przy definiowaniu krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Te reguły components mogą być wykorzystywane do wpływania na wyniki, ale nie są wymuszane:

  • route to długa lub krótka nazwa trasy.
  • locality pasuje do typów locality i sublocality.
  • administrative_area pasuje do wszystkich poziomów (administrative_area).

Uwagi na temat filtrowania komponentów:

  • Nie powtarzaj tych filtrów komponentów w żądaniach, bo interfejs API zwróci wartość Invalid_request: country, postal_code, route
  • Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API zinterpretuje je jako operator ORAZ, a nie LUB.
  • Wyniki są zgodne z Mapami Google, co czasami powoduje nieoczekiwane odpowiedzi ZERO_RESULTS. W niektórych przypadkach korzystanie z autouzupełniania miejsc może przynieść lepsze wyniki. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania.
  • Każdy komponent adresu określ w parametrze address lub w filtrze components, ale nie w obu tych komponentach. Jeśli podasz te same wartości w obu miejscach, może się zdarzyć, że ZERO_RESULTS.

Geokod z hasłem „High St, Hastings” o wartości components=country:GB zwraca wynik w Hastings (Anglia), a nie w Hastings-On-Hudson (USA).

Prośba:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Odpowiedź:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Prośba o kod geokodu dla rejonu „Santa Cruz” z firmą components=country:ES zwraca Santa Cruz de Tenerife na hiszpańskich Wyspach Kanaryjskich.

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 określisz filtry, które wykluczają się nawzajem.

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

Za pomocą filtra components możesz tworzyć prawidłowe zapytania bez parametru address. W przypadku 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"
}