Autouzupełnianie miejsc

Na tej stronie opisujemy bibliotekę po stronie klienta dostępną w Maps JavaScript API. Jeśli chcesz korzystać z usługi internetowej Places API na serwerze, zapoznaj się z klientem Node.js do usług Map Google. Na stronie pod tym linkiem znajdziesz też informacje o klientach Google Maps Services w językach Java, Python i Go.

Wprowadzenie

Autouzupełnianie to funkcja biblioteki Miejsc w interfejsie Maps JavaScript API. Możesz użyć autouzupełniania, aby nadać aplikacjom funkcję wyszukiwania z wyprzedzeniem, która jest dostępna w polu wyszukiwania Map Google. Usługa autouzupełniania może dopasowywać całe słowa i podciągi, rozwiązując nazwy miejsc, adresy i kody Plus Code. Aplikacje mogą więc wysyłać zapytania w trakcie wpisywania przez użytkownika, aby na bieżąco podawać prognozy dotyczące miejsc. Zgodnie z definicją interfejsu Places API „miejsce” może być obiektem, lokalizacją geograficzną lub ważnym punktem orientacyjnym.

Pierwsze kroki

Zanim zaczniesz używać biblioteki Places w interfejsie Maps JavaScript API, sprawdź, czy interfejs Places API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany dla interfejsu Maps JavaScript API.

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

1. Otwórz konsolę Google Cloud.
2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt, który został 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 więcej robić. Ten projekt ma jednak stan starszy. Więcej informacji o etapie starszych usług i o tym, jak przejść ze starszych usług na nowsze, znajdziesz w artykule Starsze produkty i funkcje. Wyjątkiem są widżety Autouzupełnianie i SearchBox, które nie są jeszcze dostępne jako usługa GA w interfejsie Places API (nowym).

Wczytywanie biblioteki

Usługa Miejsca to samodzielna biblioteka, oddzielona od głównego kodu interfejsu Maps JavaScript API. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw wczytać ją za pomocą parametru libraries w adresie URL bootstrap interfejsu Maps API:

<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  omówieniu bibliotek.

Podsumowanie zajęć

Interfejs API oferuje 2 typy widżetów autouzupełniania, które możesz dodać za pomocą klas Autocomplete i SearchBox. Oprócz tego możesz użyć klasy AutocompleteService, aby programowo pobierać wyniki autouzupełniania (patrz dokumentacja Maps JavaScript API: klasa AutocompleteService).

Poniżej znajdziesz podsumowanie dostępnych klas:

• Autocomplete dodaje do strony internetowej pole do wpisywania tekstu i monitoruje je pod kątem wpisywanych znaków. Gdy użytkownik wpisuje tekst, autouzupełnianie zwraca prognozy miejsc w postaci listy rozwijanej. Gdy użytkownik wybierze miejsce z listy, informacje o nim zostaną zwrócone do obiektu autouzupełniania i będą mogły zostać pobrane przez aplikację. Szczegóły znajdziesz poniżej.

  

  

• SearchBox dodaje do strony internetowej pole wpisywania tekstu w podobny sposób jak element 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 na przykład użytkownik wpisze „pizza w nowym”, lista wyboru może zawierać frazę „pizza w Nowym Jorku” oraz nazwy różnych pizzerii.
  • SearchBox oferuje mniej opcji niż Autocomplete, jeśli chodzi o ograniczanie wyszukiwania. W pierwszym przypadku możesz ukierunkować wyszukiwanie na określony LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do konkretnego kraju i rodzaju miejsca, a także ustawić granice. Więcej informacji znajdziesz poniżej.

  

  Szczegółowe informacje znajdziesz poniżej.
• Możesz utworzyć obiekt AutocompleteService, aby programowo pobierać prognozy. Wywołaj getPlacePredictions(), aby pobrać pasujące miejsca, lub wywołaj getQueryPredictions(), aby pobrać pasujące miejsca i sugerowane wyszukiwane hasła. Uwaga: AutocompleteService nie dodaje żadnych elementów interfejsu. Zamiast tego powyższe metody zwracają tablicę obiektów prognozowania. Każdy obiekt prognozy zawiera tekst prognozy, a także informacje referencyjne i szczegóły dotyczące tego, jak wynik pasuje do danych wejściowych użytkownika. Szczegółowe informacje znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widżet Autocomplete tworzy na stronie internetowej pole wprowadzania tekstu, wyświetla prognozy miejsc na liście wyboru interfejsu i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każdy wpis na liście wyboru odpowiada jednemu miejscu (zgodnie z definicją w interfejsie Places API).

