Usługa geokodowania

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Omówienie

Geokodowanie to proces konwersji 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żesz użyć do umieszczenia znaczników lub pozycji na mapie.

Odwrotne geokodowanie to proces konwertowania współrzędnych geograficznych na adresy czytelne dla użytkowników (patrz odwrotne geokodowanie (wyszukiwanie adresu)).

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

Interfejs Maps JavaScript API zapewnia klasy Geocoder na potrzeby geokodowania i odwrotnego geokodowania na podstawie danych użytkownika. Jeśli chcesz skorzystać z kodowania statycznego, znanych adresów, zajrzyj do usługi geokodowania.

Pierwsze kroki

Zanim użyjesz usługi geokodowania w interfejsie Maps JavaScript API, musisz się upewnić, że ten interfejs API jest włączony w Google Cloud Console w tym samym projekcie, który został skonfigurowany pod kątem interfejsu 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 dla interfejsu API JavaScript Map Google, a następnie kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Geocoding API.
  4. Jeśli na liście znajduje się interfejs API, nie musisz nic więcej robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. U góry strony wybierz ENABLE API, aby wyświetlić kartę Biblioteka. Możesz też wybrać w menu po lewej stronie Bibliotekę.
    2. Wyszukaj Interfejs API kodowania, a następnie wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Gdy proces się zakończy, interfejs Geocoding API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

cenę,

Od 16 lipca 2018 roku w Mapach, trasach i miejscach jest stosowany nowy, płatny abonament. Aby dowiedzieć się więcej o nowych cenach i limitach wykorzystania związanych z korzystaniem z usługi geokodowania JavaScript, przeczytaj artykuł Użycie i płatności tego interfejsu.

Zasady

Używanie usługi geokodowania musi być zgodne z zasadami opisanymi w interfejsie Geocoding API.

Żądania geokodowania

Dostęp do usługi geokodowania jest asynchroniczny, ponieważ interfejs API Map Google wymaga wywoływania serwera zewnętrznego. Z tego powodu 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ż 1 wynik.

Usługa geokodowania interfejsu API Map Google jest dostępna w kodzie za pomocą obiektu konstruktora google.maps.Geocoder. Metoda Geocoder.geocode() inicjuje żądanie do usługi geokodowania, przekazując do niego literał obiektu GeocoderRequest zawierający warunki wejściowe i metodę wywołania zwrotnego, która ma być wykonana 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ć tylko jedno z tych pól:

  • address – adres, który chcesz uwzględnić w danych geograficznych;
    lub
    locationLatLng (lub LatLngLiteral), dla których chcesz uzyskać najbliższy, czytelny dla człowieka adres. Geokoder przeprowadza odwrotne geokodowanie. Więcej informacji znajdziesz w sekcji Odwrotne geokodowanie.
    lub
    placeId – identyfikator miejsca, z którego chcesz uzyskać najbliższy, czytelny dla człowieka adres. Dowiedz się więcej o pobieraniu adresu za pomocą identyfikatora miejsca.

Parametry opcjonalne:

  • boundsLatLngBounds, w którym odchylenie wyników geograficznych jest bardziej widoczne. Parametr bounds ma wpływ tylko na wyniki z kodera, a nie bez ograniczeń. Więcej informacji o promowaniu widocznego obszaru znajdziesz poniżej.
  • 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 podany jako dwuznakowy (nieliczbowy) subtag regionu Unicode. W większości przypadków tagi są mapowane bezpośrednio na dobrze znane 2-znakowe wartości ccTLD („domena najwyższego poziomu”). Parametr region ma wpływ tylko na wyniki z kodera, a nie bez ograniczeń. Więcej informacji o promowaniu kodu regionu znajdziesz poniżej.

Odpowiedzi geokodowania

Usługa geokodowania wymaga wykonania metody wywołania zwrotnego po pobraniu wyników geokodera. To wywołanie zwrotne powinno przekazywać 2 parametry zawierające kod results i status w takiej kolejności.

Wyniki geokodowania

Obiekt GeocoderResult reprezentuje jeden wynik geokodowania. Żądanie geokodowania może zwracać 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
 }
}

