Usługa geokodowania

Omówienie

Geokodowanie to proces konwertowania adresów (np. „1600 Amphitheatre Parkway, Mountain View, CA”) na współrzędne geograficzne (np.szerokość geograficzna 37,423021 i długość geograficzna -122,083739), których można używać do umieszczania znaczników lub pozycjonowania na mapie.

Odwrotne geokodowanie to proces konwertowania współrzędnych geograficznych na adres zrozumiały dla człowieka (patrz Odwrotne geokodowanie (wyszukiwanie adresu)).

Możesz też użyć geokodera, aby znaleźć adres danego identyfikatora miejsca.

Interfejs Maps JavaScript API udostępnia klasę Geocoder do dynamicznego geokodowania i odwrotnego geokodowania danych wejściowych użytkownika. Jeśli zamiast tego chcesz geokodować statycznie znane adresy, zapoznaj się z artykułem o usłudze internetowej wykorzystującej geokodowanie.

Rozpocznij

Zanim użyjesz usługi geokodowania w Maps JavaScript API, upewnij się, że interfejs Geocoding API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany dla Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

  1. Otwórz konsolę Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt skonfigurowany dla interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu odszukaj Geocoding API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejs API nie jest wymieniony, włącz go:
    1. U góry strony kliknij WŁĄCZ INTERFEJS API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
    2. Wyszukaj Geocoding API i wybierz go na liście wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu interfejs Geocoding API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

Informacje o cenach i zasadach korzystania z usługi geokodowania JavaScript znajdziesz w sekcji Korzystanie i rozliczenia interfejsu Geocoding API.

Zasady

Korzystanie z usługi Geocoding musi być zgodne z zasadami dotyczącymi interfejsu Geocoding API.

Żądania geokodowania

Dostęp do usługi geokodowania jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do zewnętrznego serwera. Z tego powodu musisz przekazać metodę z wywołaniem zwrotnym, która zostanie wykonana po zakończeniu przetwarzania żądania. Ta metoda wywołania zwrotnego przetwarza wyniki. Pamiętaj, że geokoder może zwrócić więcej niż 1 wynik.

Dostęp do usługi geokodowania interfejsu API Map Google uzyskujesz w kodzie za pomocą obiektu konstruktora google.maps.Geocoder. Metoda Geocoder.geocode() inicjuje żądanie do usługi geokodowania, przekazując jej literał obiektu GeocoderRequest zawierający warunki wejściowe i metodę wywołania, która zostanie wykonana po otrzymaniu odpowiedzi.

Obiekt GeocoderRequest zawiera te pola:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Wymagane parametry: musisz podać jedno i tylko jedno z tych pól:

  • address – adres, który chcesz geokodować.
         lub
    location – LatLng (lub LatLngLiteral), dla którego chcesz uzyskać najbliższy, zrozumiały dla człowieka adres. Geokoder wykonuje odwrotne geokodowanie. Więcej informacji znajdziesz w artykule Geokodowanie odwrotne.
         lub
    placeId – identyfikator miejsca, w przypadku którego chcesz uzyskać najbliższy, zrozumiały dla człowieka adres. Dowiedz się więcej o pobieraniu adresu na podstawie identyfikatora miejsca.

Parametry opcjonalne:

  • bounds – obszar geograficzny, na którym mają być wyświetlane wyniki geokodowania.LatLngBounds Parametr bounds będzie miał wpływ na wyniki geokodowania, ale nie będzie ich w pełni ograniczać. Poniżej znajdziesz więcej informacji o uwzględnianiu rozmiaru widoku .
  • componentRestrictions – służy do ograniczania wyników do określonego obszaru. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
  • region – kod regionu określony jako dwuznakowy (niecyfrowy) tag regionu w standardzie Unicode. W większości przypadków te tagi są mapowane bezpośrednio na 2-znakowe wartości domen krajowych najwyższego poziomu (ccTLD). Parametr region będzie miał wpływ na wyniki geokodera, ale nie będzie ich w pełni ograniczać. Poniżej znajdziesz więcej informacji o uwzględnianiu kodu regionu.
  • extraComputations – jedyną dozwoloną wartością tego parametru jest ADDRESS_DESCRIPTORS. Więcej informacji znajdziesz w  opisie adresu.
  • fulfillOnZeroResults – w odpowiedzi spełnij obietnicę dotyczącą stanu ZERO_RESULT. Może to być pożądane, ponieważ nawet przy zerowym geokodowaniu mogą zostać zwrócone dodatkowe pola na poziomie odpowiedzi. Więcej informacji znajdziesz w artykule Realizacja zamówienia w przypadku braku wyników.

