Ta strona została przetłumaczona przez Cloud Translation API.

Żądanie geokodowania i odpowiedź

Żądanie

Żą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. Zgodnie ze standardem w adresach URL Parametry są oddzielane znakiem ampersand (&).

W pozostałej części tej strony opisaliśmy geokodowanie odwrotne geokodowanie, ponieważ dla każdego typu żądania są dostępne różne parametry.

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

Parametry wymagane w żądaniu geokodowania:

address – adres lub kod plus, który chcesz poddać geokodowaniu. Podaj adresy zgodnie z formatem wykorzystywane przez krajowy urząd pocztowy w danym kraju. Dodatkowe informacje elementów adresowych, takich jak nazwy firm i numer lokalu, lokalu lub piętra powinno być pomijane. Elementy adresu ulicy powinny być rozdzielane spacjami (tutaj zapisane w sposób ujęty w składnie adresu URL: %20):
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
Sformatuj kody plus zgodnie z poniższym opisem (znaki plusa są zmieniane w adres URL jako %2B, a spacje zawierają kod %20 ze znakami zmiany znaczenia dla adresu URL):
- kod globalny to 4-znakowy kod kierunkowy i co najmniej 6 znaków kod lokalny (849VCWC8+R9 to 849VCWC8%2BR9).
- Kod złożony to kod lokalny o długości co najmniej 6 znaków z wyraźną lokalizacją (CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).
--OR--
components – filtr komponentów z elementami. są oddzielone pionową kreską (|). Filtr komponentów też jest akceptowany. jako parametr opcjonalny, jeśli podano address. Każdy element w filtrze komponentów składa się z elementu component:value i całkowicie ogranicza wyniki od geokodera. Zobacz więcej informacji: filtrowania komponentów poniżej.
key – klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje Twoją aplikację na potrzeby zarządzania limitem. Dowiedz się, jak uzyskaj klucz.

Zapoznaj się z najczęstszymi pytaniami na temat: dodatkowe wskazówki.

Opcjonalne parametry w żądaniu Geocoding:

bounds – ramka ograniczająca widocznego obszaru. w ramach których można bardziej eksponować wyniki geokodowania. Ten parametr będzie miał wpływ na wyniki geokodowania, ale nie będzie ich w pełni ograniczał. (Więcej więcej informacji znajdziesz w sekcji Promowanie widocznego obszaru poniżej).
language – język, w którym ma być używany wyniki.
- Zobacz listę obsługiwanych funkcji języki. Google często aktualizuje obsługiwane języki, więc może nie być wyczerpująca.
- Jeśli parametr language nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub domyślnego języka domeny, z której wysłano żądanie.
- Geokoder stara się podać adres, który łatwy do odczytania zarówno przez użytkownika, jak i lokalnie. Aby to osiągnąć, zwraca adresy ulicy w języku lokalnym, transliterowane do postaci zrozumiałej dla użytkownika w odpowiednim języku. Wszystkie inne adresy są zwracane w preferencjach język. wszystkie komponenty adresu są zwracane w jednym języku, który jest wybierany z pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder użyje jak najbliższe znaczeniem.
- Preferowany język ma niewielki wpływ na zestaw wyników, które zwracany przez interfejs API i kolejność ich zwrócenia. Geokoder różnie interpretuje skróty w zależności od takie jak skróty określające typy ulic lub synonimy, które mogą mogą być ważne w jednym języku, a w innym już nie. Na przykład: utca. tér to synonimy ulicy i kwadratu po węgiersku.
region – kod regionu podany jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Ten parametr będzie tylko wpływ, a nie na całkowite ograniczanie, wyników z geokodera. (Więcej więcej informacji znajdziesz w sekcji Promowanie według regionu poniżej). może też wpływać na wyniki na podstawie obowiązującego prawa.
components – filtr komponentów z elementami rozdzielonymi znakiem pionowym (|). Filtr komponentów jest wymagany, jeśli żądanie nie zawiera znaku address. Każdy element w filtrze komponentów składa się z elementu component:value i całkowicie ogranicza wyniki od geokodera. Zobacz więcej informacji: filtrowania komponentów poniżej.
extra_computations – użyj tego parametru, aby określić parametr następujące dodatkowe funkcje w odpowiedzi:
- ADDRESS_DESCRIPTORS – Zobacz deskryptory adresów.
- BUILDING_AND_ENTRANCES – Zobacz wejścia i kontury budynków.
Aby włączyć kilka z tych funkcji w ramach tego samego żądania interfejsu API, dodaj parametr extra_computations w żądaniu dla każdej funkcji, na przykład:
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```

Odpowiedzi

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

W tym przykładzie interfejs Geocoding API wysyła żądanie json odpowiedź na pytanie dotyczące adresu „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

Aby zobaczyć przykładowe odpowiedzi w formacie JSON i XML, kliknij karty poniżej.

JSON

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

Pamiętaj, że odpowiedź JSON zawiera 2 elementy główne:

"status" zawiera metadane dotyczące żądania. Zobacz Kody stanu poniżej.
"results" zawiera tablicę danych adresowych z kodami geograficznymi oraz informacje geometryczne.

Zwykle zwracany jest tylko jeden wpis w tablicy "results" dla argumentu podczas wyszukiwania adresów, jednak geokoder może zwrócić kilka wyników, 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>

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

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

Odpowiedź XML jest znacznie dłuższa niż odpowiedź JSON. Dla: dlatego zalecamy wybór formatu json. flagi wyjściowej, chyba że usługa z jakiegoś powodu wymaga xml. Ponadto przetwarzanie drzew XML wymaga pewnej ostrożności, dlatego należy odwoływać się odpowiednich węzłów i elementów. Zobacz Analiza pliku XML za pomocą XPath w celu uzyskania niektórych zalecanych wzorców projektowych do przetwarzania danych wyjściowych.

Wyniki XML są zawijane w element główny <GeocodeResponse>.
W pliku JSON wpisy z większą liczbą elementów są oznaczone tablicami w liczbie mnogiej (types), a w pliku XML – elementami w liczbie pojedynczej (<type>).
Puste elementy są wskazywane przez puste tablice w formacie JSON, ale przez brak w kodzie XML. Odpowiedź, która nie generuje żadnych wyników, zwraca wartość pustą. tablica results w formacie JSON, ale brak elementów <result> w pliku XML, na przykład.

Kody stanu

Pole "status" w obiekcie odpowiedzi geokodowania zawiera stan żądania i może zawierać informacje debugowania, które pomogą Ci ustalić, dlaczego geokodowanie nie działa. Pole "status" może zawierać te wartości:

"OK" oznacza, że nie wystąpiły błędy. adres został pomyślnie przeanalizowany i został zwrócony co najmniej jeden 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 ważność karty kredytowej wygasła).
Przeczytaj Najczęstsze pytania dotyczące Map, aby dowiedzieć się więcej. jak to naprawić.
"OVER_QUERY_LIMIT" oznacza, że limit został przekroczony.
"REQUEST_DENIED" oznacza, że prośba została odrzucona.
"INVALID_REQUEST" oznacza zwykle, że brakuje zapytania (address, components lub latlng).
"UNKNOWN_ERROR" oznacza, że nie udało się zrealizować żądania przetworzono z powodu błędu serwera. Żądanie może zostać zrealizowane, jeśli: spróbuj jeszcze raz.

Komunikaty o błędach

Jeśli geokoder zwróci kod stanu inny niż OK, w obiekcie odpowiedzi geokodowania może się pojawić dodatkowe pole error_message. To pole zawiera więcej szczegółowe informacje o przyczynach związanych z określonym kodem stanu.

Wyniki

Gdy geokoder zwraca wyniki, umieszcza je w tablicy results (w formacie JSON). Nawet jeśli geokoder nie zwróci żadnych wyników (np. jeśli adres nie istnieje), nadal nie zostanie znaleziony. zwraca pustą tablicę results. (Odpowiedzi XML zawierają zero lub więcej wartości <result> elements.)

Typowy wynik zawiera te pola:

Tablica types[] wskazuje typ zwróconej wynik. Ta tablica zawiera zestaw zero lub więcej tagów identyfikujących typ funkcji zwracanych w wyniku. Na przykład geokod „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co oznacza, że jest to jednostka polityczna. Komponenty mogą mieć puste typy , gdy nie ma znanych typów dla danego składnika 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 elementy.
formatted_address to ciąg znaków zawierający zrozumiały dla człowieka tej lokalizacji.
Adres ten jest często odpowiednikiem adresu pocztowego. Pamiętaj, że niektóre takich jak Wielka Brytania, nie zezwalają na dystrybucję prawdziwego adresów pocztowych ze względu na ograniczenia licencyjne.

Sformatowany adres składa się logicznie z jednego lub wielu adresów . Na przykład adres „111 8th Avenue, Nowy Jork, NY” składa się z następujących komponentów: „111” (numer domu), „Ósma Aleja” (trasa), „Nowy Jork” (miasto) i „NY” (stan w USA).

Nie analizuj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych elementów adresu, które są zawarte w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.
address_components[] to tablica zawierająca oddzielne które mają zastosowanie do tego adresu.
Każdy komponent adresu zawiera zwykle te pola:
- types[] to tablica wskazująca typ adresu. Zobacz listę obsługiwanych typów.
- long_name to pełny opis lub nazwa elementu komponentem adresowym zwracanym przez Geocoder.
- short_name to skrócona nazwa tekstowa adresu jeśli jest dostępny. Na przykład składnik adresu dla stanu obszaru Alaski może mieć long_name o wartości „Alaska” i short_name pozycji „Akademia” za pomocą dwuliterowego skrótu pocztowego.
Pamiętaj o tych informacjach dotyczących tablicy address_components[]:
- Tablica elementów adresu może zawierać więcej elementów niż formatted_address.
- Tablica niekoniecznie zawiera wszystkie podmioty polityczne, które zawierają adres, z wyjątkiem tych, które są uwzględnione w tablicy formatted_address. Aby pobrać wszystkie jednostki polityczne zawierających konkretny adres, należy zastosować odwrotne geokodowanie, przesyłając szerokość i długość geograficzną adresu jako parametr żądania.
- Nie ma gwarancji, że format odpowiedzi będzie taki sam w przypadku różnych żądań. W szczególności chodzi o liczbę address_components zmienia się w zależności od żądanego adresu i może się zmieniać pod tym samym adresem. Komponent może zmienić pozycję w tablicy. Typ komponentu może się zmienić. Konkretnym komponentem może być których brakuje w późniejszej odpowiedzi.
Aby obsługiwać tablicę komponentów, musisz przeanalizować odpowiedź i wybieraj odpowiednie wartości za pomocą wyrażeń. Zapoznaj się z przetwarzaniem odpowiedzi.
postcode_localities[] to tablica oznaczająca do 100 miejscowości podane w kodzie pocztowym. Ten parametr jest widoczny tylko wtedy, gdy wynik to kod pocztowy który zawiera wiele lokalizacji.
geometry zawiera te informacje:
- location zawiera szerokość geograficzną i długość geograficzną z geokodowaniem. Normalne wyszukiwań adresów, to pole jest zwykle najważniejsze.
- location_type przechowuje dodatkowe dane o określonej lokalizacji. obecnie obsługiwane są następujące wartości:
  - "ROOFTOP" oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji dokładne do adresu ulicy.
  - "RANGE_INTERPOLATED" oznacza że zwracany wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między dwoma dokładnymi punktami (np. skrzyżowaniami). Interpolowane wyniki są zwykle zwracane, gdy kody geograficzne na dachu budynku są niedostępne dla adresu ulicznego.
  - "GEOMETRIC_CENTER" oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak linia łamana (na przykład ulica) lub wielokąt (region).
  - "APPROXIMATE" oznacza, że zwracany wynik jest przybliżony.
- viewport zawiera zalecany widoczny obszar wyświetlania zwrócony wynik, określony jako dwie wartości szerokości i długości geograficznej,definiujące southwest i northeast róg ramki ograniczającej widoczny obszar. Ogólnie parametr jest używany do umieszczania wyniku w ramce podczas wyświetlania go użytkownikowi.
- Funkcja bounds (opcjonalnie zwrócona) przechowuje ramkę ograniczającą który może w całości zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanej przez Google przeglądarce. (Na przykład San Francisco obejmuje Wyspy Farallona, technicznie stanowią część miasta, ale prawdopodobnie nie powinny być wyświetlane na widocznym obszarze).
plus_code (zobacz Otwórz kod lokalizacji i kody plus) to zakodowany odniesienie do lokalizacji na podstawie współrzędnych geograficznych, przedstawia obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m x 14 m na równiku) lub mniejszą. Kody Plus Code mogą zastępować adresy w miejscach, w których nie ma adresów (gdzie budynki nie są numerowane, a ulice nie mają nazw). Interfejs API nie zawsze zwraca kodów plus.
Gdy usługa zwróci kod plus, będzie on sformatowany jako kod globalny i kod złożony:
- global_code to 4-znakowy 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 ich automatycznie.
Jeśli to możliwe, interfejs API zwraca zarówno kod globalny, jak i złożony. Jeśli jednak wynik dotyczy odległej lokalizacji (np. oceanu lub pustyni) tylko może zostać zwrócony kod globalny.
partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Możesz sprawdzić pierwotną prośbę pod kątem błędów ortograficznych i/lub jest niepełny adres.

Dopasowania częściowe najczęściej pojawiają się w przypadku adresów, które nie istnieją na obszarze objętym zgłoszeniem. Częściowe dopasowania mogą również zostać zwracany, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości. Na przykład wyszukiwanie „Hillpar St, Bristol, UK” zwróci dopasowanie częściowe zarówno do Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera parametr błędnie zapisany adres, usługa geokodowania może zaproponować alternatywę adresu. Sugestie wywołane w ten sposób zostaną również oznaczone jako częściowe dopasowania.
place_id to unikalny identyfikator których można używać z innymi interfejsami API Google. Możesz na przykład: użyj funkcji place_id w Żądanie Places API do pobrania informacje o lokalnej firmie, takie jak numer telefonu, godziny otwarcia, opinie i inne treści. Zapoznaj się z omówieniem identyfikatora miejsca.

Typy adresów i typy komponentów adresu

Tablica types[] w wyniku wskazuje typ adresu. Przykłady typów adresów to: ulicę i numer, kraju lub podmiotu politycznego. W elementach address_components[] znajduje się też tablica types[], która wskazuje typ poszczególnych części adresu. Może to być na przykład numer domu lub kraj. (Poniżej znajduje się pełna lista types.) Adresy mogą mieć kilka rodzajów. Typy mogą być uznawane za „tagi”. Na przykład wiele miast jest oznaczonych tagami political oraz Typ: locality.

Geokoder obsługuje i zwraca poniższe typy w obu tablice typu adresu i typu komponentu adresu:

street_address wskazuje dokładny adres.
route oznacza trasę z nazwą (np. „E101”).
intersection oznacza większe przecięcie, zwykle składające się z dwóch dróg głównych.
political oznacza podmiot polityczny. Zwykle ten typ wskazuje poligon administracji cywilnej.
country oznacza krajowy podmiot polityczny i jest zwykle jest to najwyższy typ kolejności zwracany przez Geocoder.
administrative_area_level_1 oznacza cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany. Nie we wszystkich krajach na poziomach administracyjnych. W większości przypadków parametr administracyjny_area_level_1 krótkie nazwy będą dokładnie odpowiadać podziałom zgodnym z normą ISO 3166-2 oraz innymi powszechnymi publikowane listy; Nie jest to jednak gwarantowane, ponieważ wyniki geokodowania na podstawie różnych sygnałów i danych o lokalizacji.
administrative_area_level_2 oznacza typ cywilny drugiego rzędu. poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie we wszystkich krajach na poziomach administracyjnych.
administrative_area_level_3 oznacza rodzaj 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 cywilny rządu 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 cywilny piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
administrative_area_level_6 oznacza cywilny szóstego rzędu. poniżej poziomu kraju. Ten typ oznacza niewielką jednostkę cywilną. Nie wszystkie kraje mają te poziomy administracyjne.
administrative_area_level_7 oznacza 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 oznacza często używaną nazwę alternatywną. danego podmiotu.
locality oznacza miasto lub miejscowości, na terenie których funkcjonuje podmiotu zabezpieczeń.
sublocality oznacza podmiot cywilny pierwszego rzędu pod lokalizacji. W przypadku niektórych lokalizacji mogą pojawić się dodatkowe typy lokalizacji: sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejsze obszar geograficzny.
neighborhood oznacza nazwę sąsiedztwa
premise wskazuje nazwaną lokalizację, zwykle budynek lub zbiór budynków o wspólnej nazwie
subpremise oznacza element pierwszego rzędu pod nazwanym lokalizacji, zwykle pojedynczego budynku w obrębie zespołu budynków imię i nazwisko
plus_code oznacza zakodowane odniesienie do lokalizacji, pochodne od szerokości i długości geograficznej. Kody Plus Code mogą zastępować adresy ulicy w miejscach, w których ich nie ma (gdzie budynki nie mają numerów lub ulice nie mają nazw). Zobacz https://plus.codes. .
postal_code oznacza kod pocztowy używany do adresowania. na terenie tego kraju.
natural_feature oznacza ważny obiekt naturalny.
airport oznacza lotnisko.
park oznacza nazwany park.
point_of_interest wskazuje nazwane miejsce docelowe. Takie miejsca to zazwyczaj dobrze widoczne obiekty lokalne, które nie zawsze w innej kategorii, takiej jak „Empire State Building” czy „wieża Eiffla”.

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

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

floor wskazuje piętro w adresie budynku.
establishment zwykle oznacza miejsce, w którym nie ma jeszcze została sklasyfikowana.
landmark wskazuje miejsce w pobliżu, które jest używane jako odniesienie. i ułatwi nawigację.
point_of_interest wskazuje nazwane miejsce docelowe.
parking oznacza parking.
post_box oznacza konkretną skrzynkę pocztową.
postal_town oznacza grupę obszarów geograficznych, takich jak locality i sublocality, używane w adresach 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ę autobusu, pociągu lub środka transportu publicznego przystanek.

Promowanie widocznego obszaru

W żądaniu geokodowania możesz poprosić usługę geokodowania o preferowanie wyników w danym widoku (wyrażonym jako ograniczony obszar). Możesz to zrobić w adresie URL żądania, ustawiając parametr bounds.

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ą linii (|) do rozdzielenia współrzędnych.

Na przykład kod geograficzny „Waszyngton”. zwraca zwykle stan USA 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"
}

Dodanie argumentu bounds definiującego ramkę ograniczającą północno-wschodnią część USA daje wynik tego geokodu, 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 nakazać usłudze Geocoding, aby zwracała ona wyników dla określonego regionu za pomocą funkcji region . Ten parametr przyjmuje domenę ccTLD (kodu kraju najwyższego poziomu) domena) określający odchylenie regionalne. Większość kodów ccTLD jest taka sama jak kodów ISO 3166-1 z kilkoma wyjątkami. Na przykład Stany Zjednoczone domena ccTLD królestwa to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielkiej Brytanii Wielkiej Brytanii i Irlandia Północna”).

Wyniki geokodowania mogą być stronnicze w przypadku każdej domeny, w której główny Aplikacja Mapy Google została oficjalnie uruchomiona. Pamiętaj, że odchylenie dotyczy tylko preferuje wyniki z konkretnej domeny; jeśli istnieją trafniejsze wyniki spoza tej domeny, mogą zostać uwzględnione.

Na przykład geokod dla „Toledo”. domyślnie zwraca ten wynik. domena dla 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” z: region=es (Hiszpania) zwraca 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 zwrócić adres wyników ograniczonych do konkretnego obszaru. Ograniczenie możesz określić za pomocą filtra components. Filtr składa się z listy: component:value par rozdzielone pionową kreską (|). Wartości filtrów obsługują te same metody poprawy pisowni oraz częściowe sprawdzanie pisowni tak jak inne żądania geokodowania. Jeśli geokoder znajdzie częściowe dopasowanie dla wartości 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 pasuje do nazwy kraju lub dwuliterowego kodu kraju ISO 3166-1. Interfejs API jest zgodny ze standardem ISO dla definiują kraje, a filtrowanie działa najlepiej przy z odpowiednim kodem ISO kraju.
Uwaga: w przypadku nieoczekiwanych wyników z kodem kraju sprawdź, że używasz kodu zawierającego kraje, terytoria zależne i specjalne interesujące Cię obszary. Informacje o kodzie znajdziesz na stronie Wikipedia: lista ISO Kody krajów 3166 lub ISO Online Browsing Platforma.

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

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

Uwagi na temat filtrowania komponentów:

Nie powtarzaj tych filtrów komponentów w żądaniach – inaczej interfejs API zwróci Invalid_request: country, postal_code, route
Jeśli żądanie zawiera powtarzające się filtry komponentów, interfejs API je oceni użyj operatora I, a nie LUB.
Wyniki są zgodne z Mapami Google, które czasami zwracają nieoczekiwane odpowiedzi. W niektórych przypadkach autouzupełnianie miejsc może przynieść lepsze wyniki. Więcej informacji: to Najczęstsze pytania.
W przypadku każdego elementu adresu podaj go w parametrze address lub w filtrze components, ale nie w obu tych miejscach. Podanie tych samych wartości w obu przypadkach może spowodować ZERO_RESULTS.

Geokod dla „High Street, Hastings” dzięki components=country:GB zwraca wynik w Hastings (Wielka Brytania), 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"
}

Żądanie geokodowania lokalizacji „Santa Cruz” z components=country:ESzwraca Santa Cruz de Tenerife na Wyspach Kanaryjskich w Hiszpanii.

Prośba:

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

Odpowiedź:

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

Filtrowanie komponentów zwraca odpowiedź ZERO_RESULTS tylko wtedy, gdy zastosujesz filtry, które wzajemnie się wykluczają.

Prośba:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Odpowiedź:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Możesz wysyłać prawidłowe zapytania bez parametru address, korzystając z filtra components. (Przy geokodowaniu 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"
}