Te pola zostały omówione poniżej:

  • types[] to tablica wskazująca typ adresu zwróconego wyniku. Ta tablica zawiera zestaw zero lub więcej tagów identyfikujących typ cechy zwróconego w wyniku. Na przykład kod geograficzny „Chicago” zwróci wartość „locality”, która wskazuje, że „Chicago” jest miastem, a także „polityczne”, która wskazuje, że jest to podmiot polityczny. Więcej informacji o typach adresów i typach komponentów znajdziesz poniżej.
  • formatted_address to ciąg znaków zawierający adres lokalizacji, który jest zrozumiały dla człowieka.

    Często jest to odpowiednik 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ę z co najmniej 1 komponentu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).

    Nie przetwarzaj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które oprócz odpowiedzi na sformatowane pole adresu zawierają odpowiedź interfejsu API.

  • address_components[] to tablica zawierająca osobne komponenty stosowane do tego adresu.

    Każdy komponent adresu zawiera zazwyczaj następujące pola:

    • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
    • long_name to pełny opis lub nazwa komponentu adresu zwracana przez geokoder.
    • short_name to skrócona nazwa tekstowa komponentu adresu (jeśli jest dostępny). Na przykład komponent adresu dla stanu Alaska może mieć atrybuty long_name takie jak „Alaska” i short_name „A” przy użyciu dwuliterowego skrótu pocztowego.

    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 obejmować wszystkich jednostek politycznych zawierających adres, poza tymi wymienionymi w zasadzie formatted_address. Aby pobrać wszystkie jednostki polityczne zawierające określony adres, użyj odwrotnego geokodowania, podając w żądaniu parametr szerokość i długość geograficzną adresu.
    • Format odpowiedzi między różnymi żądaniami nie musi być taki sam. W szczególności liczba obiektów address_components różni się w zależności od żądanego adresu i może się zmieniać w czasie dla tego samego adresu. Komponent może zmieniać położenie tablicy. Typ komponentu może się zmienić. W odpowiedzi może brakować określonego komponentu.

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

  • partial_match wskazuje, że geokoder nie zwrócił ściśle dopasowania do pierwotnego żądania, chociaż udało się dopasować część żądanego adresu. Możesz sprawdzić pierwotne żądanie dotyczące literówek lub niepełny adres.

    Częściowo pasujące adresy występują najczęściej w przypadku adresów, które nie istnieją w lokalizacji podanej w żądaniu. Częściowe dopasowania mogą zostać zwrócone także wtedy, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym miejscu. Na przykład „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie adresów na ulicy Helena i ul. Kochanowskiego. Jeśli żądanie zawiera nieprawidłowy komponent adresu, usługa geokodowania może zasugerować alternatywny adres. Sugestie uruchamiane w ten sposób również będą oznaczane jako częściowe dopasowanie.

  • place_id to unikalny identyfikator miejsca, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć place_id z biblioteką Google Places API, aby uzyskać informacje o lokalnej firmie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zobacz omówienie identyfikatora miejsca.
  • postcode_localities[] to tablica reprezentująca wszystkie miejscowości zawarte w kodzie pocztowym i występuje tylko wtedy, gdy wynikiem jest kod pocztowy z wieloma rejonami.
  • geometry zawiera te informacje:

    • location zawiera geograficzną wartość szerokości i długości geograficznej. Zwracamy tę lokalizację jako obiekt LatLng, a nie w postaci ciągu znaków.
    • location_type przechowuje dodatkowe dane o określonej lokalizacji. Obecnie obsługiwane są te wartości:
      • ROOFTOP wskazuje, że zwrócony wynik odzwierciedla dokładny kod geograficzny.
      • RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżone dane (zwykle na drodze) między 2 dokładnymi punktami (np. skrzyżowaniami). Interpolowane wyniki są zwykle zwracane, gdy geokodowanie na dachu jest niedostępne dla adresu pocztowego.
      • GEOMETRIC_CENTER wskazuje, że zwrócony wynik to geometryczny środek wyniku, taki jak linia łamana (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) zwraca LatLngBounds, który może w pełni zawierać zwrócony wynik. Te limity mogą nie być zalecane w widocznym obszarze. (Na przykład San Francisco obejmuje Wyspy Fallonów, które technicznie są częścią miasta, ale nie powinny być zwracane w widocznym obszarze).