Odpowiedzi dotyczące geokodowania

Usługa geokodowania wymaga metody wywołania zwrotnego, która zostanie wykonana po pobraniu wyników geokodowania. To wywołanie zwrotne powinno przekazywać 2 parametry, które zawierają odpowiednio kod results i status.

Wyniki geokodowania

Obiekt GeocoderResult reprezentuje pojedynczy wynik geokodowania. Żądanie geokodowania może zwrócić wiele obiektów wyników:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Poniżej opisujemy te pola:

  • types[] to tablica wskazująca typ adresu zwróconego wyniku. Tablica ta zawiera co najmniej 1 tag, który identyfikuje typ zwracanej w wyniku funkcji. Na przykład kod geograficzny „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co oznacza, że jest to podmiot polityczny. Poniżej znajdziesz więcej informacji o typach adresów i ich komponentach.
  • formatted_address to ciąg tekstowy zawierający adres tej lokalizacji w zrozumiałej dla człowieka formie.

    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ć 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.

    Poniżej znajdziesz więcej informacji o typach adresów i ich komponentach.

  • 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 ortograficznych 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. Częściowe dopasowania 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 Henry Street, jak i Henrietta Street. 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_idto unikalny identyfikator miejsca, którego można używać w innych interfejsach API Google. Możesz na przykład używać interfejsu place_id z biblioteką Google Places API, aby uzyskiwać informacje o firmie działającej lokalnie, takie jak numer telefonu, godziny otwarcia czy opinie użytkowników. Zapoznaj się z omówieniem identyfikatora miejsca.
  • postcode_localities[] to tablica zawierająca wszystkie miejscowości zawarte w kodzie pocztowym. Jest obecna tylko wtedy, gdy wynik to kod pocztowy zawierający wiele miejscowości.

  • geometry zawiera te informacje:

    • location zawiera geokodowaną szerokość i długość geograficzną. Pamiętaj, że zwracamy tę lokalizację jako obiekt LatLng, a nie jako sformatowany ciąg znaków.
    • location_type przechowuje dodatkowe dane o określonej lokalizacji. Obsługiwane są te wartości:
      • ROOFTOP oznacza, że zwrócony wynik odzwierciedla dokładny kod geograficzny.
      • RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachów są niedostępne dla adresu ulicznego.
      • GEOMETRIC_CENTER oznacza, że zwrócony wynik jest środkiem geometrycznym wyniku, takiego jak linia złożona (np. ulica) lub wielokąt (region).
      • APPROXIMATE oznacza, że zwrócony wynik jest przybliżony.

    • viewport przechowuje zalecany widoczny obszar dla zwróconego wyniku.
    • bounds (opcjonalnie zwracany) przechowuje zmienną LatLngBounds, która może zawierać zwrócony wynik. Pamiętaj, że te granice mogą nie odpowiadać zalecanej widoczności. Na przykład San Francisco obejmuje Wyspy Faralona, które technicznie stanowią część miasta, ale nie powinny znajdować się w widocznym obszarze.

Geokoder zwraca adresy, korzystając z preferowanego języka przeglądarki lub języka określonego podczas wczytywania JavaScriptu interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w  tym artykule).

Typy adresów i typy ich komponentów

Tablica types[] w GeocoderResult wskazuje typ adresu. Tablica types[] może być też zwracana w ramach GeocoderAddressComponent, aby wskazać typ danego elementu adresu. Adresy zwracane przez geokoder mogą mieć różne typy, które mogą być traktowane jako tagi. Na przykład wiele miast ma tagi typu political i locality.

Geokoder obsługuje i zwraca te typy adresów oraz typy elementów 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 reprezentujący administrację cywilną.
  • 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 zgodne z podgrupami w standardzie ISO 3166-2 i innymi rozpowszechnionymi listami. 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 wskazuje nazwany dzielnicę.
  • premise wskazuje nawaną lokalizację, zwykle budynek lub zbiór budynków o takiej samej nazwie.
  • subpremise oznacza adresowany obiekt znajdujący się poniżej poziomu nieruchomości, np. mieszkanie, lokal czy apartament.
  • 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 ma znanych typów tego składnika adresu, np. Lieu-dit we Francji.

Oprócz wymienionych powyżej elementy adresu mogą obejmować te typy.

