Usługa geokodowania

Opis

Geokodowanie to proces przekształcania adresów (np. „1600 Amphitheatre Parkway, Mountain View, CA”) na współrzędne geograficzne (np. szerokość 37.423021 i długość geograficzną -122.083739), których możesz użyć do umieszczenia znaczników lub położenia 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 dla danego identyfikatora miejsca.

Interfejs Maps JavaScript API udostępnia klasę geokodera do geokodowania i odwrotnego geokodowania na podstawie danych wejściowych użytkownika. Jeśli zamiast tego chcesz geokodować statyczne, znane adresy, zapoznaj się z usługą internetową do 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 konsolę Google Cloud.
2. Kliknij przycisk Wybierz projekt, a następnie wybierz projekt 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 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ć Biblioteka w menu po lewej stronie.
   2. Wyszukaj Geocoding API, a potem wybierz go z listy wyników.
   3. Wybierz 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 zaczęliśmy obowiązywać nowy abonament rozliczany według wykorzystania. W przypadku Map, tras i Miejsc Google obowiązuje nowy abonament. Aby dowiedzieć się więcej o nowych cenach i limitach wykorzystania usługi JavaScript Geocoding, zapoznaj się z sekcją Korzystanie i płatności dotyczącą interfejsu Geocoding API.

Zasady

Korzystanie z usługi Geocoding musi być zgodne z zasadami opisanymi dla interfejsu Geocoding API.

Żądania geokodowania

Dostęp do usługi Geocoding jest asynchroniczny, ponieważ interfejs Google Maps API musi wywoływać serwer zewnętrzny. Dlatego musisz przekazać metodę wywołania zwrotnego, 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ż jeden wynik.

Dostęp do usługi geokodowania interfejsu API Map Google w kodzie możesz uzyskać za pomocą obiektu konstruktora google.maps.Geocoder. Metoda Geocoder.geocode() inicjuje żądanie do usługi geokodowania, przekazując go literał obiektu GeocoderRequest zawierający hasła wejściowe i metodę wywołania zwrotnego, która jest wykonywana po otrzymaniu odpowiedzi.

Literał obiektu 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, na który chcesz geokodować.
       lub
  location – LatLng (lub LatLngLiteral), dla którego chcesz uzyskać najbliższy, czytelny dla człowieka adres. Geokoder wykonuje odwrotny geokoder. Więcej informacji znajdziesz na stronie o odwrotnym geokodowaniu.
       lub
  placeId – identyfikator miejsca, dla którego chcesz uzyskać najbliższy, czytelny dla człowieka adres. Dowiedz się więcej o pobieraniu adresu dla identyfikatora miejsca.

Parametry opcjonalne:

• bounds – LatLngBounds, w którym lepiej oddziałuje na wyniki geokodu. Parametr bounds będzie miał wpływ tylko na wyniki generowane przez geokodera, a nie jego pełne ograniczenie. Więcej informacji o promowaniu widocznego obszaru znajdziesz poniżej.
• componentRestrictions – umożliwia ograniczenie wyników do konkretnego 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 dwuznakowe wartości domeny ccTLD („domena najwyższego poziomu”). Parametr region ma wpływ tylko na wyniki generowane przez geokodera, a nie jego pełne ograniczanie. Więcej informacji o promowaniu kodu regionu znajdziesz poniżej.

Odpowiedzi na geokodowanie

Usługa Geocoding wymaga metody wywołania zwrotnego po pobraniu wyników geokodera. To wywołanie zwrotne powinno przekazywać 2 parametry umożliwiające przechowywanie 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 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 objaśniamy te pola:

• types[] to tablica wskazująca typ adresu zwracanego wyniku. Ta tablica zawiera zbiór 0 lub więcej tagów identyfikujących typ cechy zwracanej w wyniku. Na przykład geokod „Chicago” zwraca ciąg „locality”, który wskazuje, że „Chicago” to miasto, i dodatkowo „polityczne”, które wskazuje, że podmiot polityczny. 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 równoważny adres pocztowy. Pamiętaj, że w niektórych krajach (np. w Wielkiej Brytanii) nie można rozpowszechniać prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

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

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

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

  Każdy komponent adresu zwykle zawiera te pola:

  • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
  • long_name to pełny opis lub nazwa składnika adresu zwracanego przez geokodera.
  • short_name to skrócona nazwa tekstowa komponentu adresu, jeśli jest dostępna. Na przykład składnik adresu dla stanu Alaska może mieć atrybut long_name o nazwie „Alaska” oraz wartość short_name w polu „AK” z dwuliterowym skrótem pocztowym.

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

  • Tablica komponentów adresu może zawierać więcej komponentów niż formatted_address.
  • Tablica nie musi zawierać wszystkich podmiotów politycznych z adresem (oprócz tych uwzględnionych w elemencie formatted_address). Aby pobrać wszystkie jednostki polityczne, które mają określony adres, użyj odwrotnego geokodowania, podając szerokość i długość geograficzną adresu jako parametr w żądaniu.
  • Nie możemy zagwarantować, że format odpowiedzi będzie taki sam między żądaniami. Liczba address_components różni się w zależności od żądanego adresu i może się z czasem zmieniać dla tego samego adresu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmieniać. Konkretnego komponentu może brakować w późniejszej odpowiedzi.

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

• partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, mimo że udało się dopasować część żądanego adresu. Warto sprawdzić w pierwotnej prośbie, czy adres nie zawiera błędów pisowni lub zawiera niepełny adres.

  Dopasowania częściowe najczęściej występują w przypadku adresów, które nie występują w rejonie podanym w żądaniu. Dopasowania częściowe mogą zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym rejonie. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera komponent adresu z błędną pisownią, usługa geokodowania może zaproponować alternatywny adres. Sugestie uruchamiane w ten sposób będą również oznaczane jako dopasowania częściowe.

• place_id to unikalny identyfikator miejsca, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć obiektu place_id z biblioteką interfejsu Google Places API, aby uzyskać szczegółowe informacje o firmie lokalnej, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zobacz omówienie identyfikatorów miejsc.
• postcode_localities[] to tablica określająca wszystkie miejscowości w danym kodzie pocztowym. Jest widoczna tylko wtedy, gdy wynik to kod pocztowy obejmujący wiele miejscowości.

• geometry zawiera następujące informacje:

  • location zawiera geokodowaną wartość szerokości i długości geograficznej. Zwracamy tę lokalizację jako obiekt LatLng, a nie 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) interpolację między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki z interpolacji są zwykle zwracane, gdy geokody dachowe są niedostępne w przypadku adresu.
    • GEOMETRIC_CENTER wskazuje, że zwrócony wynik jest geometrycznym środkiem wyniku, np. linia łamana (na przykład ulica) lub wielokątem (region).
    • APPROXIMATE wskazuje, że zwrócony wynik jest przybliżony.
  
  
  • viewport przechowuje zalecany widoczny obszar dla zwróconego wyniku.
  • bounds (zwracany opcjonalnie) przechowuje LatLngBounds, który może zawierać pełny wynik. Pamiętaj, że te granice mogą się różnić od zalecanego widocznego obszaru. Na przykład San Francisco obejmuje wyspy Farallona, które technicznie są częścią miasta, ale nie powinny być zwracane w widocznym obszarze.

Adresy będą zwracane przez Geocoder z użyciem ustawienia języka preferowanego w przeglądarce lub języka określonego podczas wczytywania JavaScriptu interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w artykule o lokalizacji).

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 określonego komponentu adresu. Adresy zwracane przez geokodera mogą mieć kilka typów. Na przykład wiele miast jest oznaczonych tagami typu political i locality.

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