Adresy będą zwracane przez geokoder wykorzystujący preferowany język przeglądarki lub język określony podczas wczytywania kodu JavaScript interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w sekcji Lokalizacja).

Typy i komponenty adresów

Tablica types[] w GeocoderResult wskazuje typ adresu. Tablica types[] może być także zwracana w elemencie GeocoderAddressComponent, by wskazać typ konkretnego komponentu z adresem. Adresy zwracane przez geokoder mogą mieć wiele typów; typy mogą być traktowane jak tagi. Na przykład wiele miast jest oznaczonych tagami typu political i locality.

Te typy są obsługiwane i zwracane przez geokoder zarówno w typach adresów, jak i komponentów adresów:

  • street_address wskazuje dokładny adres.
  • route wskazuje trasę nazwaną (np. „PL 101”).
  • intersection wskazuje duże skrzyżowanie, zwykle z dwiema głównymi drogami.
  • political oznacza podmiot polityczny. Zwykle ten typ wskazuje wielokąt wybranej administracji cywilnej.
  • country wskazuje krajowy podmiot polityczny i zwykle jest to najwyższy typ zamówienia zwracany przez Geocoder.
  • administrative_area_level_1 wskazuje podmiot cywilny pierwszego stopnia poniżej poziomu kraju. W Stanach Zjednoczonych poziomy te są stanami. Nie wszystkie kraje przedstawiają te poziomy administracyjne. W większości przypadków krótkie nazwy administracyjne_area_level_1 będą bardzo zbliżone do podgrup z normą ISO 3166-2 i innych popularnych list, ale nie jest to gwarantowane, ponieważ wyniki geokodowania opierają się na różnych sygnałach i danych o lokalizacji.
  • administrative_area_level_2 wskazuje podmiot cywilny drugiego poziomu poniżej poziomu kraju. Na terenie Stanów Zjednoczonych te poziomy administracyjne obejmują hrabstwa. Nie wszystkie kraje przedstawiają te poziomy administracyjne.
  • administrative_area_level_3 wskazuje podmiot cywilny spoza organizacji na poziomie kraju. Ten typ oznacza niewielką cywilizację. Nie wszystkie kraje przedstawiają te poziomy administracyjne.
  • administrative_area_level_4 wskazuje podmiot cywilny czwartego rzędu poniżej poziomu krajowego. Ten typ oznacza niewielką cywilizację. Nie wszystkie kraje przedstawiają te poziomy administracyjne.
  • administrative_area_level_5 wskazuje jednostkę cywilną piątej kolejności poniżej kraju. Ten typ oznacza niewielką cywilizację. Nie wszystkie kraje przedstawiają te poziomy administracyjne.
  • administrative_area_level_6 wskazuje podmiot cywilny szóstego stopnia na poziomie kraju. Ten typ oznacza niewielką cywilizację. Nie wszystkie kraje przedstawiają te poziomy administracyjne.
  • administrative_area_level_7 wskazuje podmiot cywilny siódmego stopnia poniżej poziomu kraju. Ten typ oznacza niewielką cywilizację. Nie wszystkie kraje przedstawiają te poziomy administracyjne.
  • colloquial_area wskazuje powszechnie używaną alternatywną nazwę elementu.
  • locality wskazuje włączone miasto lub inny podmiot polityczny.
  • sublocality oznacza podmiot cywilny pierwszego rzędu poniżej miejscowości. W przypadku niektórych lokalizacji może wystąpić jeden z dodatkowych typów: od sublocality_level_1 do sublocality_level_5. Każdy podrejon jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
  • neighborhood wskazuje nazwane dzielnice.
  • premise wskazuje nazwane miejsce, zwykle budynek lub kolekcję budynków o takiej samej nazwie
  • subpremise wskazuje encję pierwszego stopnia poniżej nazwanej lokalizacji. Zazwyczaj jest to jeden budynek w kolekcji budynków o tej samej nazwie.
  • plus_code wskazuje zakodowane odwołanie do lokalizacji na podstawie szerokości i długości geograficznej. Kody Plus Code mogą być używane zamiast adresów w miejscach, w których nie istnieją (gdy budynki nie mają numerów lub nie mają nazw). Więcej informacji znajdziesz na https://plus.codes.
  • postal_code to kod pocztowy używany do adresowania poczty w danym kraju.
  • natural_feature wskazuje naturalną cechę witryny.
  • airport oznacza lotnisko.
  • park wskazuje nazwany park.
  • point_of_interest wskazuje na najciekawsze miejsce. Są to zwykle najważniejsze obiekty lokalne, które nie pasują łatwo do innej kategorii, takie jak „Empire State Building” czy „Eiffel Tower”.