Uwaga: ta lista nie jest wyczerpująca 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 służy jako punkt odniesienia, aby ułatwić nawigację.
  • point_of_interest wskazuje nazwane miejsce.
  • parking oznacza parking.
  • post_box wskazuje 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 pokój w budynku.
  • street_number wskazuje dokładny numer domu.
  • bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, pociągu lub transportu publicznego.

Kody stanu

Kod status może zwracać jedną z tych 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_QUERY_LIMIT" oznacza, że limit został przekroczony.
  • "REQUEST_DENIED" oznacza, że prośba została odrzucona. Strona internetowa nie może korzystać z geokodera.
  • "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.
  • "ERROR" oznacza, że żądanie przekroczyło limit czasu lub wystąpił problem z kontaktem z serwerami Google. Jeśli spróbujesz jeszcze raz, żądanie może zostać zrealizowane.

W tym przykładzie geokodujemy adres i umieszczamy znacznik w zwróconych wartościach szerokości i długości geograficznej. Pamiętaj, że uchwyt jest przekazywany jako litera funkcji anonimowej.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Zobacz przykład

Wpływ widocznego obszaru

Możesz zlecić usłudze geokodowania, aby preferowała wyniki w danym widocznym obszarze (wyrażonym jako pole ograniczające). Aby to zrobić, ustaw parametr bounds w literale obiektu GeocoderRequest, aby zdefiniować granice tego widoku. Pamiętaj, że ustawienie preferencji tylko preferuje wyniki w określonych granicach. Jeśli poza tymi granicami istnieją bardziej trafne wyniki, mogą one zostać uwzględnione.

Na przykład geokodowanie „Winnetka” zwykle zwraca ten przysiółek Chicago:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Jeśli jednak określisz parametr bounds, który definiuje prostokąt ograniczający dla doliny San Fernando w Los Angeles, geokodowanie zwróci dzielnicę o nazwie „Winnetka” w tej lokalizacji:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Uwzględnianie kodu regionu

Za pomocą parametru region możesz ustawić, aby usługa geokodowania zwracała wyniki z uwzględnieniem konkretnego regionu. Ten parametr przyjmuje kod regionu podany jako dwuznakowy (niecyfrowy) tag regionu w standardzie Unicode. Te tagi są bezpośrednio mapowane na znane wartości 2-znakowe ccTLD („domena najwyższego poziomu”), np. „uk” w „co.uk”. W niektórych przypadkach tag region obsługuje też kody ISO-3166-1, które czasami różnią się od wartości ccTLD (np. „GB” zamiast „Wielka Brytania”).

Gdy używasz parametru region:

  • Określ tylko 1 kraj lub region. Wiele wartości jest ignorowanych, co może spowodować niepowodzenie żądania.
  • Używaj tylko 2-znakowych podtagów regionów (w formacie Unicode CLDR). Wprowadzanie innych danych spowoduje wyświetlenie błędów.
  • Obsługiwane są tylko kraje i regiony wymienione w szczegółach dotyczących zasięgu Google Maps Platform.

Żądania geokodowania mogą być wysyłane w przypadku każdej domeny, w której główna aplikacja Map Google oferuje geokodowanie. Pamiętaj, że ustawienie preferencji tylko preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną istnieją bardziej trafne wyniki, mogą one zostać uwzględnione.

Na przykład geokodowanie „Toledo” zwraca ten wynik, ponieważ domyślna domena usługi geokodowania jest ustawiona na Stany Zjednoczone:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Geokodowanie „Toledo” z polem region ustawionym na 'es' (Hiszpania) zwróci hiszpańskie miasto:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Filtrowanie komponentów

Możesz skonfigurować usługę geokodowania tak, aby zwracała wyniki adresu ograniczone do określonego obszaru, używając filtra komponentów. Określ filtr w parametrze componentRestrictions. Wartości filtrów obsługują te same metody poprawiania pisowni i dopasowania częściowego co inne żądania geokodowania.

Geokodowanie zwraca tylko wyniki, które pasują do wszystkich filtrów komponentu. Oznacza to, że specyfikacje filtra są oceniane jako AND, a nie OR.