Konstruktor Autocomplete przyjmuje 2 argumenty:

• Element HTML input typu text. Jest to pole wejściowe, które będzie monitorowane przez usługę automatycznego uzupełniania, a wyniki będą do niego dołączane.
• 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 na wybrane przez użytkownika PlaceResult. Jeśli właściwość nie jest ustawiona lub przekazano wartość ['ALL'], zwracane są wszystkie dostępne pola i naliczane są opłaty (nie jest to zalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w PlaceResult.
  • Tablica types, która określa typ lub kolekcję typów, jak podano w obsługiwanych typach. Jeśli nie podasz typu, zwracane będą wszystkie typy.
  • bounds to obiekt google.maps.LatLngBounds określający obszar, w którym mają być wyszukiwane miejsca. Wyniki są ukierunkowane na miejsca znajdujące się w tych granicach, ale nie są do nich ograniczone.
  • strictBounds to boolean określający, czy interfejs API ma zwracać tylko te miejsca, które znajdują się ściśle w regionie zdefiniowanym przez podany parametr bounds. API nie zwraca wyników spoza tego regionu, nawet jeśli pasują one do danych wejściowych użytkownika.
  • componentRestrictions można używać do ograniczania wyników do konkretnych grup. Możesz użyć componentRestrictions, aby filtrować dane z maksymalnie 5 krajów. Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 Alpha-2. Wiele krajów musi być przekazywanych jako lista kodów krajów.

    Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i obszary specjalne o znaczeniu geograficznym, które Cię interesują. Informacje o kodach znajdziesz na Wikipedii: Lista kodów krajów ISO 3166 lub na platformie ISO Online Browsing.

  • Parametr placeIdOnly może służyć do instruowania widżetu Autocomplete, aby pobierał tylko identyfikatory miejsc. Po wywołaniu funkcji calling getPlace() na obiekcie Autocomplete udostępniony obiekt PlaceResult będzie miał ustawione tylko właściwości place id, types i name. Zwrócony identyfikator miejsca możesz wykorzystać w wywołaniach usług Places, Geocoding, Directions lub Distance Matrix.

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc wyświetla wszystkie typy miejsc, z tendencją do prognoz w pobliżu lokalizacji użytkownika, i pobiera wszystkie dostępne pola danych dla wybranego przez użytkownika miejsca. Ustaw opcje autouzupełniania miejsca, aby wyświetlać trafniejsze prognozy na podstawie Twojego przypadku użycia.

Ustawianie opcji podczas tworzenia

Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, który umożliwia ustawienie ograniczeń podczas tworzenia widżetu. W tym przykładzie ustawiono opcje bounds, componentRestrictions i types, aby wysyłać żądania dotyczące miejsc typu establishment, preferując te, które znajdują się w określonym obszarze geograficznym, i ograniczając prognozy tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje mają być zwracane o wybranym przez użytkownika miejscu.

Zadzwoń pod numer setOptions(), aby zmienić wartość opcji w przypadku istniejącego widżetu.

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);
index.ts

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);
index.js

Określanie pól danych

Określ pola danych, aby uniknąć opłat za jednostki SKU danych o miejscach, których nie potrzebujesz. Uwzględnij właściwość fields w obiekcie AutocompleteOptions przekazywanym do konstruktora widżetu, jak pokazano w poprzednim przykładzie, lub wywołaj metodę setFields() na istniejącym obiekcie Autocomplete.

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

Określanie odchyleń i granic obszaru wyszukiwania w przypadku autouzupełniania

Wyniki autouzupełniania możesz dostosować, aby faworyzować przybliżoną lokalizację lub obszar, w ten sposób:

• Ustaw granice tworzenia obiektu Autocomplete.
• Zmień granice istniejącego Autocomplete.
• Ustaw granice na widoczny obszar mapy.
• Ogranicz wyszukiwanie do granic.
• Ogranicz wyszukiwanie do określonego kraju.

