Żądanie geokodowania i odpowiedź

Prośba

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

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

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

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

Wymagany jest protokół HTTPS.

Niektóre parametry są wymagane, a inne opcjonalne. Standardowo w adresach URL parametry są oddzielane znakiem „&”.

W dalszej części tej strony oddzielnie opisujemy geokodowanie i odwrotne geokodowanie, ponieważ dla poszczególnych typów żądań dostępne są różne parametry.

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

Parametry wymagane w żądaniu geokodowania:

• address – adres lub kod plus, którego dane geograficzne chcesz przetworzyć na dane geograficzne. Podaj adresy w formacie używanym przez krajowy urząd pocztowy w danym kraju. Należy unikać dodatkowych elementów adresowych, takich jak nazwy firm, numer lokalu, lokalu lub piętra. Elementy adresu pocztowego powinny być rozdzielone spacjami (w tym przykładzie ze zmianą znaczenia w adresie URL w kodzie %20):

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

  Sformatuj kod plus w podany niżej sposób (znaki plus będą zawierały kod zmiany znaczenia w adresie URL, a spacje zawierają kod %20 ze znakami zmiany znaczenia w adresie URL):
  %2B
  • kod globalny to 4-znakowy kod kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9 to 849VCWC8%2BR9).
  • złożony kod to co najmniej 6-znakowy kod lokalny z konkretną lokalizacją (CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components– filtr komponentów z elementami oddzielonymi pionową kreską (|). Filtr komponentów jest też akceptowany jako parametr opcjonalny, jeśli podasz address. Każdy element w filtrze komponentów składa się z pary component:value i całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
• key – klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

Dodatkowe wskazówki znajdziesz w najczęstszych pytaniach.

Opcjonalne parametry w żądaniu Geocoding:

• bounds – ramka ograniczająca widocznego obszaru, w ramach której odchylane są wyniki geolokalizacji. Ten parametr będzie miał wpływ tylko na wyniki generowane przez geokoder, ale nie będzie go w pełni ograniczać. (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ć wyczerpująca.
  • 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 zostanie wysłane żądanie.
  • Geokoder stara się podać adres czytelny dla użytkowników i lokalnych osób. Aby osiągnąć ten cel, zwraca adresy w języku lokalnym, transliterację na skrypt, który w razie potrzeby może odczytać użytkownik, z zachowaniem preferowanego języka. Pozostałe adresy są zwracane w preferowanym języku. Wszystkie 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 zestaw wyników zwracanych przez interfejs API oraz na kolejność, w jakiej są one zwracane. Geokoder różnie interpretuje skróty w zależności od języka. Mogą to być np. skróty określające typy ulic lub synonimy, które mogą być prawidłowe w jednym języku, a w innym nie. Na przykład utca i tér to synonimy ulicy i kwadratu w języku węgierskim.
• region – kod regionu określony jako dwuznakowa wartość domeny ccTLD („domeny najwyższego poziomu”). Ten parametr będzie miał wpływ tylko na wyniki generowane przez geokoder, ale nie będzie go w pełni ograniczać. (Więcej informacji znajdziesz w sekcji Promowanie według regionu poniżej). Ten parametr może też wpływać na wyniki na podstawie obowiązujących przepisów.
• components – filtr komponentów, w którym elementy są oddzielone pionową kreską (|). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera address. Każdy element w filtrze komponentów składa się z pary component:value i całkowicie ogranicza wyniki z geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
• extra_computations – jedyna dozwolona wartość w przypadku tego parametru to ADDRESS_DESCRIPTORS. Więcej informacji znajdziesz w artykule o deskryptorach adresów.

Odpowiedzi

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

W tym przykładzie interfejs Geocoding API żąda odpowiedzi json na zapytanie na adres „1600 Amphitheatre Parkway, Mountain View, CA”.

To żądanie demonstruje użycie flagi output 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 output XML:

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

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

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

Kody stanu

Pole "status" w obiekcie odpowiedzi Geocoding zawiera stan żądania i może zawierać informacje na potrzeby 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 błędy. Adres został przeanalizowany i zwrócono co najmniej 1 kod geograficzny.
• "ZERO_RESULTS" oznacza, że geokod został poprawnie użyty, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder został przekazany do nieistniejącego elementu address.
• OVER_DAILY_LIMIT oznacza dowolne z tych wartości:
  • Brak klucza interfejsu API lub jest on nieprawidłowy.
  • Płatności nie zostały włączone na Twoim koncie.
  • Przekroczono nałożony samodzielnie limit wykorzystania.
  • Podana forma płatności straciła ważność (na przykład wygasła karta kredytowa).

  Zapoznaj się z najczęstszymi pytaniami dotyczącymi Map, aby dowiedzieć się, jak rozwiązać ten problem.

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

Komunikaty o błędach

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

Wyniki

Gdy geokoder zwróci wyniki, umieszcza je w tablicy results (JSON). Nawet jeśli geokoder nie zwróci żadnych wyników (np. gdy adres nie istnieje), i tak zwróci pustą tablicę results. (Odpowiedzi XML zawierają zero lub więcej elementów <result>).

Typowy wynik zawiera te pola:

• Tablica types[] wskazuje typ zwróconego wyniku. Ta tablica zawiera zestaw zero lub więcej tagów określających typ cechy zwróconej w wyniku. Na przykład kod geograficzny „Chicago” zwraca wartość „locality”, która oznacza, że „Chicago” jest miastem, oraz hasło „polityczne”, co oznacza, że jest podmiotem politycznym. Komponenty mogą mieć pustą tablicę typów, gdy nie są znane żadne typy danego komponentu adresu. W razie potrzeby interfejs API może dodać nowe wartości typów. Więcej informacji znajdziesz w artykule Typy adresów i ich komponenty.
• formatted_address to ciąg znaków zawierający zrozumiały dla człowieka adres tej lokalizacji.

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

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

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

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

  Każdy komponent adresu zawiera zwykle te pola:

  • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
  • long_name to pełny opis tekstowy lub nazwa komponentu adresu zwrócone przez Geocoder.
  • short_name to skrócona nazwa tekstowa komponentu adresu, jeśli jest dostępna. Na przykład komponent adresu dla stanu Alaska może mieć wartość long_name o wartości „Alaska” i short_name „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 niekoniecznie obejmuje wszystkie podmioty polityczne, które zawierają adres, z wyjątkiem tych zawartych w tabeli formatted_address. Aby pobrać wszystkie podmioty polityczne, które zawierają konkretny adres, użyj odwrotnego geokodowania, przekazując szerokość i długość geograficzną adresu jako parametr do żądania.
  • Nie ma gwarancji, że format odpowiedzi między żądaniami pozostanie taki sam. W szczególności liczba parametrów address_components zależy od żądanego adresu i może się zmieniać z czasem w przypadku tego samego adresu. Komponent może zmienić pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować określonego komponentu.

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

• postcode_localities[] to tablica wskazująca maksymalnie 100 miejscowości zawartych w kodzie pocztowym. Jest on dostępny tylko wtedy, gdy wynikiem jest kod pocztowy zawierający wiele miejscowości.
• geometry zawiera te informacje:
  • Pole location zawiera Geokodowaną wartość długości i szerokości geograficznej. W przypadku normalnego wyszukiwania adresów to pole ma zwykle najważniejsze znaczenie.

  • 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 z dokładnością do dokładnego adresu.
    • "RANGE_INTERPOLATED" wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolację między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachowe dla adresu ulicy są niedostępne.
    • "GEOMETRIC_CENTER" oznacza, że zwrócony wynik to środek geometryczny wyniku, np. linii łamanej (na przykład ulica) lub wielokąta (region).
    • "APPROXIMATE" oznacza, że zwrócony wynik jest przybliżony.
  • viewport zawiera zalecany widoczny obszar, na którym można wyświetlić zwrócony wynik, określony za pomocą 2 wartości szerokości i długości geograficznej, które określają róg ramki ograniczającej widoczny obszar southwest i northeast. Ogólnie widoczny obszar służy do umieszczania wyniku w ramce podczas wyświetlania go użytkownikowi.
  • bounds (opcjonalnie zwracana) przechowuje ramkę ograniczającą, która może w całości zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanemu widocznemu obszarowi. Na przykład San Francisco obejmuje wyspy Farallona, które technicznie stanowią część miasta, ale prawdopodobnie nie powinny pojawiać się na widocznym obszarze.
• plus_code (patrz Otwórz kod lokalizacji i kody plus) to zakodowane odniesienie do lokalizacji określane na podstawie współrzędnych geograficznych i reprezentujące obszar: 1/8000 stopnia i 1/8000 stopnia (około 14 x 14 m na równiku) lub mniejszy. Kody Plus Code mogą zastąpić adresy w miejscach, w których adresy nie istnieją (gdzie budynki nie są ponumerowane ani nazwy ulic). API nie zawsze zwraca kody Plus Code.

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

  • global_code to czteroznakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).
  • compound_code to co najmniej 6-znakowy kod lokalny z konkretną lokalizacją (CWC8+R9, Mountain View, Kalifornia, USA). Nie analizuj takich treści programowo.
  Tam, gdzie 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), zwrócony może zostać tylko kod globalny.

• partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, chociaż mógł dopasować część żądanego adresu. Możesz sprawdzić pierwotną prośbę pod kątem błędów pisowni lub niekompletnych adresów.

  Dopasowania częściowe pojawiają się najczęściej w przypadku adresów, których nie ma w okolicy, którą przekazujesz w żądaniu. Dopasowania częściowe mogą też zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym regionie. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry Street, jak i ulicy Henrietta. Pamiętaj, że jeśli żądanie zawiera błędny adres, usługa geokodowania może zaproponować inny adres. Sugestie wywołane w ten sposób zostaną również oznaczone jako dopasowane częściowo.

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

Typy adresów i typy komponentów adresu

Tablica types[] w wyniku wskazuje typ adresu. Przykładowe rodzaje adresu to ulica i numer, kraj lub nazwa podmiotu politycznego. W obiekcie 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 kraj. (Poniżej znajduje się pełna lista typów). Adresy mogą mieć kilka rodzajów. Typy mogą być uważane za „tagi”. Na przykład wiele miast jest oznaczonych tagami typu political i locality.

Te typy są obsługiwane i zwracane przez geokoder zarówno w tablicach typu adresu, jak i typu komponentu adresu:

• street_address wskazuje dokładny adres.
• route oznacza trasę z nazwą (np. „E101”).
• intersection oznacza główne skrzyżowanie, zwykle dwóch głównych dróg.
• political oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt niektórych obiektów administracji cywilnej.
• country wskazuje krajowy podmiot polityczny i jest zwykle najwyższym typem zamówienia zwracanym przez geokoder.
• 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 administracyjne_area_level_1 będą bardzo podobne do podgrup w standardzie ISO 3166-2 i innych rozpowszechnianych list. Nie jest to jednak gwarantowane, ponieważ wyniki geokodowania opierają się na różnych sygnałach 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 rzędu poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. 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 niewielką jednostkę cywilną. 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 niewielką jednostkę cywilną. 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 niewielką jednostkę cywilną. 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 niewielką jednostkę cywilną. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• colloquial_area wskazuje powszechnie używaną nazwę alternatywną elementu.
• locality oznacza podmiot polityczny z własnym miastem lub miastem.
• sublocality oznacza jednostkę cywilną pierwszego rzędu pod rejonem. W przypadku niektórych lokalizacji mogą pojawić się dodatkowe typy: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
• neighborhood oznacza nazwany dzielnicę
• premise wskazuje nazwane miejsce, zwykle jest to budynek lub zbiór budynków o takiej samej nazwie
• subpremise oznacza element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle jest to pojedynczy budynek w zespole budynków o takiej samej nazwie
• plus_code oznacza zakodowane odniesienie do lokalizacji na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastąpić adresy w miejscach, w których nie istnieją (gdzie budynki nie są numerowane lub nazwy ulic nie są nazwane). Szczegółowe informacje znajdziesz na stronie https://plus.codes.
• postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
• natural_feature oznacza ważny obiekt naturalny.
• airport oznacza lotnisko.
• park oznacza nazwany park.
• point_of_interest wskazuje nazwane miejsce. Takie miejsca to zazwyczaj znane obiekty lokalne, które nie pasują do żadnej innej kategorii, takiej jak „Empire State Building” czy „Wieża Eiffla”.