• street_address wskazuje dokładny adres.
• route wskazuje nazwaną trasę (np. „E701”).
• intersection oznacza główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.
• political oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt związany z administracją cywilną.
• country oznacza krajowy podmiot polityczny i zwykle jest najwyższym typem porządku zwracanym przez Geocoder.
• administrative_area_level_1 oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są stanami. Nie we wszystkich krajach obowiązują te poziomy administracyjne. W większości przypadków krótkie nazwy są zbliżone do nazw z normą ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy tego jednak zagwarantować, ponieważ wyniki geokodowania opierają się na różnych sygnałach i danych o lokalizacji.
• administrative_area_level_2 oznacza podmiot cywilny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są hrabstwami. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_3 oznacza podmiot cywilny trzeciego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_4 oznacza podmiot cywilny czwartego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_5 oznacza podmiot cywilny piątego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_6 oznacza podmiot cywilny szóstego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• administrative_area_level_7 oznacza podmiot cywilny siódmego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
• colloquial_area wskazuje często używaną nazwę alternatywną jednostki.
• locality oznacza miejskie podmioty polityczne.
• sublocality wskazuje podmiot cywilny pierwszego rzędu poniżej rejonu. W przypadku niektórych lokalizacji może zostać wyświetlony jeden z dodatkowych typów: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
• neighborhood wskazuje nazwę okolicy
• premise oznacza nazwaną lokalizację, zwykle budynek lub zespół budynków o wspólnej nazwie
• subpremise oznacza element pierwszego rzędu pod nazwaną lokalizacją, zwykle pojedynczy budynek należący do zespołu budynków o wspólnej nazwie
• plus_code oznacza zakodowane odniesienie do lokalizacji na podstawie szerokości i długości geograficznej. Kody plus mogą zastąpić adresy ulic w miejscach, w których one nie istnieją (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
• postal_code wskazuje kod pocztowy używany w danym kraju do adresowania przesyłek pocztowych.
• natural_feature wskazuje ważny obiekt naturalny.
• airport oznacza lotnisko.
• park wskazuje park nazwany.
• point_of_interest wskazuje nazwane miejsce. Takie ważne miejsca to zwykle doskonałe lokalne jednostki, których nie da się łatwo przypisać do innych kategorii, takich jak „Empire State Building” czy „wieża Eiffla”.

Pusta lista typów oznacza, że nie ma znanych typów dla danego komponentu adresu (np. Lieu-dit we Francji).

Oprócz powyższych typów komponenty adresu mogą też obejmować poniższe typy.

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

• floor wskazuje piętro w adresie budynku.
• Typ establishment zwykle oznacza miejsce, które nie zostało jeszcze sklasyfikowane.
• landmark wskazuje miejsce w pobliżu, które jest używane jako punkt odniesienia, aby ułatwić nawigację.
• point_of_interest wskazuje nazwane miejsce.
• parking oznacza parking lub strukturę parkingową.
• post_box wskazuje konkretną skrytkę pocztową.
• postal_town oznacza grupę obszarów geograficznych, np. locality i sublocality, używaną w adresach pocztowych w niektórych krajach.
• room wskazuje salę, w której znajduje się adres budynku.
• street_number wskazuje dokładny numer ulicy.
• bus_station, train_station i transit_station wskazują lokalizację przystanku autobusowego, pociągu lub transportu publicznego.

Kody stanu

Kod status może zwracać jedną z tych wartości:

• "OK" oznacza, że nie wystąpiły żadne błędy. Adres został pomyślnie przeanalizowany i zwrócono co najmniej jeden geokod.
• "ZERO_RESULTS" oznacza, że geokod został przetworzony pomyślnie, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder przekazał nieistniejący obiekt address.
• "OVER_QUERY_LIMIT" oznacza, że przekraczasz limit.
• "REQUEST_DENIED" oznacza, że Twoja prośba została odrzucona. Na stronie nie można używać geokodera.
• Parametr "INVALID_REQUEST" zwykle wskazuje, że brakuje zapytania (address, components lub latlng).
• "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może zostać zrealizowane.
• "ERROR" oznacza, że upłynął limit czasu żądania lub wystąpił problem z połączeniem z serwerami Google. Jeśli spróbujesz ponownie, żą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 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żanym w ramce ograniczającej). Aby to zrobić, ustaw parametr bounds w literale obiektu GeocoderRequest w celu określenia granic tego widocznego obszaru. Pamiętaj, że promowanie tylko preferuje wyniki w obrębie tych granic. Jeśli poza tymi granicami są bardziej trafne wyniki, możemy je uwzględnić.