Filtr komponentów składa się z co najmniej 1 z tych elementów:

  • route pasuje do długiej lub krótkiej nazwy trasy.
  • locality dopasowuje się do typów lokalizacji i podtypów lokalizacji.
  • administrativeArea pasuje do wszystkich poziomów obszaru administracyjnego.
  • postalCode pasuje do kodów pocztowych i prefiksów kodów pocztowych.
  • Atrybut country odpowiada nazwie kraju lub dwuliterowym kodem kraju zgodnym z normą ISO 3166-1. Uwaga: interfejs API stosuje standard ISO do definiowania krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Ten przykład pokazuje, jak za pomocą parametru componentRestrictions filtrować według parametrów country i postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Realizacja w przypadku braku wyników

W przypadku odwrotnego geokodowania domyślnie obietnica jest niespełniona w przypadku wartości status=ZERO_RESULTS. W takim przypadku pola dodatkowego poziomu odpowiedzi plus_code i address_descriptor mogą być nadal wypełnione. Jeśli parametr fulfillOnZeroResults ma wartość „prawda”, wypełnia się ją w tym przypadku. Jeśli parametr fulfillOnZeroResults ma wartość Prawda, obietnica nie została zerwana i te dodatkowe pola są dostępne w obietnicy, jeśli są obecne.

Poniżej znajdziesz przykład tego zachowania w przypadku współrzędnych geograficznych w Antarktyce. Nawet jeśli nie ma wyników odwrotnego geokodowania, możemy nadal drukować kod plusa w obietnicy, jeśli ustawimy fulfillOnZeroResults=true. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Adresy – opisy

Deskryptory adresów zawierają dodatkowe informacje, które pomagają opisać lokalizację za pomocą punktów orientacyjnych i obszarów. Aby zapoznać się z tą funkcją, obejrzyj prezentację adresów.

Deskryptory adresów można włączyć za pomocą parametru extraComputations. Aby otrzymać deskryptory adresu w odpowiedzi, dodaj parametr extra_computations=ADDRESS_DESCRIPTORS do żądania geokodowania, żądania odwrotnego geokodowania lub żądania geokodowania miejsc.

Przykład geokodowania miejsc

To zapytanie zawiera adres miejsca w Delhi.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Przykład odwrotnego geokodowania

To zapytanie zawiera wartość szerokości i długości geograficznej lokalizacji w Delhi.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Przykład deskryptora adresu

Przykład address_descriptor:

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

W każdym obiekcie address_descriptor występują 2 tablice: landmarks i areas. Tablica landmarks zawiera maksymalnie 5 wyników uporządkowanych według trafności z uwzględnieniem bliskości żądanych współrzędnych, popularności punktu orientacyjnego i jego widoczności. Każdy wynik dotyczący punktu orientacyjnego zawiera te wartości:

  • place_id to identyfikator miejsca w wyniku z punktami orientacyjnymi. Zapoznaj się z omówieniem identyfikatora miejsca.
  • display_name to wyświetlana nazwa punktu orientacyjnego, która zawiera language_code i text.
  • straight_line_distance_meters to odległość w metrach między punktem wejściowym a wynikiem z użyciem punktów orientacyjnych.
  • travel_distance_meters to odległość pokonana w metrach przy użyciu sieci dróg (z wyłączeniem ograniczeń drogowych) między wejściowymi współrzędnymi a wynikami punktów orientacyjnych.
  • spatial_relationship to szacowany związek między współrzędnymi wejściowymi a wynikiem dotyczącym punktów orientacyjnych:
    • "NEAR" to domyślna relacja, gdy nie ma zastosowania żadna z tych relacji.
    • "WITHIN", gdy współrzędna wejściowa znajduje się w granicach struktury powiązanej z punktem orientacyjnym.
    • "BESIDE" gdy współrzędne wejściowe są bezpośrednio przy zabytku lub punkcie dostępu do zabytku.
    • "ACROSS_THE_ROAD", gdy współrzędne wejściowe znajdują się po przeciwnej stronie punktu orientacyjnego po drugiej stronie trasy.
    • "DOWN_THE_ROAD", gdy współrzędna wejściowa znajduje się na tej samej trasie co punkt orientacyjny, ale nie "BESIDES" ani "ACROSS_THE_ROAD".
    • "AROUND_THE_CORNER" gdy współrzędne wejściowe znajdują się na drodze prostopadłej do punktu orientacyjnego (ograniczone do jednego skrętu).
    • "BEHIND" gdy współrzędne wejściowe znajdują się w pobliżu punktu orientacyjnego, ale daleko od punktu dostępu.
  • types to typy miejsc związane z miejscem.

