Autouzupełnianie miejsc

Wstęp

Autouzupełnianie to funkcja biblioteki Miejsca w interfejsie Maps JavaScript API. Dzięki autouzupełnianiu Twoje aplikacje mogą wyszukiwać z wyprzedzeniem w polu wyszukiwania Map Google. Usługa autouzupełniania dopasowuje pełne słowa i podłańcuchy, rozpoznając nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w miarę wpisywania przez użytkowników, aby generować prognozy dotyczące miejsc na bieżąco.

Pierwsze kroki

Zanim użyjesz biblioteki Miejsc w interfejsie Maps JavaScript API, upewnij się, że interfejs Places API jest włączony w Google Cloud Console 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ź Places 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 interfejs Places API, a następnie wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu Places API pojawi się na liście interfejsów API w panelu.

Wczytuję bibliotekę

Usługa Miejsca jest samodzielną biblioteką, niezależną od głównego kodu interfejsu Maps JavaScript API. Aby korzystać z funkcji dostępnych w tej bibliotece, musisz ją najpierw wczytać za pomocą parametru libraries w adresie URL wczytywania interfejsu API Map Google:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Więcej informacji znajdziesz w artykule Omówienie bibliotek.

Podsumowanie zajęć

Interfejs API udostępnia 2 rodzaje widżetów autouzupełniania, które można dodawać odpowiednio za pomocą klas Autocomplete i SearchBox. Dodatkowo możesz używać klasy AutocompleteService do automatycznego pobierania wyników autouzupełniania (zobacz dokumentację interfejsu Maps JavaScript API: klasa AutocompleteService).

Poniżej znajdziesz podsumowanie dostępnych zajęć:

  • Autocomplete dodaje do strony internetowej pole tekstowe i monitoruje to pole pod kątem wpisów znaków. Gdy użytkownik wpisuje tekst, autouzupełnianie zwraca prognozy miejsc w postaci listy wyboru. Gdy użytkownik wybierze miejsce z listy, informacje o nim są zwracane do obiektu autouzupełniania i mogą być pobierane przez aplikację. Szczegółowe informacje znajdziesz poniżej.
    Pole tekstowe autouzupełniania oraz lista podpowiedzi dotyczących miejsc podana, gdy użytkownik wpisuje zapytanie.
    Rys. 1. Pole tekstowe autouzupełniania i lista wyboru
    Wypełniony formularz adresowy.
    Rys. 2. Wypełniony formularz z adresem
  • SearchBox dodaje do strony internetowej pole tekstowe podobne do Autocomplete. Różnice są następujące:
    • Główna różnica polega na wynikach wyświetlanych na liście wyboru. SearchBox dostarcza rozszerzoną listę prognoz, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wprowadzi hasło „pizza w nowym”, lista opcji może zawierać wyrażenie „pizza w Krakowie”, a także nazwy różnych pizzerii.
    • SearchBox oferuje mniej opcji ograniczania wyszukiwania niż Autocomplete. W pierwszym przypadku możesz ukierunkować wyszukiwanie na konkretną wartość LatLngBounds. W drugim przypadku możesz ograniczyć wyszukiwanie do określonych krajów i typów miejsc, a także określić granice. Więcej informacji znajdziesz poniżej.
    Wypełniony formularz adresowy.
    Rysunek 3. Pole SearchBox przedstawia wyszukiwane hasła i prognozy miejsc.
    Więcej informacji znajdziesz poniżej.
  • Aby automatycznie pobierać prognozy, możesz utworzyć obiekt AutocompleteService. Zadzwoń pod numer getPlacePredictions(), aby pobrać pasujące miejsca, lub getQueryPredictions(), aby pobrać pasujące miejsca i sugerowane wyszukiwane hasła. Uwaga: AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego powyższe metody zwracają tablicę obiektów prognoz. Każdy obiekt prognozy zawiera tekst prognozy, a także informacje referencyjne oraz szczegóły dotyczące tego, jak wynik pasuje do danych wejściowych użytkownika. Więcej informacji znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widżet Autocomplete tworzy pole do wprowadzania tekstu na stronie internetowej, dostarcza prognozy miejsc na liście wyboru w interfejsie i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każda pozycja na liście wyboru odpowiada pojedynczemu miejscu (zgodnie z definicją w interfejsie Places API).