W poprzednim przykładzie pokazaliśmy, jak ustawić granice podczas tworzenia. Poniższe przykłady pokazują inne techniki stosowania odchyleń.

Zmiana granic istniejącego autouzupełniania

Wywołaj setBounds(), aby zmienić obszar wyszukiwania na istniejącymAutocomplete na prostokątne granice.

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);
index.ts

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);
index.js

Ustawianie granic na widoczny obszar mapy

Użyj parametru bindTo(), aby dostosować wyniki do widocznego obszaru mapy, nawet jeśli ten obszar się zmienia.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

Użyj ikony unbind(), aby odłączyć podpowiedzi autouzupełniania od obszaru widocznego na mapie.

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

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

Zobacz przykład

Ogranicz wyszukiwanie do bieżących granic

Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących granic, niezależnie od tego, czy są one oparte na widocznym obszarze mapy czy na granicach prostokątnych.

autocomplete.setOptions({ strictBounds: true });

Ograniczanie prognoz do określonego kraju

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

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

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

Zobacz przykład

Ograniczanie typów miejsc

Użyj opcji types lub zadzwoń pod numer setTypes(), aby ograniczyć prognozy do określonych typów miejsc. To ograniczenie określa typ lub zbiór typów, zgodnie z typami miejsc. Jeśli nie określono żadnego ograniczenia, zwracane są wszystkie typy.

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

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

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

  Lub:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• Dowolny filtr z tabeli 3 w sekcji Typy miejsc. Możesz podać tylko jedną wartość z tabeli 3.

Prośba zostanie odrzucona, jeśli:

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

Wersja demonstracyjna Autouzupełniania miejsc pokazuje różnice w prognozach między różnymi typami miejsc.

Wypróbuj wersję demonstracyjną

Pobieranie informacji o miejscu

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

1. Utwórz moduł obsługi zdarzeń dla zdarzenia place_changed i wywołaj addListener() na obiekcie Autocomplete, aby dodać moduł obsługi.
2. Wywołaj funkcję Autocomplete.getPlace() na obiekcie Autocomplete, aby pobrać obiekt PlaceResult, którego możesz następnie użyć do uzyskania dodatkowych informacji o wybranym miejscu.

Domyślnie, gdy użytkownik wybierze miejsce, autouzupełnianie zwraca wszystkie dostępne pola danych dla wybranego miejsca, a Ty otrzymasz odpowiednią fakturę. Użyj parametru Autocomplete.setFields(), aby określić, które pola danych o miejscu mają zostać zwrócone. Dowiedz się więcej o obiekcie PlaceResult, w tym o liście pól danych o miejscach, o które możesz poprosić. Aby uniknąć płacenia za dane, których nie potrzebujesz, użyj parametru Autocomplete.setFields(), aby określić tylko te dane o miejscach, które będziesz wykorzystywać.

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

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

W tym przykładzie użyto autouzupełniania do wypełnienia pól w formularzu adresu.

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();
}
index.ts

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;
index.js

Zobacz przykład

Dostosowywanie tekstu zastępczego

Domyślnie pole tekstowe utworzone przez usługę autouzupełniania 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ść symbolu zastępczego, musisz zadbać o jej lokalizację w aplikacji. Informacje o tym, jak interfejs Maps JavaScript API wybiera język, znajdziesz w dokumentacji dotyczącej lokalizacji.

Aby dostosować wygląd widżetu, zapoznaj się z artykułem Stylizowanie widżetów autouzupełniania i pola wyszukiwania.

Dodawanie widżetu SearchBox

SearchBox umożliwia użytkownikom wyszukiwanie geograficzne na podstawie tekstu, np. „pizza w Nowym Jorku” lub „sklepy obuwnicze w pobliżu ulicy Robson”. Możesz dołączyć SearchBox do pola tekstowego. W miarę wpisywania tekstu usługa będzie zwracać prognozy w postaci listy rozwijanej.