Obiekt areas zawiera maksymalnie 3 odpowiedzi i ogranicza się do miejsc, które reprezentują małe regiony, takie jak dzielnice, mniejsze jednostki administracyjne i duże kompleksy. Obszary zawierające podane współrzędne są wyświetlane jako pierwsze i posortowane od najmniejszego do największego. Każdy wynik areas zawiera te wartości:

  • place_id to identyfikator miejsca w wyniku „areas”. Zapoznaj się z omówieniem identyfikatora miejsca.
  • display_name to wyświetlana nazwa obszaru, która zawiera language_code i text.
  • containment to szacowany związek zasięgu między współrzędnymi wejściowymi a wynikiem obszarów:
    • "NEAR" to domyślna relacja, gdy nie ma zastosowania żadna z tych relacji.
    • "WITHIN" gdy współrzędna wejściowa jest zbliżona do środka obszaru.
    • "OUTSKIRTS" gdy współrzędna wejściowa jest blisko krawędzi obszaru.

Zasięg deskryptora adresu

Deskryptory adresów są dostępne w Google Analytics w Indiach. Korzystanie z deskryptorów adresów w Indiach nie wiąże się z dodatkowymi kosztami i jest objęte dotychczasową poziom SKU Essentials (geokodowanie, Indie).

Prześlij opinię

Ta funkcja jest dostępna we wszystkich regionach. Ta funkcja jest dostępna w wersji GA w Indiach, a w pozostałych regionach jest w fazie eksperymentalnej przed GA. Będziemy wdzięczni za opinię:

Odwrotne geokodowanie (wyszukiwanie adresu)

Termin geokodowanie odnosi się zazwyczaj do przekształcania adresu w postaci czytelnej dla człowieka w lokalizację na mapie. Proces odwrotny, czyli przekształcanie lokalizacji na mapie w adres zrozumiały dla człowieka, nazywa się odwrotnym geokodowaniem.

Zamiast podawać tekstowy parametr address, podaj w parametrze location pary współrzędnych geograficzne (szerokość/długość geograficzna) rozdzielone przecinkami.

W tym przykładzie geokodujemy współrzędne geograficzne i wyśrodkowujemy mapę na tej lokalizacji, wyświetlając okno z sformatowanym adresem:

TypeScriptJavaScript
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts
 
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Zobacz przykład

Wypróbuj próbkę

Pamiętaj, że w poprzednim przykładzie wyświetliliśmy pierwszy wynik, wybierając results[0]. Odwrotny geokodownik często zwraca więcej niż 1 wynik. Adresy geokodowane to nie tylko adresy pocztowe, ale dowolny sposób na określenie lokalizacji geograficznej. Podczas geokodowania punktu w mieście Chicago może on zostać oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są adresami dla geokodera. Odwrotny geokodownik zwraca wszystkie te wyniki.

Geokodowanie odwrotne umożliwia dopasowanie jednostek politycznych (krajów, miast, dzielnic), adresów ulic i kodów pocztowych.

Oto przykład listy adresów, która może zostać zwrócona przez powyższe zapytanie: 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Adresy są zwracane w kolejności od najlepszego do najgorszego dopasowania. Zazwyczaj im dokładniejszy adres, tym ważniejszy wynik, jak w tym przypadku. Pamiętaj, że zwracamy różne typy adresów, od najbardziej dokładnego adresu po bardziej szczegółowe jednostki polityczne, takie jak dzielnice, miasta, hrabstwa, województwa itp. Jeśli chcesz dopasować bardziej ogólny adres, sprawdź pole results[].types.

Uwaga: odwrotne geokodowanie nie jest nauką ścisłą. Geokoder spróbuje znaleźć najbliższą lokalizację z adresem w określonym zakresie tolerancji.

Pobieranie adresu na podstawie identyfikatora miejsca

Podaj placeId, aby znaleźć adres podany w identyfikatorze miejsca. Identyfikator miejsca to unikalny identyfikator, którego można używać w innych interfejsach API Google. Możesz na przykład podać wartość placeId zwróconą przez interfejs Roads API, aby uzyskać adres punktu załamania. Więcej informacji o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatorów miejsc.

Gdy podajesz placeId, żądanie nie może zawierać tych pól:

  • address
  • latLng
  • location
  • componentRestrictions

W tym przykładzie funkcja przyjmuje identyfikator miejsca, wyszukuje odpowiadający mu adres i środkuje na nim mapę. Wyświetla się też okno z sformatowanym adresem danego miejsca:

TypeScriptJavaScript
// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts
 
// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Zobacz przykład

Wypróbuj próbkę