Konstruktor Autocomplete przyjmuje 2 argumenty:

  • Element HTML input typu text. Jest to pole do wprowadzania danych, które będzie monitorować usługa autouzupełniania i dołącza do niego swoje wyniki.
  • Opcjonalny argument AutocompleteOptions, który może zawierać te właściwości:
    • Tablica danych fields, które mają być uwzględnione w odpowiedzi Place Details dla wybranego przez użytkownika elementu PlaceResult. Jeśli właściwość nie jest ustawiona lub jest przekazywana ['ALL'], wszystkie dostępne pola są zwracane i rozliczane (nie jest to zalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
    • Tablica types, która określa konkretny typ lub kolekcję typów wymienionych na liście obsługiwanych typów. Jeśli nie określisz typu, zwrócone zostaną wszystkie typy.
    • bounds to obiekt google.maps.LatLngBounds określający obszar wyszukiwania miejsc. Wyniki są stronnicze, ale nie ograniczają się do miejsc znajdujących się w tych granicach.
    • strictBounds to właściwość boolean określająca, czy interfejs API może zwracać tylko te miejsca, które znajdują się wyłącznie w regionie określonym przez podaną wartość bounds. Interfejs API nie zwraca wyników spoza tego regionu, nawet jeśli pasują one do danych wejściowych użytkownika.
    • componentRestrictions może służyć do ograniczania wyników do określonych grup. Obecnie za pomocą componentRestrictions możesz filtrować według maksymalnie 5 krajów. Kraje należy przekazywać w postaci dwuznakowego kodu kraju zgodnego z normą ISO 3166-1 alfa-2. W postaci listy kodów krajów należy przekazać wiele krajów.

      Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu zawierającego kraje, terytoria zależne i specjalne obszary geograficzne, które Cię interesują. Informacje o kodzie znajdziesz na stronie Wikipedii: lista kodów krajów w formacie ISO 3166 lub na platformie przeglądania online w ISO.

    • Za pomocą parametru placeIdOnly możesz nakazać widżetowi Autocomplete pobieranie tylko identyfikatorów miejsc. Po wywołaniu getPlace() w obiekcie Autocomplete udostępniony PlaceResult będzie miał ustawione tylko właściwości place id, types i name. Zwróconego identyfikatora miejsca możesz używać w połączeniach z usługami Miejsca, Geokodowanie, Wskazówki dojazdu lub Macierz odległości.

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc prezentuje wszystkie typy miejsc na podstawie prognoz dotyczących lokalizacji użytkownika oraz pobiera wszystkie dostępne pola danych dotyczące wybranego miejsca. Ustaw opcje autouzupełniania miejsc, aby wyświetlać trafniejsze podpowiedzi na podstawie Twojego przypadku użycia.

Ustaw opcje na etapie budowy

Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, aby ustawić ograniczenia podczas tworzenia widżetu. W poniższym przykładzie ustawione są opcje bounds, componentRestrictions i types, które żądają miejsc typu establishment, preferując te znajdujące się na określonym obszarze geograficznym i ograniczając prognozy tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje o wybranym miejscu przez użytkownika mają być zwracane.

Wywołaj setOptions(), aby zmienić wartość opcji dla istniejącego widżetu.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Określanie pól danych

Określ pola danych, by uniknąć opłat za kody SKU danych Miejsc, których nie potrzebujesz. Umieść w obiekcie AutocompleteOptions właściwość fields, która jest przekazywana do konstruktora widżetu, jak pokazano w poprzednim przykładzie, lub wywołaj setFields() w istniejącym obiekcie Autocomplete.

autocomplete.setFields(["place_id", "geometry", "name"]);

Zdefiniuj odchylenia i granice obszarów wyszukiwania na potrzeby autouzupełniania

Możesz odchylić wyniki autouzupełniania, aby preferować przybliżoną lokalizację lub obszar. Oto możliwe sposoby:

  • Wyznacz granice podczas tworzenia obiektu Autocomplete.
  • Zmień granice istniejącego obiektu Autocomplete.
  • Ustaw granice widocznego obszaru mapy.
  • Ogranicz wyszukiwanie do granic.
  • Ograniczyć wyszukiwanie do konkretnego kraju.

Poprzedni przykład przedstawia ustawianie granic podczas tworzenia konta. Poniższe przykłady ilustrują inne techniki promowania wyników.

Zmiana zakresu istniejącego autouzupełniania

Wywołaj setBounds(), aby zmienić obszar wyszukiwania w istniejącym elemencie Autocomplete na prostokątne granice.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Ustaw granice widocznego obszaru mapy

Użyj operatora bindTo(), aby odchylić wyniki zgodnie z widocznym obszarem mapy, nawet jeśli ten widoczny obszar się zmieni.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Użyj polecenia unbind(), by usunąć powiązanie podpowiedzi autouzupełniania z widocznym obszarem mapy.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

Zobacz przykład

Ogranicz wyszukiwanie do bieżącego zakresu

Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących granic niezależnie od widocznego obszaru mapy czy prostokątnych granic.

autocomplete.setOptions({ strictBounds: true });
Ograniczenie podpowiedzi do konkretnego kraju

Użyj opcji componentRestrictions lub wywołaj setComponentRestrictions(), aby ograniczyć wyszukiwanie autouzupełniania do określonego zestawu maksymalnie 5 krajów.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

Zobacz przykład

Ograniczenie typów miejsc

Użyj opcji types lub wywołaj setTypes(), aby ograniczyć prognozy do określonych typów miejsc. To ograniczenie określa typ lub kolekcję typów wymienionych w sekcji Typy miejsc. Jeśli nie podasz ograniczenia, zwracane będą wszystkie typy.

W przypadku wartości opcji types lub wartości przekazanej do setTypes() możesz określić:

  • Tablica zawierająca maksymalnie 5 wartości z tabeli 1 lub tabeli 2 typów miejsc. Na przykład:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    lub:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Każdy filtr w Tabeli 3 z Typy miejsc. Możesz podać tylko jedną wartość z tabeli 3.

Prośba zostanie odrzucona, jeśli:

  • Możesz określić więcej niż 5 typów.
  • Określasz nierozpoznane typy.
  • Mieszasz dowolne typy z tabeli 1 lub tabeli 2 z dowolnym filtrem z tabeli 3.

Prezentacja autouzupełniania miejsc pokazuje różnice w przewidywaniach różnych typów miejsc.

Zobacz prezentację

Jak uzyskać informacje o miejscu

Gdy użytkownik wybierze miejsce z podpowiedzi dołączonych do pola tekstowego autouzupełniania, usługa uruchomi zdarzenie place_changed. Aby uzyskać szczegółowe informacje o miejscu:

  1. Utwórz moduł obsługi zdarzeń place_changed i wywołaj addListener() w obiekcie Autocomplete, aby go dodać.
  2. Wywołaj Autocomplete.getPlace() w obiekcie Autocomplete, aby pobrać obiekt PlaceResult, którego możesz potem użyć, aby uzyskać więcej informacji o wybranym miejscu.

Domyślnie, gdy użytkownik wybierze miejsce, autouzupełnianie zwraca wszystkie dostępne pola danych dotyczące wybranego miejsca, a Twoje konto jest odpowiednio rozliczane. Aby określić, które pola danych miejsca mają zostać zwrócone, użyj funkcji Autocomplete.setFields(). Dowiedz się więcej o obiekcie PlaceResult, w tym o liście pól danych miejsc, o które możesz poprosić. Aby uniknąć płacenia za niepotrzebne dane, użyj funkcji Autocomplete.setFields() do określenia tylko tych danych o miejscach, których będziesz używać.

Właściwość name zawiera description z podpowiedzi autouzupełniania Miejsc. Więcej informacji o funkcji description znajdziesz w dokumentacji autouzupełniania Miejsc.

W przypadku formularzy adresowych przydatne jest uzyskanie adresu w formacie strukturalnym. Aby zwrócić uporządkowany adres dla wybranego miejsca, wywołaj Autocomplete.setFields() i określ pole address_components.

Poniższy przykład pokazuje użycie autouzupełniania do wypełniania pól w formularzu adresowym.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Zobacz przykład

Dostosowywanie tekstu zastępczego

Pole tekstowe utworzone przez usługę autouzupełniania domyślnie zawiera standardowy tekst zastępczy. Aby zmodyfikować tekst, ustaw atrybut placeholder w elemencie input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Uwaga: domyślny tekst zastępczy jest lokalizowany automatycznie. Jeśli określisz własną wartość zmiennej, musisz ją zlokalizować w swojej aplikacji. Informacje o tym, jak interfejs Google Maps JavaScript API wybiera język do użycia, znajdziesz w dokumentacji dotyczącej lokalizacji.

Aby dowiedzieć się, jak dostosować wygląd widżetów, zapoznaj się z artykułem Określanie stylu widżetów autouzupełniania i pól wyszukiwania.

SearchBox umożliwia użytkownikom przeprowadzanie wyszukiwania geograficznego, np. „pizza w Krakowie” lub „sklepy z obuwiem w pobliżu Mokotów”. Możesz dołączyć SearchBox do pola tekstowego, a po wpisaniu tekstu usługa będzie zwracać prognozy w postaci listy wyboru.

SearchBox udostępnia rozszerzoną listę podpowiedzi, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wprowadzi hasło „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie”, a także nazwy różnych pizzerii. Gdy użytkownik wybierze miejsce z listy, informacje o nim są zwracane do obiektu SearchBox i mogą być pobierane przez aplikację.

Konstruktor SearchBox przyjmuje 2 argumenty:

  • Element HTML input typu text. Jest to pole do wprowadzania danych, które będzie monitorować usługa SearchBox i do którego dołącza swoje wyniki.
  • Argument options, który może zawierać właściwość bounds: bounds to obiekt google.maps.LatLngBounds określający obszar, w którym wyszukiwane są miejsca. Wyniki są stronnicze, ale nie ograniczają się do miejsc znajdujących się w tych granicach.

W poniższym kodzie użyto parametru granic do odchylenia wyników pod kątem miejsc w konkretnym obszarze geograficznym, który jest określony za pomocą współrzędnych szerokości i długości geograficznej.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Zmiana obszaru wyszukiwania w polu wyszukiwania

Aby zmienić obszar wyszukiwania dla istniejącego obiektu SearchBox, wywołaj setBounds() w obiekcie SearchBox i przekaż odpowiedni obiekt LatLngBounds.

Zobacz przykład

Jak uzyskać informacje o miejscu

Gdy użytkownik wybierze element z prognoz załączonych do pola wyszukiwania, usługa wywoła zdarzenie places_changed. Możesz wywołać getPlaces() w obiekcie SearchBox, aby pobrać tablicę zawierającą kilka prognoz, z których każde jest obiektem PlaceResult.

Więcej informacji o obiekcie PlaceResult znajdziesz w dokumentacji dotyczącej wyników dotyczących szczegółów miejsca.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Zobacz przykład

Aby dowiedzieć się, jak dostosować wygląd widżetów, zapoznaj się z artykułem Określanie stylu widżetów autouzupełniania i pól wyszukiwania.

Automatyczne pobieranie prognoz usługi autouzupełniania

Aby pobierać prognozy programowo, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego zwraca tablicę obiektów prognoz, z których każdy zawiera tekst prognozy, informacje referencyjne oraz szczegóły dotyczące tego, jak wynik pasuje do danych wejściowych użytkownika. Jest to przydatne, gdy chcesz mieć większą kontrolę nad interfejsem w stosunku do opisanych powyżej metod Autocomplete i SearchBox.

AutocompleteService udostępnia te metody:

  • getPlacePredictions() zwraca przewidywane miejsca. Uwaga: „miejscem” może być instytucja, lokalizacja geograficzna lub ważne ciekawe miejsce określone w interfejsie Places API.
  • getQueryPredictions() zwraca rozszerzoną listę prognoz, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wprowadzi hasło „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie”, a także nazwy różnych pizzerii.

Obie te metody zwracają tablicę obiektów prognoz w tej postaci:

  • Pasująca prognoza: description.
  • distance_meters to odległość w metrach od miejsca od określonej lokalizacji AutocompletionRequest.origin.
  • matched_substrings zawiera w opisie zestaw podłańcuchów pasujących do elementów wpisanych przez użytkownika. Przydaje się to do wyróżniania tych podłańcuchów w aplikacji. W wielu przypadkach zapytanie pojawi się jako podłańcuch pola opisu.
    • length to długość podłańcucha.
    • offset to przesunięcie znaku mierzone od początku ciągu znaków opisu, w którym pojawia się pasujący podłańcuch.
  • place_id to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w polu placeId w żądaniu szczegółów miejsca. Dowiedz się więcej o tym, jak określić odwołanie do miejsca za pomocą identyfikatora miejsca.
  • terms to tablica zawierająca elementy zapytania. W przypadku miejsca każdy element stanowi zwykle część adresu.
    • offset to przesunięcie znaku mierzone od początku ciągu znaków opisu, w którym pojawia się pasujący podłańcuch.
    • value to pasujący termin.

Poniższy przykład wykonuje żądanie prognozy zapytania dla wyrażenia „pizza w pobliżu” i wyświetla wynik w postaci listy.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Wypróbuj fragment

Zobacz przykład

Tokeny sesji

AutocompleteService.getPlacePredictions() używa tokenów sesji do grupowania żądań autouzupełniania na potrzeby płatności. Tokeny sesji grupują fazy zapytania i selekcji użytkownika w ramach autouzupełniania wyszukiwania w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, i kończy, gdy wybiera miejsce. Każda sesja może obejmować wiele zapytań, a następnie wybrać jedno miejsce. Po zakończeniu sesji token traci ważność. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania. Jeśli pominiesz parametr sessionToken lub użyjesz ponownie tokena sesji, opłata za sesję zostanie naliczona tak, jakby nie został dostarczony żaden token sesji (każde żądanie jest rozliczane osobno).

Za pomocą tego samego tokena sesji możesz wysłać jedno żądanie Place Details (Szczegóły miejsca) w przypadku danego miejsca, które jest wynikiem wywołania metody AutocompleteService.getPlacePredictions(). W takim przypadku żądanie autouzupełniania jest połączone z prośbą o szczegóły miejsca, a połączenie jest płatne jak zwykłe żądanie informacji o miejscu. Automatyczne uzupełnianie żądania jest bezpłatne.

Pamiętaj, by w każdej nowej sesji przekazywać unikalny token. Użycie tego samego tokena w więcej niż jednej sesji autouzupełniania spowoduje, że te sesje autouzupełniania będą unieważnione, a wszystkie żądania autouzupełniania w nieprawidłowych sesjach będą rozliczane indywidualnie za pomocą kodu SKU autouzupełniania na żądanie. Więcej informacji o tokenach sesji

Poniższy przykład pokazuje, jak utworzyć token sesji, a następnie przekazać go w elemencie AutocompleteService (funkcja displaySuggestions() została pominięta ze względu na długość):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Pamiętaj, by w każdej nowej sesji przekazywać unikalny token. Używanie tego samego tokena w więcej niż 1 sesji sprawia, że każde żądanie jest rozliczane osobno.

Więcej informacji o tokenach sesji

Zmienianie stylu widżetów autouzupełniania i SearchBox

Domyślnie elementy interfejsu udostępniane przez Autocomplete i SearchBox są dostosowane do umieszczenia na mapie Google. Możesz dostosować styl do swojej witryny. Dostępne są poniższe klasy CSS. Wszystkie klasy wymienione poniżej dotyczą zarówno widżetów Autocomplete, jak i SearchBox.

Ilustracja przedstawiająca klasy CSS dla widżetów autouzupełniania i SearchBox
Klasy CSS dla widżetów autouzupełniania i SearchBox
Klasa CSS Opis
pac-container Element wizualny zawierający listę prognoz zwracanych przez usługę autouzupełniania miejsc. Ta lista ma postać menu pod widżetem Autocomplete lub SearchBox.
pac-icon Ikona wyświetlana po lewej stronie każdego elementu na liście prognoz.
pac-item Element na liście prognoz dostarczanych przez widżet Autocomplete lub SearchBox.
pac-item:hover Element, gdy użytkownik najedzie na niego kursorem myszy.
pac-item-selected Element wybrany po wybraniu przez użytkownika na klawiaturze. Uwaga: wybrane elementy będą należeć do tej klasy i klasy pac-item.
pac-item-query Rozpiętość wewnątrz elementu pac-item, który jest główną częścią prognozy. W przypadku lokalizacji geograficznych jest to nazwa miejsca, np. „Gdańsk”, lub nazwa ulicy i numer domu, np. „ul. 10 Kraków”. W przypadku wyszukiwań tekstowych, np. „pizza w Krakowie”, zawiera on pełny tekst zapytania. Domyślnie pac-item-query jest w kolorze czarnym. Jeśli pac-item zawiera dodatkowy tekst, znajduje się on poza domeną pac-item-query i dziedziczy jej styl z pac-item. Domyślnie jest on szary. Dodatkowy tekst to zwykle adres.
pac-matched Część zwróconej prognozy, która pasuje do danych wejściowych użytkownika. Domyślnie dopasowany tekst jest pogrubiony. Pamiętaj, że pasujący tekst może znajdować się w dowolnym miejscu w obrębie zakresu pac-item. Nie musi być częścią elementu pac-item-query. Może znajdować się częściowo w elemencie pac-item-query, a częściowo w pozostałym tekście w języku pac-item.

Optymalizacja autouzupełniania miejsc

W tej sekcji znajdziesz opis sprawdzonych metod, które pomogą Ci w pełni wykorzystać możliwości usługi autouzupełniania miejsc.

Oto kilka ogólnych wskazówek:

  • Najszybszym sposobem na opracowanie działającego interfejsu jest użycie widżetu autouzupełniania interfejsu Maps JavaScript API, widżetu autouzupełniania na Androidzie lub widżetu autouzupełniania w interfejsie Places SDK na iOS.
  • Opanuj od samego początku najważniejsze pola danych autouzupełniania miejsc.
  • Pola promowania lokalizacji i ograniczeń dotyczących lokalizacji są opcjonalne, ale mogą mieć znaczny wpływ na wydajność autouzupełniania.
  • Obsługuj błędy, aby zadbać o płynne działanie aplikacji, gdy interfejs API zwróci błąd.
  • Sprawdź, czy aplikacja obsługuje, gdy nie ma możliwości wyboru, i zapewni użytkownikom możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi autouzupełniania miejsc, użyj masek pól w szczegółach miejsca i widżetów autouzupełniania miejsc, aby zwracać tylko te pola danych miejsc, których potrzebujesz.

Zaawansowana optymalizacja kosztów

Rozważ automatyczną implementację autouzupełniania miejsca, aby mieć dostęp do cen według żądania i wysyłać żądania wyników interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca. Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej ekonomiczne niż ceny na sesję (ustalane na podstawie sesji), jeśli są spełnione oba te warunki:

  • Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego przez użytkownika, interfejs Geocoding API dostarcza te informacje do wartości krótszych niż wywołanie szczegółów miejsca.
  • Jeśli użytkownicy wybiorą prognozę autouzupełniania nie więcej niż cztery żądania, model cenowy na żądanie może być bardziej opłacalny niż model cenowy na sesję.
Aby uzyskać pomoc przy wyborze implementacji autouzupełniania miejsc, która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą Twojej odpowiedzi na poniższe pytanie.

Czy Twoja aplikacja wymaga podania innych informacji niż adres i szerokość/długość geograficzna wybranej prognozy?

Tak, potrzebuję więcej szczegółów

Korzystaj z autouzupełniania miejsc na podstawie sesji.
Aplikacja wymaga informacji o miejscu, takich jak nazwa miejsca, status firmy czy godziny otwarcia, więc implementacja autouzupełniania miejsca powinna korzystać z tokena sesji (programowo lub wbudowanych w widżety JavaScript, Androida lub iOS). Łączny koszt wynosi 0, 017 USD za sesję plus odpowiednie Kody SKU danych miejsc w zależności od żądanego pola danych o miejscu.

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Androida i iOS. Dotyczy to zarówno żądań autouzupełniania miejsc, jak i żądań szczegółów miejsca w przypadku wybranej podpowiedzi. Określ parametr fields, aby mieć pewność, że wysyłasz tylko żądania pól danych miejsc, których potrzebujesz.

Implementacja automatyczna
W żądaniach autouzupełniania miejsc używaj tokena sesji. Wysyłając żądanie Szczegóły miejsca dotyczące wybranej prognozy, podaj te parametry:

  1. identyfikator miejsca z odpowiedzi autouzupełniania miejsca,
  2. Token sesji używany w żądaniu autouzupełniania miejsca.
  3. Parametr fields określający potrzebne pola danych miejsc

Nie, potrzebuje tylko adresu i lokalizacji

Interfejs Geocoding API może być bardziej opłacalny niż „Place Details” (Szczegóły miejsca) w przypadku danej aplikacji, w zależności od wydajności funkcji autouzupełniania. Skuteczność autouzupełniania aplikacji różni się w zależności od tego, co wpisują użytkownicy, gdzie jest ona używana i od tego, czy zostały wdrożone sprawdzone metody optymalizacji skuteczności.

Aby odpowiedzieć na to pytanie, sprawdź, ile znaków średnio wpisuje użytkownik, zanim wybierzesz podpowiedź autouzupełniania w swojej aplikacji.

Czy Twoi użytkownicy korzystają średnio z podpowiedzi autouzupełniania miejsc w maksymalnie 4 żądaniach?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku prognozowania wybranego miejsca.
Geocoding API dostarcza adresów oraz współrzędnych szerokości i długości geograficznej za 0,005 USD za żądanie. Realizacja 4 żądań autouzupełniania miejsc na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołanie Geocoding API dla prognozy wybranego miejsca wynosi 0,01632 USD, czyli mniej niż cena autouzupełniania za sesję, która wynosi 0,017 USD za sesję1.

Rozważ stosowanie sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskiwać interesujące ich prognozy, używając jeszcze mniejszej liczby znaków.

Nie

Korzystaj z autouzupełniania miejsc na podstawie sesji.
Ponieważ średnia liczba żądań, które spodziewasz się wysłać przed wybraniem prognozy autouzupełniania miejsca przez użytkownika, przekracza koszt za sesję, Twoja implementacja autouzupełniania miejsc powinna korzystać z tokena sesji zarówno w przypadku żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań szczegółów miejsca.Łączny koszt wynosi 0,017 USD za sesję1.

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Androida i iOS. Dotyczy to zarówno żądań autouzupełniania miejsc, jak i żądań szczegółów miejsca w przypadku wybranej podpowiedzi. Określ parametr fields, aby mieć pewność, że żądasz tylko pól Dane podstawowe.

Implementacja automatyczna
W żądaniach autouzupełniania miejsc używaj tokena sesji. Wysyłając żądanie Szczegóły miejsca dotyczące wybranej prognozy, podaj te parametry:

  1. identyfikator miejsca z odpowiedzi autouzupełniania miejsca,
  2. Token sesji używany w żądaniu autouzupełniania miejsca.
  3. Parametr fields określający pola Dane podstawowe, takie jak adres i geometria

Rozważ opóźnienie żądań autouzupełniania miejsc
Możesz użyć strategii, takich jak opóźnianie żądania autouzupełniania miejsca do momentu, w którym użytkownik wpisał pierwsze 3 lub 4 znaki. Dzięki temu aplikacja będzie wysyłać mniej żądań. Na przykład wysyłanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku przez użytkownika oznacza, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze podpowiedź, dla której tworzysz jedno żądanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 * 0,00283 USD autouzupełniania na żądanie + 0,005 USD za geokodowanie)1.

