Usługa geokodowania

Opis

Geokodowanie to proces przeliczania adresów (np. „1600 Amphitheatre Parkway, Mountain View, CA”) na współrzędne geograficzne (np. szerokość geograficzną 37.423021 i długość geograficzną -122,083739), których możesz użyć do umieszczenia znaczników lub umiejscowienia mapy.

Odwrotne geokodowanie to proces przekształcania 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ę geokodera do dynamicznego geokodowania i odwrotnego geokodowania na podstawie danych wejściowych użytkownika. Jeśli zamiast tego chcesz geokodować znane adresy statyczne, zapoznaj się z usługą internetową geokodowania.

Pierwsze kroki

Zanim skorzystasz z usługi Geocoding w interfejsie Maps JavaScript API, sprawdź, czy interfejs Geocoding API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany na potrzeby Maps JavaScript API.

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

  1. Otwórz Google Cloud Console.
  2. Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany na potrzeby interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Geocoding API.
  4. Jeśli widzisz interfejs API na liście, nie musisz nic więcej robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. Aby wyświetlić kartę Biblioteka, u góry strony wybierz WŁĄCZ API. Możesz też wybrać w menu po lewej stronie opcję Biblioteka.
    2. Wyszukaj Geocoding API, a potem wybierz go z listy wyników.
    3. Kliknij WŁĄCZ. Po zakończeniu procesu Geocoding API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

16 lipca 2018 roku w Mapach Google, trasach i miejscach zaczęł obowiązywać nowy abonament (płatność według wykorzystania). Więcej informacji o nowych cenach i limitach wykorzystania usługi geokodowania JavaScript znajdziesz w sekcji Wykorzystanie i rozliczenia interfejsu Geocoding API.

Zasady

Z usługi Geocoding należy korzystać zgodnie z zasadami opisanymi dla interfejsu Geocoding API.

Żądania geokodowania

Dostęp do usługi Geocoding jest asynchroniczny, ponieważ interfejs API Map Google musi wywoływać serwer zewnętrzny. Dlatego musisz przekazać metodę callback, która zostanie wykonana po zakończeniu żą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 możesz uzyskać w kodzie za pomocą obiektu konstruktora google.maps.Geocoder. Metoda Geocoder.geocode() inicjuje żądanie do usługi geokodowania, przekazując do niej literał obiektu GeocoderRequest zawierający terminy wejściowe i metodę wywołania zwrotnego, która zostanie wykonana po otrzymaniu odpowiedzi.

Literał obiektu GeocoderRequest zawiera te pola:

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

Parametry wymagane: musisz podać jedno i tylko jedno z tych pól:

  • address – adres na potrzeby geokodowania.
         lub
    location – wartość LatLng (lub LatLngLiteral), dla której chcesz uzyskać najbliższy, zrozumiały dla człowieka adres. Geokoder wykonuje odwrotny geokod. Więcej informacji znajdziesz w artykule na temat odwrotnego geokodowania.
         lub
    placeId – identyfikator miejsca, dla którego chcesz uzyskać najbliższy, czytelny dla człowieka adres. Więcej informacji o pobieraniu adresu dla identyfikatora miejsca.

Parametry opcjonalne:

  • bounds – element LatLngBounds, który określa stronniczość geograficznie i lepiej eksponuje wyniki. Parametr bounds będzie miał wpływ tylko na wyniki generowane przez geokodera, a nie na jego całkowite ograniczenie. Więcej informacji o promowaniu widocznego obszaru znajdziesz poniżej.
  • componentRestrictions – umożliwia ograniczenie wyników do określonego obszaru. Więcej informacji o filtrowaniu komponentów znajdziesz poniżej.
  • region – kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode. W większości przypadków tagi te są odwzorowywane bezpośrednio na znane dwuliterowe wartości domeny najwyższego poziomu („domena najwyższego poziomu”). Parametr region będzie miał wpływ tylko na wyniki generowane przez geokodera, a nie na jego całkowite ograniczenie. Więcej informacji o promowaniu kodu regionu znajdziesz poniżej.

Odpowiedzi na temat geokodowania

Usługa Geocoding wymaga metody wywołania zwrotnego po pobraniu wyników geokodera. To wywołanie zwrotne powinno przekazywać 2 parametry do przechowywania kodów results i status (w tej kolejności).