Pusta lista typów oznacza, że nie są znane żadne typy określonego komponentu adresu, np. Lieu-dit we Francji.

Oprócz tego składniki adresu mogą zawierać wymienione tu typy. Ta lista nie jest pełna i może ulec zmianie.

• floor wskazuje piętro w adresie 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 dla ułatwienia nawigacji.
• point_of_interest wskazuje nazwane miejsce.
• parking oznacza parking.
• post_box oznacza konkretną skrzynkę pocztową.
• postal_town oznacza grupę obszarów geograficznych, np. locality i sublocality, która jest używana w przypadku adresów pocztowych w niektórych krajach.
• room wskazuje salę w danym budynku.
• street_number wskazuje dokładny numer domu.
• bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, pociągu lub transportu publicznego.

Promowanie widocznego obszaru

W żądaniu geokodowania można polecić usłudze Geocoding, aby preferowała wyniki w danym obszarze (wyrażony jako ramka ograniczająca). Aby to zrobić, ustaw parametr bounds w adresie URL żądania.

Parametr bounds określa współrzędne szerokości i długości geograficznej południowego i północno-wschodniego narożnika tej ramki ograniczającej za pomocą kreski pionowej (|).

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

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, że geokod będzie zwracał miasto Waszyngton w Dystrykcie Kolumbii:

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 geokodowania można za pomocą parametru region polecić usłudze Geocoding, aby zwracała ona wyniki stronnicze w określonym regionie. Ten parametr przyjmuje argument ccTLD (domena najwyższego poziomu kodu kraju) określający odchylenie regionu. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).

Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której została oficjalnie uruchomiona główna aplikacja Map Google. Pamiętaj, że promowanie preferuje tylko wyniki z konkretnej domeny. Jeśli poza tą domeną występują trafniejsze wyniki, zostaną one uwzględnione.