Pusta lista typów oznacza, że nie ma znanych typów określonych komponentów adresu, np. Lieu-dit we Francji.

Oprócz powyższych składników komponenty z adresem mogą też zawierać podane niżej typy adresów.

Uwaga: ta lista nie jest pełna i może się zmieniać.

  • floor to piętro w budynku.
  • establishment zwykle wskazuje miejsce, które nie ma jeszcze kategorii.
  • landmark wskazuje miejsce w pobliżu, które jest używane jako punkt odniesienia, aby ułatwić nawigację.
  • point_of_interest wskazuje na najciekawsze miejsce.
  • parking wskazuje parking lub strukturę parkingu.
  • post_box wskazuje konkretną skrytkę pocztową.
  • postal_town oznacza grupę obszarów geograficznych, takich jak locality i sublocality, używana w przypadku adresów pocztowych w niektórych krajach.
  • room oznacza salę z adresem budynku.
  • street_number wskazuje dokładny numer domu.
  • bus_station, train_station i transit_station wskazują miejsce przystanku autobusowego, pociągu lub 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ł przeanalizowany, a przynajmniej jeden został zwrócony.
  • "ZERO_RESULTS" oznacza, że przetwarzanie danych geograficznych zakończyło się powodzeniem, ale nie zwrócono żadnych wyników. Może się tak zdarzyć, jeśli koder został przekazany do nieistniejącego address.
  • "OVER_QUERY_LIMIT" oznacza, że został przekroczony limit.
  • "REQUEST_DENIED" oznacza, że Twoja prośba została odrzucona. Strona internetowa nie może używać geokodera.
  • "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, prośba może zostać zrealizowana.
  • "ERROR" oznacza, że upłynął limit czasu żądania lub wystąpił problem z połączeniem z serwerami Google. Jeśli spróbujesz ponownie, prośba może zostać zrealizowana.

W tym przykładzie przetwarzamy dane geograficzne na podstawie adresu i umieszczamy znacznik w zwróconych wartościach szerokości i długości geograficznej. Pamiętaj, że moduł obsługi jest przekazywany jako anonimowy literał funkcji.

  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 polecić usłudze geokodowania, aby preferowała wyniki z danego widocznego obszaru (wyrażonego jako ramka ograniczająca). W tym celu musisz ustawić parametr bounds w dosłowie obiektu GeocoderRequest, aby określić granice tego widocznego obszaru. Pamiętaj, że promowanie wyników tylko preferuje wyniki znajdujące się w tych granicach. Jeśli wyniki znajdują się poza tymi granicami, mogą one być uwzględnione.

Na przykład geografia „Winnetka” zwykle zwraca takie 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"
}

Jeśli jednak określisz parametr bounds definiujący ramkę ograniczającą dla doliny San Fernando w Los Angeles, w wyniku tego geokodu powstanie okolica 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 kodów regionów

Za pomocą parametru region możesz ustawić zwracanie przez usługę geokodowania wyników stronniczych w konkretnym regionie. Ten parametr pobiera kod regionu określony za pomocą dwuznakowego (nieliczbowego) subtagu regionu Unicode. Te tagi mapują bezpośrednio na dobrze znane wartości ccTLD („domena najwyższego poziomu”) 2-znakowe, 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” dla Wielkiej Brytanii).