Wyniki geokodowania

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

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 objaśniamy te pola:

  • types[] to tablica wskazująca typ adresu zwracanego wyniku. Ta tablica zawiera zestaw 0 lub więcej tagów identyfikujących typ cechy zwróconej w wyniku. Na przykład geokod „Chicago” zwraca wartość „locality”, która wskazuje, że „Chicago” jest miastem, a także „polityczne”, które wskazuje, że jest ono podmiotem politycznym. Więcej informacji o typach adresów i typach komponentów adresu znajdziesz poniżej.
  • formatted_address to ciąg znaków zawierający czytelny dla człowieka adres tej lokalizacji.

    Często jest to 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 jednego lub większej liczby komponentów 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żyj poszczególnych komponentów adresu, które odpowiedź interfejsu API zawiera oprócz sformatowanego pola adresu.

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

    Każdy komponent adresu zwykle zawiera te pola:

    • types[] to tablica wskazująca typ składnika adresu. Zobacz listę obsługiwanych typów.
    • long_name to pełny opis tekstowy lub nazwa składnika adresu zwracanego przez geokoder.
    • 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ć w polu long_name nazwę „Alaska” i zasadę 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 nie musi zawierać wszystkich podmiotów politycznych z adresem (z wyjątkiem tych uwzględnionych w elemencie formatted_address). Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj odwrotnego geokodowania, przekazując w żądaniu szerokość i długość geograficzną adresu jako parametr.
    • Nie gwarantujemy, że format odpowiedzi będzie taki sam w różnych żądaniach. Liczba address_components różni się w zależności od żądanego adresu i może się zmieniać w przypadku tego samego adresu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmieniać. W późniejszej odpowiedzi może brakować konkretnego komponentu.

    Więcej informacji o typach adresów i typach komponentów adresu znajdziesz poniżej.

  • Wartość partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, chociaż został dopasowany do części żądanego adresu. Warto sprawdzić pierwotne zgłoszenie pod kątem błędów pisowni lub niepełnego adresu.

    Dopasowania częściowe najczęściej występują w przypadku adresów, których nie ma w rejonie przesłanym 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, Wielka Brytania” zwróci częściowe dopasowanie zarówno do ulicy Jana, jak i przy uliczce Jana Chrzciciela. Pamiętaj, że jeśli żądanie zawiera nieprawidłowo wpisany komponent adresu, usługa geokodowania może zaproponować adres alternatywny. Sugestie uruchamiane w ten sposób zostaną również oznaczone jako częściowe dopasowanie.

  • place_id to unikalny identyfikator miejsca, który może być używany z innymi interfejsami API Google. Możesz np. użyć pola place_id z biblioteką interfejsu API Miejsc Google, aby uzyskać szczegółowe informacje o firmie lokalnej, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zapoznaj się z omówieniem identyfikatorów miejsc.
  • postcode_localities[] to tablica oznaczająca wszystkie miejscowości zawarte w danym kodzie pocztowym. Występuje tylko wtedy, gdy wynik jest kodem pocztowym obejmującym wiele miejscowości.

  • Pole geometry zawiera te informacje:

    • location zawiera geograficzną wartość szerokości i długości geograficznej. 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. Obecnie obsługiwane są te wartości:
      • ROOFTOP oznacza, że zwrócony wynik odzwierciedla dokładny geokod.
      • Wartość RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowania). Wyniki interpolowane są zwykle zwracane, gdy geokodery dachów są niedostępne w przypadku adresu.
      • Wartość GEOMETRIC_CENTER wskazuje, że zwrócony wynik to geometryczny środek wyniku, np. linia łamana (na przykład ulica) lub wielokąt (region).
      • APPROXIMATE oznacza, że zwrócony wynik jest przybliżony.

    • viewport przechowuje zalecany widoczny obszar dla zwracanego wyniku.
    • bounds (zwracany opcjonalnie) przechowuje LatLngBounds, który może w pełni 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 nie powinny być wyświetlane w widocznym obszarze.

Adresy będą zwracane przez geocoder z wykorzystaniem ustawienia języka preferowanego w przeglądarce lub języka określonego podczas wczytywania kodu JavaScript interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w sekcji Lokalizacja).

Typy adresów i typy komponentów adresu