Na przykład kod geograficzny dla „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 dla „Toledo” wysłane przez 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 interfejs Geocoding API może zwracać wyniki adresowe 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 korekty pisowni i częściowego dopasowywania, co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie do filtra komponentów, odpowiedź będzie zawierać pole partial_match.

Wartości, które można filtrować (components) to:

• postal_code pasuje do postal_code i postal_code_prefix.
• Atrybut country odpowiada nazwie kraju lub dwuliterowym kodem kraju zgodnym z normą ISO 3166-1. Interfejs API jest zgodny ze standardem ISO dla definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Te components mogą być używane do wpływania na wyniki, ale nie są wymuszane:

• route odpowiada długą lub krótką nazwą trasy.
• locality pasuje do typów locality i sublocality.
• administrative_area pasuje do wszystkich administrative_area poziomów.

Uwagi na temat filtrowania komponentów:

• Nie powtarzaj tych filtrów komponentów w żądaniach. W przeciwnym razie interfejs API zwróci wartość Invalid_request: country, postal_code, route
• Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API ocenia te filtry za pomocą operatorów ORAZ, a nie LUB.
• Wyniki są zgodne z Mapami Google, co czasem zwraca nieoczekiwane odpowiedzi ZERO_RESULTS. W niektórych przypadkach użycie autouzupełniania miejsc może przynieść lepsze wyniki. Więcej informacji znajdziesz w najczęstszych pytaniach.
• W przypadku każdego komponentu adresu określ go w parametrze address lub w filtrze components, ale nie w obu tych miejscach. Podanie tych samych wartości w obu przypadkach może spowodować ZERO_RESULTS.

Geokod odpowiadający „High St, Hastings” zawierający components=country:GB zwraca wynik w Hastings (Anglia), a nie w Hastings-On-Hudson w 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 geokod dla rejonu „Santa Cruz” z components=country:ES zwraca Santa Cruz de Tenerife na Wyspach Kanaryjskich w Hiszpanii.

Prośba:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Odpowiedź:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Filtrowanie komponentów zwraca odpowiedź ZERO_RESULTS tylko wtedy, gdy podasz filtry, które 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 wysyłać prawidłowe zapytania bez parametru adresu. (podczas geokodowania pełnego adresu wymagany jest parametr address, 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"
}