Żądanie geokodowania i odpowiedź

Prośba

Żądanie do Geocoding API ma taką postać:

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

W przypadku żądań korzystających z klucza interfejsu API wymagany jest protokół HTTPS.

Niektóre parametry są wymagane, a inne opcjonalne. Zgodnie ze standardem w adresach URL parametry są rozdzielone znakiem „&”.

W pozostałej części tej strony opisujemy geokodowanie i odwrotne geokodowanie oddzielnie, 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, dla którego chcesz przetworzyć dane geograficzne. Podaj adresy zgodnie z formatem używanym przez krajową służbę pocztową w danym kraju. Należy unikać dodatkowych elementów adresu, takich jak nazwy firm, lokale, lokale i piętra. Elementy adresu pocztowego powinny być rozdzielone spacjami (w tym przykładzie ze zmianą znaczenia adresu URL do adresu %20):

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

  Sformatuj kody plus w sposób podany tutaj (znak plusa musi zawierać kod zmiany znaczenia dla adresu URL %2B, a spacje należy zapisać w adresie URL do adresu %20):
  • Kod globalny to 4-znakowy numer kierunkowy i co najmniej 6 znaków (kod lokalny 849VCWC8+R9 to 849VCWC8%2BR9).
  • Kod złożony to co najmniej 6-znakowy kod lokalny z określoną 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 właściwość address. Każdy element filtra komponentów składa się z pary component:value i całkowicie 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 wskazówek znajdziesz w najczęstszych pytaniach.

Parametry opcjonalne w żądaniu Geocoding:

• bounds – ramka ograniczająca widoczny obszar, w którym lepiej eksponuje odchylenie geokodu. Ten parametr ma wpływ tylko na wyniki generowane przez geokodera, a nie jego pełne ograniczenie. Więcej informacji znajdziesz w sekcji Promowanie widocznego obszaru poniżej.
• language – język, w którym zwracane są 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 nie zostanie podany language, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka ojczystego domeny, z której wysyłane jest żądanie.
  • Geokoder dokłada wszelkich starań, aby podać czytelny adres zarówno dla użytkownika, jak i lokalnego. W tym celu zwraca adresy w języku lokalnym, transliterację na skrypt w razie potrzeby zrozumiały dla użytkownika i zachowując preferowany język. Pozostałe 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 jest niedostępna w preferowanym języku, geokoder użyje najbliższego odpowiednika.
  • Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API zwróci, oraz na kolejność ich zwracania. Geokoder interpretuje skróty w różny sposób w zależności od języka (np. skrót nazwy ulicy lub synonimy mogą być poprawne w jednym języku, a w innym nie). Na przykład utca i tér to synonimy słów „ulica” i „kwadrat” w języku węgierskim.
• region – kod regionu, podany jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Ten parametr ma wpływ tylko na wyniki generowane przez geokodera, a nie jego pełne ograniczenie. Więcej informacji znajdziesz poniżej w sekcji Promowanie regionów. Parametr może też wpływać na wyniki w zależności od obowiązującego prawa.
• 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 i całkowicie ogranicza wyniki generowane przez geokodera. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.

Odpowiedzi

Odpowiedzi związane z geokodowaniem są zwracane w formacie określonym przez flagę output w żądaniu adresu URL lub w formacie JSON.

W tym przykładzie interfejs Geocoding API żąda odpowiedzi json na zapytanie o identyfikator miejsca „ChIJeRpOeF67j4AR9ydy_PIzPuM”. Ten identyfikator miejsca dotyczy budynku pod adresem 1600 Amphitheatre Parkway, Mountain View, CA.

W tym żądaniu pokazano użycie flagi JSON output:

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

W tym żądaniu użyto 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 w formacie 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"
                    ]
                }
            ],
            "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"
}

<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 żadne błędy. Adres został pomyślnie przeanalizowany i zwrócono co najmniej jeden geokod.
• "ZERO_RESULTS" oznacza, że geokod został przetworzony pomyślnie, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder przekazał nieistniejący obiekt address.
• OVER_DAILY_LIMIT oznacza jedną z tych wartości:
  • Brak klucza interfejsu API lub jest on nieprawidłowy.
  • Płatności nie są włączone na Twoim koncie.
  • Nałożony przez Ciebie limit wykorzystania został przekroczony.
  • Podana forma płatności nie jest już aktualna (np. karta kredytowa straciła ważność).

  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.