Gdy używasz parametru region:

  • Podaj tylko jeden kraj lub region. Kilka wartości jest ignorowanych, co może spowodować niepowodzenie żądania.
  • Używaj tylko subtagów regionu (2 znaki) (format Unicode CLDR). Pozostałe 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 wyników preferuje tylko wyniki dotyczące określonej domeny. Jeśli wyniki spoza tej domeny są trafniejsze, można je uwzględnić.

Na przykład kod geograficzny „Toledo” zwraca ten wynik, ponieważ domyślna domena usługi geokodowania to 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"
}

Kod geograficzny „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ę geokodowania tak, by zwracała wyniki adresu ograniczone do określonego obszaru. Określ filtr w parametrze componentRestrictions. Wartości filtrów obsługują te same metody poprawiania pisowni i częściowego dopasowywania co inne żądania geokodowania.

Geokoder zwraca tylko wyniki pasujące do wszystkich filtrów komponentów. Oznacza to, że ocenia parametry filtra jako I, a nie LUB.

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

  • route pasuje do długiej lub krótkiej nazwy trasy.
  • locality odpowiada typom podlokalnym i podrzędnym.
  • administrativeArea pasuje do wszystkich poziomów obszaru administracyjnego.
  • postalCode pasuje do kodów pocztowych i prefiksów kodów pocztowych.
  • country pasuje do nazwy kraju lub dwuliterowego kodu kraju zgodnego ze standardem ISO 3166-1. Uwaga: interfejs API jest zgodny ze standardem ISO określającym kraje, 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 oznacza zwykle tłumaczenie adresu czytelnego dla człowieka na lokalizację na mapie. Proces odwrotnego tłumaczenia lokalizacji na mapie na adres czytelny dla użytkowników jest nazywany odwrotnym geokodowaniem.

Zamiast podawania tekstu address podaj w parametrze location parę szerokości i długości geograficznej rozdzielone przecinkami.

Ten przykład to kodowanie szerokości i długości geograficznej, które powoduje wyśrodkowanie mapy w danym miejscu, co spowoduje 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;

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;
Zobacz przykład

Fragment

W poprzednim przykładzie po raz pierwszy wyświetliliśmy pierwszy wynik, wybierając results[0]. Odwrotne kodowanie geograficzne często zwraca więcej niż 1 wynik. Adresy geokodowane to nie tylko adresy pocztowe, ale każdy sposób na geograficzną nazwę lokalizacji. Na przykład podczas geokodowania punktów w Chicago punkt geograficzny może być oznaczony jako ulica z nazwą ulicy (Chicago), stanem (Illinois) lub krajem (Stany Zjednoczone). Wszystkie są adresami geokodera. Odwrócony geokoder zwraca wszystkie te wyniki.

Odwrotne kodowanie geograficzne pasuje do jednostek politycznych (krajów, prowincji, miast i dzielnic), adresów i kodów pocztowych.

Oto przykład listy adresów, które może zwrócić jedno z powyższych zapytań:

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 najwyższej do najniższej. Najbardziej dokładny adres to zazwyczaj najlepszy wynik, jaki jest w tym przypadku. Zwracamy różne typy adresów – od najbardziej szczegółowego adresu po mniej konkretne podmioty polityczne, takie jak dzielnice, miasta, hrabstwa, stany itp. Jeśli chcesz dopasować bardziej ogólny adres, możesz sprawdzić pole results[].types.

Uwaga: odwrotne geokodowanie nie jest precyzyjne. Geokoder próbuje znaleźć najbliższą adresowaną lokalizację z określoną tolerancją.

Pobieranie adresu dla identyfikatora miejsca

W polu placeId znajdziesz adres miejsca o określonym identyfikatorze. Identyfikator miejsca to unikalny identyfikator, którego można używać z innymi interfejsami API Google. Możesz na przykład podać wartość placeId zwracaną przez interfejs Roads API, aby uzyskać adres przyciągania. 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, wyszukuje odpowiedni adres i wyśrodkowuje mapę w tej lokalizacji. Wyświetlane jest też okno informacyjne z sformatowanym adresem danego 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;

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;
Zobacz przykład

Fragment