Jeśli opóźnione żądania mogą spowodować, że średnie żądania zautomatyzowanych żądań znikają poniżej 4, zapoznaj się ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania miejsc za pomocą interfejsu Geocoding API. Pamiętaj, że opóźnione żądania mogą być postrzegane jako czas oczekiwania dla użytkownika, który może oczekiwać, że prognozy będą pojawiać się po każdym nowym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskiwać interesujące ich informacje przy użyciu mniejszej liczby znaków.


  1. Wymienione tutaj koszty są podane w dolarach amerykańskich. Pełne informacje o cenach znajdziesz na stronie Rozliczenia za Google Maps Platform.

Sprawdzone metody zwiększania skuteczności

Poniższe wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj do implementacji autouzupełniania miejsc ograniczenia związane z krajem, promowaniem lokalizacji i ustawienia języka (w przypadku implementacji zautomatyzowanych). Widżety nie wymagają wyboru języka, ponieważ są one wybierane w przeglądarce lub na urządzeniu mobilnym użytkownika.
  • Jeśli autouzupełnianie miejsc towarzyszy mapie, możesz odchylać lokalizację według widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze jednego z podpowiedzi autouzupełniania, zwykle dlatego, że żadne z nich nie jest pożądanym adresem wyniku, możesz ponownie wykorzystać pierwotne dane wejściowe, aby uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik będzie podawać tylko informacje adresowe, użyj tych samych danych w wywołaniu Geocoding API.
    • Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytanie o konkretne miejsce, podając jego nazwę lub adres, skorzystaj z funkcji Znajdź prośbę o miejsce. Jeśli wyniki są oczekiwane tylko w konkretnym regionie, użyj promowania lokalizacji.
    Inne scenariusze, w których warto wrócić do interfejsu Geocoding API, to między innymi:
    • Użytkownicy podający adresy podrzędne w krajach, w których autouzupełnianie miejsc nie obsługuje adresów podrzędnych, np. w Czechach, Estonii i Litwie. Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściowe podpowiedzi w funkcji autouzupełniania miejsc.
    • Użytkownicy wpisują adresy z prefiksem segmentu drogi, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawai.

Limity i zasady dotyczące wykorzystania

Limity

Informacje o limitach i cenach znajdziesz w dokumentacji dotyczącej użytkowania i rozliczeń dotyczącej interfejsu Places API.

Zasady

Korzystanie z biblioteki Miejsc Google Maps JavaScript API musi być zgodne z zasadami dotyczącymi interfejsu Places API.