Na przykład geokod dla nazwy „Winnetka” zwykle 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ą dolinę San Fernando w Los Angeles powoduje, że ten geokod zwraca dzielnicę „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 uporządkowane względem konkretnego regionu. Ten parametr przyjmuje kod regionu, określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode. Te tagi są odwzorowywane bezpośrednio na dwuznakowe wartości domeny 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 słowa „Wielka Brytania”).

Gdy używasz parametru region:

• Podaj tylko 1 kraj lub region. Wiele wartości zostanie zignorowanych, co może spowodować nieudane żądanie.
• 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 główna aplikacja Map Google oferuje geokodowanie. Pamiętaj, że promowanie tylko preferuje wyniki z konkretnej domeny. Jeśli poza tą domeną są bardziej trafne wyniki, możemy je uwzględnić.

Na przykład geokod dla hasła „Toledo” zwraca ten wynik, ponieważ domyślną domeną usługi Geocoding 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 dla „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ć w usłudze Geocoding Service zwracanie wyników adresów ograniczonych do określonego obszaru. Określ filtr w parametrze componentRestrictions. Wartości filtrów obsługują te same metody korekty pisowni i dopasowania częściowego co inne żądania geokodowania.

Geokoder zwraca tylko wyniki pasujące do wszystkich filtrów komponentów. Oznacza to, że specyfikacja filtra jest oceniana 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 dopasowań do typów lokalnych i podrejonów.
• administrativeArea odpowiada wszystkim poziomom obszaru administracyjnego.
• postalCode pasuje do kodów pocztowych i prefiksów kodów pocztowych.
• country to nazwa kraju lub dwuliterowy kod kraju zgodny z normą ISO 3166-1. Uwaga: interfejs API jest zgodny ze standardem ISO przy definiowaniu krajów, a filtrowanie działa najlepiej, gdy używasz odpowiedniego kodu ISO kraju.

Poniższy przykład pokazuje, jak używać parametru componentRestrictions do filtrowania według właściwoś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 oznacza tłumaczenie adresu zrozumiałego dla człowieka na lokalizację na mapie. Odwrotny proces, czyli przekształcenie lokalizacji na mapie na adres zrozumiały dla człowieka, to odwrotne geokodowanie.

Zamiast podawać tekstową wartość address, w parametrze location podaj rozdzieloną przecinkami parę szerokości i długości geograficznej.

Poniższy przykład geokodu określa wartość szerokości/długości geograficznej i wyśrodkowuje mapę na tej lokalizacji, wyświetlając okno informacyjne ze sformatowanym adresem:

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

Zwróć uwagę, że w poprzednim przykładzie pierwszy wynik pokazaliśmy, wybierając results[0]. Odwrotny geokoder często zwraca więcej niż jeden wynik. Geokodowane adresy to nie tylko adresy pocztowe, ale też wszelkiego rodzaju nazwy geograficzne. Na przykład podczas geokodowania punktu w Chicago punkt geokodowany można oznaczyć jako ulicę i numer domu, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie to adresy do geokodera. Odwrotny geokoder zwraca wszystkie te wyniki.

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

Oto przykład listy adresów, które może zwrócić 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 największej do najmniejszej zgodności. Ogólnie rzecz biorąc, w tym przypadku najbardziej widoczny jest dokładny adres. Zwracamy różnego rodzaju adresy – od najbardziej szczegółowych adresów po mniej szczegółowe podmioty polityczne, takie jak dzielnice, miasta, hrabstwa, stany itp. Jeśli chcesz dopasować bardziej ogólny adres, przejrzyj pole results[].types.

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

Uzyskiwanie adresu dla identyfikatora miejsca

Podaj placeId, aby znaleźć adres dla danego identyfikatora miejsca. 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 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

Poniższy przykład akceptuje identyfikator miejsca, znajduje odpowiedni adres i wyśrodkowuje mapę na tej lokalizacji. Wyświetli się też okno informacyjne ze sformatowanym adresem odpowiedniego miejsca:

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