• Parametr "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 zostać zrealizowane.

Komunikaty o błędach

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

Typowy wynik zawiera te pola:

• Tablica types[] wskazuje typ zwróconego wyniku. Ta tablica zawiera zestaw tagów określających typ obiektu zwracanego w wyniku (zero lub więcej). Na przykład geokod „Chicago” zwraca „locality”, który wskazuje, że „Chicago” to miasto, i dodatkowo „polityczne”, które wskazuje, że jest to podmiot polityczny. Komponenty mogą mieć pustą tablicę typów, jeśli nie ma znanych typów dla danego 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 adresu.
• formatted_address to ciąg znaków zawierający czytelny dla człowieka adres tej lokalizacji.

  Często jest to równoważny adres pocztowy. Pamiętaj, że w niektórych krajach (np. w Wielkiej Brytanii) nie można rozpowszechniać prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

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

  Nie analizuj sformatowanego adresu automatycznie. Zamiast tego należy używać poszczególnych komponentów adresu, które oprócz sformatowanego pola adresu zawierają odpowiedź interfejsu API.

• 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 składnika adresu zwracanego 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” oraz wartość short_name w polu „AK” z dwuliterowym skrótem pocztowym.

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

  • Tablica komponentów adresu może zawierać więcej komponentów niż formatted_address.
  • Tablica nie musi zawierać wszystkich podmiotów politycznych z adresem (oprócz tych uwzględnionych w elemencie formatted_address). Aby pobrać wszystkie jednostki polityczne, które mają określony adres, użyj odwrotnego geokodowania, podając szerokość i długość geograficzną adresu jako parametr w żądaniu.
  • Nie możemy zagwarantować, że format odpowiedzi będzie taki sam między żądaniami. Liczba address_components różni się w zależności od żądanego adresu i może się z czasem zmieniać 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 dotyczącym analizowania odpowiedzi.

• postcode_localities[] to tablica wskazująca maksymalnie 100 lokali zawartych w kodzie pocztowym. Ten atrybut występuje tylko wtedy, gdy wynik to kod pocztowy zawierający wiele miejscowości.
• geometry zawiera te informacje:
  • location zawiera szerokość i długość geograficzną oznaczoną geokodem. W przypadku normalnego wyszukiwania adresów to pole jest zwykle najważniejsze.

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

    • "ROOFTOP" oznacza, że zwrócony wynik to dokładny geokoder, w przypadku którego informacje o lokalizacji są dokładne z dokładnością do adresu pocztowego.
    • Wartość "RANGE_INTERPOLATED" wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolację między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki z interpolacji są zwykle zwracane, gdy geokody dachowe są niedostępne w przypadku adresu.
    • "GEOMETRIC_CENTER" wskazuje, że zwrócony wynik jest geometrycznym środkiem wyniku, takim jak linia łamana (na przykład ulica) lub wielokąt (region).
    • "APPROXIMATE" wskazuje, że zwrócony wynik jest przybliżony.
  • viewport zawiera zalecany widoczny obszar do wyświetlania zwracanego wyniku, określony jako 2 wartości szerokości i długości geograficznej definiujące 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 (zwracany opcjonalnie) przechowuje ramkę ograniczającą, która może w całości zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie pasować do 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 Otwórz kod lokalizacji i kody plus) to zakodowane odniesienie do lokalizacji utworzone na podstawie szerokości i długości geograficznej, 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, które 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 czteroznakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).
  • compound_code to co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
  Jeśli jest dostępny, 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, mimo że udało się dopasować część żądanego adresu. Warto sprawdzić w pierwotnej prośbie, czy adres nie zawiera błędów pisowni lub zawiera niepełny adres.

  Dopasowania częściowe najczęściej występują w przypadku adresów, które nie występują w rejonie podanym w żądaniu. Dopasowania częściowe mogą zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym rejonie. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera komponent adresu z błędną pisownią, usługa geokodowania może zaproponować alternatywny adres. Sugestie uruchamiane 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 lokalnej firmie, 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łady typów adresów to m.in. adres, kraj lub podmiot polityczny. address_components[] znajduje się też w tablicy types[], która wskazuje typ każdej części adresu. Może to być na przykład numer domu lub kraj. Poniżej znajdziesz pełną listę typów. Adresy mogą mieć kilka typów. Typy te można uznać za „tagi”. Na przykład wiele miast jest oznaczonych tagami political i locality.

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