Tablica types[] w GeocoderResult wskazuje typ adresu. Tablica types[] może też być zwracana w elemencie GeocoderAddressComponent, aby wskazać typ konkretnego komponentu adresu. Adresy zwrócone przez geokodera mogą mieć kilka typów. Niektóre z nich mogą być uznawane za tagi. Na przykład wiele miast jest oznaczonych tagami political i locality.

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

  • street_address wskazuje dokładny adres.
  • route oznacza trasę nazwaną (np. 402).
  • intersection oznacza główne skrzyżowanie, zwykle obejmujące 2 główne drogi.
  • political wskazuje podmiot polityczny. Ten typ oznacza zazwyczaj wielokąt reprezentujący administrację cywilną.
  • country wskazuje krajowy podmiot polityczny i jest zwykle najwyższym typem kolejności zwracanym przez geokodera.
  • administrative_area_level_1 wskazuje podmiot cywilny pierwszego stopnia 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 Admin_area_level_1 są bardzo zbliżone do nazw według normy ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy jednak zagwarantować, że wyniki geokodowania są oparte na różnych sygnałach i danych o lokalizacji.
  • administrative_area_level_2 wskazuje podmiot cywilny drugiego stopnia poniżej poziomu kraju. W Stanach Zjednoczonych tymi poziomami administracyjnymi są hrabstwa. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • Pole administrative_area_level_3 wskazuje podmiot cywilny trzeciego stopnia poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_4 wskazuje 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 wskazuje podmiot cywilny piątego rzędu niższego w danym kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • administrative_area_level_6 wskazuje 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 wskazuje podmiot cywilny siódmego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
  • colloquial_area wskazuje często używaną alternatywną nazwę elementu.
  • locality oznacza miasto lub miasto będące podmiotem politycznym.
  • sublocality wskazuje podmiot cywilny pierwszego stopnia poniżej rejonu. W przypadku niektórych lokalizacji może być przypisywany 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 nazwany obszar
  • premise wskazuje nazwaną lokalizację, zwykle budynek lub zespół budynków o wspólnej nazwie
  • Element subpremise wskazuje element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle pojedynczy budynek w grupie budynków o wspólnej nazwie.
  • plus_code wskazuje zakodowane odwołanie do lokalizacji uzyskane na podstawie szerokości i długości geograficznej. Kody plus mogą zastąpić adresy ulic w miejscach, w których nie ma ich (gdzie budynki nie są numerowane lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
  • postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie kraju.
  • natural_feature wskazuje wyróżniający się obiekt naturalny.
  • airport oznacza lotnisko.
  • park wskazuje park nazwany.
  • point_of_interest wskazuje nazwane miejsce. Takie ważne miejsca są zwykle popularnymi podmiotami lokalnymi, których nie da się łatwo umieścić w innych kategoriach, takich jak „Empire State Building” czy „Wieża Eiffla”.

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

Oprócz powyższych typów adresów komponenty mogą obejmować wymienione poniżej.

Uwaga: ta lista nie jest pełna i może ulec zmianie.

  • floor wskazuje piętro adresu budynku.
  • Typ establishment oznacza zwykle 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 adresie 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:

  • Wartość "OK" oznacza, że nie wystąpiły żadne błędy. Adres został przeanalizowany poprawnie i zwrócono co najmniej 1 kod geograficzny.
  • "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 kod address.
  • "OVER_QUERY_LIMIT" oznacza, że limit został przekroczony.
  • "REQUEST_DENIED" oznacza, że Twoja prośba została odrzucona. Strona internetowa nie może używać geokodera.
  • Typ "INVALID_REQUEST" zwykle wskazuje, że brakuje zapytania (address, components lub latlng).
  • "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się udać.
  • "ERROR" oznacza, że upłynął limit czasu żądania lub wystąpił problem ze skontaktowaniem się z serwerami Google. Jeśli spróbujesz ponownie, żądanie może się udać.

W tym przykładzie geokodujemy adres i umieszczamy znacznik w zwróconych wartościach szerokości i długości geograficznej. Pamiętaj, że moduł obsługi 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

Promowanie widocznego obszaru

Możesz poinstruować usługę Geocoding, aby preferowała wyniki w danym widocznym obszarze (wyrażonym w postaci ramki ograniczającej). Aby to zrobić, ustaw parametr bounds w literale obiektu GeocoderRequest w celu określenia granic tego widocznego obszaru. Pamiętaj, że odchylenie preferuje wyniki tylko w obrębie tych granic. Jeśli wyniki są poza tymi granicami, możemy je uwzględnić.

Na przykład geokod dla nazwy „Winnetka” zazwyczaj zwraca to przedmieście 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"
}

Jednak określenie parametru bounds definiującego ramkę ograniczającą dla doliny San Fernando Los Angeles powoduje, że geokod zwraca 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"
}

Promowanie kodu regionu

Za pomocą parametru region możesz ustawić usługę Geocoding, aby zwracała wyniki uzależnione od konkretnego regionu. Ten parametr wykorzystuje kod regionu, określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode. Te tagi są mapowane bezpośrednio na znane wartości ccTLD („domena najwyższego poziomu”), takie jak „pl” w domenie „co.uk”. W niektórych przypadkach tag region obsługuje też kody ISO-3166-1, które czasami różnią się od wartości domeny ccTLD (np. „GB” w przypadku Wielkiej Brytanii).