SearchBox udostępnia rozszerzoną listę prognoz, która może zawierać miejsca (zdefiniowane przez interfejs Places API) oraz sugerowane wyszukiwane hasła. Jeśli na przykład użytkownik wpisze „pizza w nowym”, lista wyboru może zawierać wyrażenie „pizza w Nowym Jorku” oraz nazwy różnych pizzerii. Gdy użytkownik wybierze miejsce z listy, informacje o tym miejscu zostaną zwrócone do obiektu SearchBox i będą dostępne dla Twojej aplikacji.

Konstruktor SearchBox przyjmuje 2 argumenty:

• Element HTML input typu text. Jest to pole wejściowe, które usługa SearchBox będzie monitorować i do którego będzie dołączać 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 mają być wyszukiwane miejsca. Wyniki są ukierunkowane na miejsca znajdujące się w tych granicach, ale nie są do nich ograniczone.

Poniższy kod używa parametru bounds, aby kierować wyniki na miejsca w określonym obszarze geograficznym, podanym za pomocą współrzędnych geograficznych.

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
});

Zmienianie obszaru wyszukiwania w przypadku komponentu SearchBox

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

Zobacz przykład

Pobieranie informacji o miejscu

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

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

// 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);
});
index.ts

// 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);
});
index.js

Zobacz przykład

Aby dostosować wygląd widżetu, zapoznaj się z artykułem Stylizowanie widżetów autouzupełniania i pola wyszukiwania.

Programowe pobieranie prognoz usługi autouzupełniania miejsc

Aby pobierać prognozy automatycznie, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego zwraca tablicę obiektów prognozy, z których każdy zawiera tekst prognozy, informacje referencyjne i szczegóły dotyczące dopasowania wyniku do danych wejściowych użytkownika. Jest to przydatne, jeśli chcesz mieć większą kontrolę nad interfejsem użytkownika niż w przypadku opcji Autocomplete i SearchBox opisanych powyżej.

AutocompleteService udostępnia te metody:

• getPlacePredictions() zwraca prognozy miejsc. Uwaga: „miejsce” może być obiektem, lokalizacją geograficzną lub ważnym punktem orientacyjnym, zgodnie z definicją interfejsu Places API.
• getQueryPredictions() zwraca rozszerzoną listę prognoz, które mogą obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli na przykład użytkownik wpisze „pizza w nowym”, na liście wyboru może się pojawić fraza „pizza w Nowym Jorku” oraz nazwy różnych pizzerii.

Obie powyższe metody zwracają tablicę obiektów prognoz w tej postaci:

• description to dopasowana prognoza.
• distance_meters to odległość w metrach od miejsca do określonego AutocompletionRequest.origin.
• matched_substrings zawiera w opisie zestaw podciągów, które pasują do elementów wprowadzonych przez użytkownika. Jest to przydatne do wyróżniania tych podciągów w aplikacji. W wielu przypadkach zapytanie będzie wyświetlane jako podciąg w polu opisu.
  • length to długość podciągu.
  • offset to przesunięcie znaku, mierzone od początku ciągu opisu, w którym pojawia się dopasowany podciąg.
• place_id to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w polu placeId żądania Szczegóły miejsca. Dowiedz się więcej o tym, jak odwoływać się do miejsca za pomocą identyfikatora miejsca.
• terms to tablica zawierająca elementy zapytania. W przypadku miejsca każdy element będzie zwykle stanowić część adresu.
  • offset to przesunięcie znaku, mierzone od początku ciągu opisu, w którym pojawia się dopasowany podciąg.
  • value to pasujące hasło.

W przykładzie poniżej wykonujemy żądanie prognozy zapytania dla frazy „pizza w pobliżu” i wyświetlamy wynik na liście.

// 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;
index.ts

// 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;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <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 script 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>
index.html

Zobacz przykład

Tokeny sesji

AutocompleteService.getPlacePredictions() może używać tokenów sesji (jeśli zostały wdrożone) do grupowania żądań autouzupełniania na potrzeby rozliczeń. Tokeny sesji grupują fazy zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi generować nowy token dla każdej sesji. W przypadku wszystkich sesji autouzupełniania zalecamy używanie tokenów sesji. Jeśli parametr sessionToken zostanie pominięty lub jeśli ponownie użyjesz tokena sesji, sesja zostanie obciążona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane osobno).