• street_address wskazuje dokładny adres.
• route wskazuje nazwaną trasę (np. „E701”).
• intersection oznacza główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.
• political oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt związany z administracją cywilną.
• country oznacza krajowy podmiot polityczny i zwykle jest najwyższym typem porządku zwracanym przez Geocoder.
• administrative_area_level_1 oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są stanami. Nie we wszystkich krajach obowiązują te poziomy administracyjne. W większości przypadków krótkie nazwy są zbliżone do nazw z normą ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy tego jednak zagwarantować, 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 są hrabstwami. 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 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ą nazwę alternatywną jednostki.
• locality oznacza miejskie podmioty polityczne.
• sublocality wskazuje podmiot cywilny pierwszego rzędu poniżej rejonu. W przypadku niektórych lokalizacji może zostać wyświetlony 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 oznacza element pierwszego rzędu pod nazwaną lokalizacją, zwykle pojedynczy budynek należący do zespołu budynków o wspólnej nazwie
• plus_code oznacza zakodowane odniesienie do lokalizacji na podstawie szerokości i długości geograficznej. Kody plus mogą zastąpić adresy ulic w miejscach, w których one nie istnieją (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). 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 wskazuje ważny obiekt naturalny.
• airport oznacza lotnisko.
• park wskazuje park nazwany.
• point_of_interest wskazuje nazwane miejsce. Takie ważne miejsca to zwykle doskonałe lokalne jednostki, których nie da się łatwo przypisać do innych kategorii, takich jak „Empire State Building” czy „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ć wymienione tutaj typy. Ta lista nie jest pełna i może się zmieniać.

• floor wskazuje piętro w adresie budynku.
• Typ 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 strukturę parkingową.
• post_box wskazuje 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 salę, w której znajduje się adres budynku.
• street_number wskazuje dokładny numer ulicy.
• 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, by preferowała wyniki w danym widocznym obszarze (wyrażonym jako ramka ograniczająca). Możesz to zrobić w adresie 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 za pomocą pionowej kreski (|) do oddzielania współrzędnych.

Na przykład geokod dla „Waszyngton” zazwyczaj zwraca 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ą północno-wschodnią część Stanów Zjednoczonych spowoduje, że ten geokod zwróci 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"
}

Promowanie regionu

W żądaniu Geocoding możesz poinstruować usługę Geocoding, aby zwracała odchylenia wyników w konkretnym regionie przy użyciu parametru region. Ten parametr przyjmuje argument ccTLD (kod kraju najwyższego poziomu w domenie), który określa odchylenie dotyczące regionu. Większość kodów domen ccTLD jest taka sama jak kody ISO 3166-1, z pewnymi istotnymi wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznacza to podmiot „Wielka Brytania Wielkiej Brytanii i Irlandii Północnej”).

Wyniki geokodowania mogą być tendencyjne w przypadku każdej domeny, w której oficjalnie uruchomiono główną aplikację Map Google. Pamiętaj, że promowanie tylko preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną są bardziej trafne wyniki, możemy je uwzględnić.

Ten wynik jest na przykład zwracany w przypadku geokodu „Toledo”, 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 adresów ograniczone do określonego obszaru. Ograniczenie można 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 dopasowania częściowego co inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie filtra komponentów, odpowiedź będzie zawierać pole partial_match.

components, które można filtrować:

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

Poniższe components mogą być używane do wpływania na wyniki, ale nie będą wymuszane:

• route pasuje do długiej lub krótkiej nazwy trasy.
• Dopasowania locality 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 kod Invalid_request: country, postal_code, route
• Jeśli żądanie zawiera powtarzające się filtry komponentów, API użyje operatora ORAZ, a nie LUB.
• Wyniki są zgodne z Mapami Google, które czasami dają nieoczekiwane odpowiedzi na żądanie 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.
• Dla każdego komponentu adresu podaj go w parametrze address lub filtrze components, ale nie w obu tych elementach. Podanie tych samych wartości w obu może dać wynik ZERO_RESULTS.

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

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 components=country:ES powoduje zwrócenie Santa Cruz de Tenerife na Wyspy Kanaryjskie 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 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"
}