Jeśli używasz parametru region:

  • Podaj tylko 1 kraj lub region. Wiele wartości będzie ignorowanych, co może spowodować, że żądanie nie zostanie zrealizowane.
  • Używaj tylko dwuznakowych podtagów regionów (format Unicode CLDR). Wszystkie inne dane wejściowe będą powodować błędy.
  • Obsługiwane są tylko kraje i regiony wymienione w szczegółach zasięgu Google Maps Platform.

Żądania geokodowania można wysyłać do każdej domeny, w której dostępna jest główna aplikacja Map Google. Pamiętaj, że odchylenie preferuje wyniki tylko z konkretnej domeny. Jeśli bardziej trafne wyniki istnieją poza tą domeną, mogą zostać uwzględnione.

Na przykład geokod dla nazwy „Toledo” zwraca taki wynik, ponieważ domyślną domeną usługi Geocoding Service są 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"
}

Geokod hasła „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

Za pomocą filtra komponentów możesz ustawić usługę Geocoding Service tak, aby zwracała wyniki dotyczące adresów ograniczonych do określonego obszaru. 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.

Geokoder zwraca tylko wyniki, które pasują do wszystkich filtrów komponentów. Oznacza to, że sprawdza specyfikację filtra za pomocą operatora ORAZ, a nie LUB.

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

  • route pasuje do długiej lub krótkiej nazwy trasy.
  • locality pasuje do typu lokalizacji i podrejonu.
  • administrativeArea pasuje do wszystkich poziomów obszaru administracyjnego.
  • postalCode pasuje do kodów pocztowych i prefiksów kodów pocztowych.
  • country jest zgodny z nazwą kraju lub dwuliterowym kodem kraju w formacie ISO 3166-1. Uwaga: interfejs API jest zgodny ze standardem ISO przy definiowaniu krajów, a filtrowanie działa najlepiej, gdy używany jest odpowiedni kod ISO kraju.

Poniższy przykład pokazuje użycie parametru componentRestrictions do filtrowania według wartości 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);
  }
});
}

Odwrotne geokodowanie (wyszukiwanie adresu)

Termin geokodowanie zwykle odnosi się do przekształcenia zrozumiałego dla człowieka adresu na lokalizację na mapie. Odwrotna translacja lokalizacji na mapie na format czytelny dla człowieka to odwrotne geokodowanie.

Zamiast podawać tekstową wartość address, podaj w parametrze location parę szerokość/długość geograficzna rozdzielonych przecinkami.

Poniższy przykład pokazuje wartość szerokości/długości geograficznej i wyśrodkowuje mapę na danej lokalizacji, co powoduje wyświetlenie okna informacyjnego ze sformatowanym adresem:

TypeScript

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

JavaScript

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 fragment

W poprzednim przykładzie pokazaliśmy pierwszy wynik, wybierając results[0]. Odwrotny geokoder często zwraca więcej niż 1 wynik. Geokodowane adresy to nie tylko adresy pocztowe, lecz także sposób geokodowania lokalizacji. Na przykład podczas geokodowania punktu w Chicago punkt przetwarzania danych może być oznaczony jako adres, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie dane są adresami geokodera. Odwrotny geokoder zwraca wszystkie te wyniki.

Odwrotny geokoder dopasowuje jednostki polityczne (kraje, prowincje, miasta i dzielnice), adresy i kody pocztowe.

Oto przykład listy adresów, które może zwrócić 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ą wyświetlane w kolejności od najlepszych do najmniejszych dopasowań. Ogólnie bardziej dokładny adres jest najbardziej widocznym wynikiem, jak w tym przypadku. Pamiętaj, że zwracamy różnego rodzaju adresy – od najwęższego adresu pocztowego po mniej szczegółowe podmioty polityczne, takie jak dzielnice, miasta, hrabstwa, stany itp. Jeśli chcesz dopasować bardziej ogólny adres, zapoznaj się z polem results[].types.

Uwaga: odwrotne geokodowanie nie jest nauką ścisłą. Geokoder spróbuje znaleźć najbliższą, adresowaną lokalizację z zachowaniem określonej tolerancji.

Pobieranie adresu dla identyfikatora miejsca

Aby znaleźć adres dla danego identyfikatora miejsca, wpisz parametr placeId. Identyfikator miejsca to unikalny identyfikator, którego można używać z innymi interfejsami API Google. Aby uzyskać adres przyciąganego punktu, możesz na przykład podać wartość placeId zwracaną przez interfejs Roads API. Więcej informacji o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.

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

  • address
  • latLng
  • location
  • componentRestrictions

Podany niżej przykład akceptuje identyfikator miejsca, znajduje odpowiedni adres i ustawia mapę na środku tej lokalizacji. Pojawi się też okno informacyjne z sformatowanym adresem odpowiedniego miejsca:

TypeScript

// 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

JavaScript

// 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 fragment