Możesz użyć tego samego tokena sesji, aby wysłać pojedyncze żądanie szczegółów miejsca dotyczące miejsca, które jest wynikiem wywołania funkcji AutocompleteService.getPlacePredictions(). W takim przypadku żądanie autouzupełniania jest łączone z żądaniem Szczegółów miejsca, a wywołanie jest naliczane jako zwykłe żądanie Szczegółów miejsca. Za żądanie autouzupełniania nie są pobierane żadne opłaty.

Pamiętaj, aby w przypadku każdej nowej sesji przekazywać unikalny token sesji. Użycie tego samego tokena w więcej niż 1 sesji Autocomplete spowoduje unieważnienie tych sesji, a wszystkie żądania Autocomplete w unieważnionych sesjach będą rozliczane osobno przy użyciu SKU Autocomplete za żądanie. Więcej informacji o tokenach sesji

Poniższy przykład pokazuje tworzenie tokena sesji, a następnie przekazywanie go w AutocompleteService (funkcja displaySuggestions() została pominięta dla zwięzłości):

// 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, aby w przypadku każdej nowej sesji przekazywać unikalny token sesji. Użycie tego samego tokena w więcej niż 1 sesji spowoduje naliczenie opłaty za każde żądanie osobno.

Więcej informacji o tokenach sesji

Stylizowanie widżetów Autocomplete i SearchBox

Domyślnie elementy interfejsu dostarczane przez Autocomplete i SearchBox są stylizowane tak, aby można było je umieścić na mapie Google. Możesz dostosować styl do swojej witryny. Dostępne są te klasy CSS: Wszystkie wymienione poniżej klasy dotyczą zarówno widżetu Autocomplete, jak i SearchBox.

Optymalizacja autouzupełniania miejsc (starsza wersja)

W tej sekcji opisujemy sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi Autouzupełnianie miejsc (starsza wersja).

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania miejsc (starszego) z Maps JavaScript API, widżetu autouzupełniania miejsc (starszego) z pakietu SDK Miejsc na Androida lub elementu interfejsu autouzupełniania miejsc (starszego) z pakietu SDK Miejsc na iOS.
• Od początku poznaj najważniejsze pola danych interfejsu Place Autocomplete (starszego).
• Pola dotyczące preferowania lokalizacji i ograniczania lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na skuteczność autouzupełniania.
• Używaj obsługi błędów, aby zapewnić prawidłowe działanie aplikacji, gdy interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuacje, w których nie ma wyboru, i oferuje użytkownikom możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi autouzupełniania miejsc (starszej wersji), używaj masek pól w widżetach szczegółów miejsca (starszej wersji) i autouzupełniania miejsc (starszej wersji), aby zwracać tylko potrzebne pola z danymi o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie autouzupełniania miejsc (starsza wersja), aby uzyskać dostęp do ceny za żądanie i zamiast szczegółów miejsca (starsza wersja) wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca. Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (oparte na sesjach), jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca, interfejs Geocoding API dostarczy te informacje za mniejszą opłatą niż wywołanie interfejsu Place Details (starszego).
• Jeśli użytkownicy wybiorą prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognoz autouzupełniania miejsc (starsza wersja), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.

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

Sprawdzone metody dotyczące wydajności

Poniższe wytyczne opisują sposoby optymalizacji skuteczności autouzupełniania miejsc (starsza wersja):

• Dodaj do implementacji funkcji Autouzupełnianie miejsca (starsza wersja) ograniczenia dotyczące kraju, ustawianie preferencji lokalizacji i (w przypadku implementacji programowych) preferencje językowe. W przypadku widżetów nie trzeba określać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli usługa autouzupełniania miejsc (starsza wersja) jest używana z mapą, możesz określić lokalizację na podstawie widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z prognoz autouzupełniania miejsca (starsza wersja), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć pierwotnego tekstu wpisanego przez użytkownika, aby uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania Find Place (Legacy). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawień lokalizacji.
  Inne scenariusze, w których warto wrócić do Geocoding API:
  • użytkownicy wpisujący adresy podrzędne, np. adresy konkretnych lokali lub mieszkań w budynku; Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściową podpowiedź w usłudze Autouzupełnianie miejsc (starsza wersja).
  • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23–30 29th St, Queens” w Nowym Jorku lub „47–380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Limity wykorzystania

Limity

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