Autouzupełnianie miejsc

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

Wprowadzenie

Autouzupełnianie to funkcja biblioteki Miejsc w interfejsie Maps JavaScript API. Dzięki autouzupełnianiu można nadać aplikacjom priorytet wyszukiwania w polu wyszukiwania Map Google. Usługa autouzupełniania może dopasować pełne słowa i podłańcuchy, określając nazwy miejsc, adresy i kody plus. W związku z tym aplikacje mogą wysyłać zapytania jako typy użytkowników, aby na bieżąco przekazywać prognozy.

Pierwsze kroki

Zanim użyjesz biblioteki Miejsc w interfejsie Maps JavaScript API, sprawdź, czy interfejs Places API jest włączony w Google Cloud Console w tym samym projekcie, który został skonfigurowany dla 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ź Places 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 Places API, a następnie wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Gdy proces dobiegnie końca, interfejs API Miejsc Google pojawi się na liście interfejsów API w panelu.

Wczytuję bibliotekę

Usługa Miejsca to samodzielna biblioteka niezależna od głównego kodu interfejsu API JavaScript Map Google. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw wczytać go za pomocą parametru libraries w adresie URL rozruchowego interfejsu API Map Google:

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

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

Podsumowanie zajęć

Interfejs API udostępnia 2 typy widżetów autouzupełniania, które można dodać odpowiednio za pomocą klas Autocomplete i SearchBox. Dodatkowo możesz użyć klasy AutocompleteService, aby automatycznie pobierać wyniki autouzupełniania (zobacz dokumentację interfejsu API JavaScript Map Google: klasa autouzupełniania usługi).

Oto podsumowanie dostępnych zajęć:

  • Autocomplete dodaje pole tekstowe do strony internetowej i monitoruje to pole pod kątem znaków. Gdy użytkownik wpisuje tekst, funkcja autouzupełniania wyświetla podpowiedzi w formie listy wyboru. Gdy użytkownik wybierze miejsce z listy, informacje o nim zostaną zwrócone do obiektu autouzupełniania i może je pobrać Twoja aplikacja. (szczegóły znajdziesz poniżej).
    Pole tekstowe autouzupełniania i lista podpowiedzi miejsc, które użytkownik wpisuje podczas wpisywania zapytania.
    Rys. 1: Autouzupełnianie pola tekstowego i wyboru listy
    Wypełniony formularz adresu.
    Ilustracja 2. Wypełniony formularz adresu
  • SearchBox dodaje pole do wprowadzania tekstu do Twojej strony internetowej w taki sam sposób, jak w Autocomplete. Różnice są następujące:
    • Główną różnicą są wyniki wyświetlane na liście wyboru. SearchBox udostępnia obszerną listę prognoz, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane zapytania. Jeśli np. użytkownik wpisze „pizzeria w Gdańsku”, na liście mogą pojawić się wyrażenia „pizza w Gdańsku” i „Pizzeria w Gdańsku”.
    • SearchBox oferuje mniej opcji niż Autocomplete, aby zawęzić wyszukiwanie. W pierwszym przypadku możesz odchylić wyszukiwanie dla danego LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do określonego kraju i określonych typów miejsc, a także ustawić granice. Więcej informacji znajdziesz poniżej.
    Wypełniony formularz adresu.
    Ilustracja 3. SearchBox przedstawia wyszukiwane hasła i podpowiedzi.
    Szczegółowe informacje znajdziesz poniżej.
  • Możesz utworzyć obiekt AutocompleteService, aby automatycznie pobierać prognozy. 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 i szczegółowe informacje o tym, jak wynik pasuje do danych wejściowych użytkownika. Sprawdź szczegóły 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 interfejsu i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każdy wpis na liście odpowiada pojedynczemu miejscu (zgodnie z definicją w interfejsie Places API).

Konstruktor Autocomplete przyjmuje 2 argumenty:

  • Element HTML input typu text. To pole do wprowadzania danych, które usługa autouzupełniania będzie monitorować i dołączać do wyników.
  • Opcjonalny argument AutocompleteOptions, który może zawierać te właściwości:
    • Tablica danych fields do uwzględnienia w odpowiedzi Place Details dla wybranego użytkownika PlaceResult. Jeśli usługa nie jest skonfigurowana lub jeśli pole ['ALL'] jest przekazywane, wszystkie dostępne pola są zwracane i rozliczane w przypadku (niezalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
    • Tablica types, która określa typ wyraźny lub kolekcję typów, zgodnie z listą obsługiwanych typów. Jeśli nie określisz typu, zwracane są wszystkie typy.
    • bounds to obiekt google.maps.LatLngBounds określający obszar wyszukiwania miejsc. Wyniki są obiektywne, ale nie ograniczają się do miejsc zawartych w tych granicach.
    • strictBounds to boolean, który określa, czy interfejs API musi zwracać tylko te miejsca, które są ściśle w regionie określonym przez bounds. Interfejs API nie zwraca wyników poza ten region, nawet jeśli pasują one do danych wejściowych użytkownika.
    • componentRestrictions może być używany do ograniczania wyników do określonych grup. Obecnie za pomocą filtra componentRestrictions możesz filtrować dane według maksymalnie 5 krajów. Kraje muszą być przesłane jako dwuznakowy kod kraju w formacie ISO 3166-1 alfa-2. Musisz podać wiele krajów jako listę kodów krajów.

      Uwaga: jeśli z kodem kraju otrzymasz nieoczekiwane wyniki, sprawdź, czy używasz kodu zawierającego wybrane kraje, terytoria zależne i określone obszary zainteresowań geograficznych. Informacje o kodach znajdziesz na stronie Wikipedii: lista kodów krajów w formacie ISO 3166 lub na platformie przeglądania online w standardzie ISO.

    • Możesz użyć polecenia placeIdOnly, aby polecić widżetowi Autocomplete pobieranie tylko identyfikatorów miejsc. Podczas wywoływania getPlace() w obiekcie Autocomplete dostępne PlaceResult będą miały ustawione tylko właściwości place id, types i name. Zwracanego identyfikatora miejsca można używać w połączeniach z usługami Miejsca, Geokodowanie, Trasa dojazdu i Matryca odległości.

Ograniczanie podpowiedzi autouzupełniania

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

Ustaw opcje w budowie

Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, by ustawiać ograniczenia przy tworzeniu widżetu. Poniższy przykład pokazuje, jak ustawić opcje bounds, componentRestrictions i types, aby wysyłać prośby o określenie miejsc typu establishment, faworyzować te z określonego obszaru geograficznego i ograniczać prognozy tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje o wybranym miejscu użytkownika mają być zwracane.

Wywołaj setOptions(), aby zmienić wartość opcji 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,
  types: ["establishment"],
};

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,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Określ pola danych

Określ pola danych, aby uniknąć rozliczenia za kody SKU danych miejsca, których nie potrzebujesz. Wstaw właściwość fields w elemencie AutocompleteOptions przekazywanym do konstruktora widżetu (jak pokazano w poprzednim przykładzie) lub wywołaj funkcję setFields() w istniejącym obiekcie Autocomplete.

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

Określ odchylenia i granice obszaru wyszukiwania na potrzeby autouzupełniania

Wyniki autouzupełniania możesz podać na podstawie przybliżonej lokalizacji lub obszaru na te sposoby:

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

Poprzedni przykład pokazuje granice wyznaczania wartości podczas tworzenia. Poniższe przykłady pokazują inne techniki promowania wyników.

Zmienianie granic istniejącego autouzupełniania

Wywołaj setBounds(), aby zmienić obszar wyszukiwania na 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);
Wyznacz granice do widocznego obszaru mapy

Użyj bindTo(), by odchylać wyniki do widocznego obszaru mapy, nawet jeśli się on zmieni.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Użyj przycisku unbind(), aby usunąć podpowiedź autouzupełniania z widocznego obszaru 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żących granic

Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących granic, niezależnie od tego, czy widoczny jest obszar mapy czy prostokątny.

autocomplete.setOptions({ strictBounds: true });
Ogranicz podpowiedzi do określonego kraju

Użyj opcji componentRestrictions lub wywołaj metodę setComponentRestrictions(), aby ograniczyć wyszukiwanie autouzupełniania do konkretnego 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

Ograniczenia dotyczące typów miejsc

Aby ograniczyć prognozy dotyczące określonych typów miejsc, użyj opcji types lub wywołaj metodę setTypes(). To ograniczenie określa typ lub kolekcję typów, jak opisano w sekcji Typy miejsc. Jeśli nie określisz ograniczenia, zostaną zwrócone wszystkie typy.

Jako wartość opcji types lub wartość przekazana do setTypes() możesz określić:

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

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

    lub:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Dowolny filtr w tabeli 3 z typów 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.
  • Możesz mieszać typy z tabeli 1 lub tabeli 2 z dowolnym filtrem z tabeli 3.

Demonstracja autouzupełniania w Miejscach pokazuje różnice między podpowiedziami w różnych typach miejsc.

Odwiedź wersję demonstracyjną

Uzyskiwanie informacji o miejscu

Gdy użytkownik wybierze miejsce spośród prognoz dołączonych do pola tekstowego autouzupełniania, usługa wywoła zdarzenie place_changed. Aby uzyskać szczegółowe informacje o miejscu:

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

Domyślnie, gdy użytkownik wybierze miejsce, funkcja autouzupełniania zwróci wszystkie dostępne pola danych dotyczące tego miejsca, a opłata zostanie odpowiednia naliczona. Użyj metody Autocomplete.setFields(), aby określić, które pola danych miejsc 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 nie płacić za niepotrzebne dane, użyj właściwości Autocomplete.setFields(), aby określić tylko te dane miejsca, których będziesz używać.

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

W formularzach adresowych przydatne jest podanie ich w formacie uporządkowanych danych. Aby zwrócić adres strukturalny wybranego miejsca, wywołaj pole Autocomplete.setFields() i podaj pole address_components.

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

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

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 przetłumaczony automatycznie. Jeśli określisz własną wartość zmiennej, musisz ją przetłumaczyć w aplikacji. Informacje o tym, jak interfejs API JavaScriptu w Mapach Google wybiera język, znajdziesz w dokumentacji dotyczącej lokalizacji.

Aby dostosować wygląd widżetu, przeczytaj artykuł Dodawanie stylów autouzupełniania i SearchBox.

SearchBox pozwala użytkownikom przeprowadzać wyszukiwania tekstowe, np. „pizza w Krakowie” lub „sklepy obuwnicze w pobliżu Mokotów”. Możesz dołączyć SearchBox do pola tekstowego, a gdy wprowadzisz tekst, usługa zwróci podpowiedzi w formie listy rozwijanej.

SearchBox udostępnia rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane zapytania. Jeśli np. użytkownik wpisze „pizzeria w Gdańsku”, na liście mogą pojawić się wyrażenia „pizza w Gdańsku” i „Pizzeria w Gdańsku”. Gdy użytkownik wybierze miejsce z listy, informacje o tym miejscu zostaną zwrócone do obiektu SearchBox i może je pobrać Twoja aplikacja.

Konstruktor SearchBox przyjmuje 2 argumenty:

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

Następujący kod korzysta z parametru granicy, aby odchylić wyniki do miejsc na określonym obszarze geograficznym, określonym 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
});

Zmienianie obszaru wyszukiwania w SearchBox

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

Zobacz przykład

Uzyskiwanie informacji o miejscu

Gdy użytkownik wybierze element z podpowiedzi przypisanych do pola wyszukiwania, usługa wywoła zdarzenie places_changed. Możesz wywołać obiekt 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 szczegółowych informacji o miejscach.

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 dostosować wygląd widżetu, przeczytaj artykuł Dodawanie stylów autouzupełniania i SearchBox.

Automatyczne pobieranie prognoz usługi autouzupełniania miejsc

Aby automatycznie pobierać prognozy, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów interfejsu. Zamiast tego zwraca tablicę obiektów prognozy, które zawierają tekst prognozy, informacje referencyjne i szczegóły dotyczące dopasowania wyniku do danych użytkownika. Jest to przydatne, gdy chcesz mieć większą kontrolę nad interfejsem niż ta, którą zapewniają Autocomplete i SearchBox opisane powyżej.

AutocompleteService udostępnia te metody:

  • getPlacePredictions() zwraca prognozy miejsc. Uwaga: „miejsce” może być instytucją, lokalizacją geograficzną lub ważnym miejscem zdefiniowanym przez interfejs Places API.
  • getQueryPredictions() zwraca rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane zapytania. Jeśli np. użytkownik wpisze „pizzeria w Gdańsku”, na liście mogą pojawić się wyrażenia „pizza w Gdańsku” i „Pizzeria w Gdańsku”.

Obie powyższe metody zwracają tablicę obiektów prognoz w następującej formie:

  • description to pasująca prognoza.
  • distance_meters to odległość w metrach od miejsca podane przez użytkownika AutocompletionRequest.origin.
  • matched_substrings zawiera zestaw podłańcuchów w opisie, które odpowiadają elementom w danych wejściowych 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 opisowego, w którym występuje dopasowane 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 odwoływaniu się do miejsc z identyfikatorem miejsca.
  • terms to tablica zawierająca elementy zapytania. W przypadku miejsca każdy element zwykle składa się na część adresu.
    • offset to przesunięcie znaku mierzone od początku ciągu opisowego, w którym występuje dopasowane podłańcuch.
    • value to pasujące hasło.

Przykład poniżej pokazuje żądanie prognozy zapytania dla wyrażenia „pizza w pobliżu” i wyświetla wynik na liście.

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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Fragment

Zobacz przykład

Tokeny sesji

AutocompleteService.getPlacePredictions() używa tokenów sesji do grupowania żądań autouzupełniania dla celów rozliczeniowych. Tokeny sesji grupują fazy zapytania i wyboru użytkownika w autouzupełnianiu wyszukiwania w osobne sesje do celów rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, i zakończy się, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań i 1 wybór miejsca. Po zakończeniu sesji token jest nieważny. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji dla wszystkich sesji autouzupełniania. Jeśli parametr sessionToken jest pomijany lub jeśli użyjesz tokena sesji, opłata za sesję wygląda tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane oddzielnie).

Możesz użyć tego samego tokena sesji, by przesłać jedno żądanie szczegółów miejsca w miejscu, które wywołało połączenie z firmą AutocompleteService.getPlacePredictions(). W takim przypadku żądanie autouzupełniania zostanie połączone z żądaniem szczegółowych informacji o miejscu, a opłata zostanie pobrana jako zwykłe żądanie dotyczące szczegółów miejsca. Za żądanie autouzupełniania nie pobiera się żadnych opłat.

Pamiętaj, aby przekazać unikalny token sesji dla każdej nowej sesji. Użycie tego samego tokena dla więcej niż jednej sesji autouzupełniania powoduje unieważnienie sesji autouzupełniania, a każde żądanie autouzupełniania w nieprawidłowych sesjach jest obciążane indywidualnie za pomocą kodu autouzupełniania na żądanie. Więcej informacji o tokenach sesji

Poniższy przykład pokazuje, jak utworzyć token sesji, a potem przekazać go w funkcji AutocompleteService (funkcja displaySuggestions() została pominięta w skrócie):

// 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 przekazać unikalny token sesji dla każdej nowej sesji. Użycie tego samego tokena w przypadku więcej niż jednej sesji spowoduje naliczenie każdej opłaty oddzielnie.

Więcej informacji o tokenach sesji

Określanie stylu widżetów autouzupełniania i SearchBox

Domyślnie elementy interfejsu dostarczane przez firmy Autocomplete i SearchBox są wybierane w taki sposób, aby można było uwzględnić je na mapie Google. Możesz zmienić styl, aby dopasować reklamy do swojej witryny. Dostępne są następujące klasy CSS. Wszystkie wymienione poniżej klasy mają zastosowanie do widżetów Autocomplete i SearchBox.

Grafika przedstawiająca klasy CSS 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 miejsca. Ta lista jest widoczna jako lista rozwijana 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 wybierany przez użytkownika za pomocą klawiatury. Uwaga: wybrane elementy będą członkiem tej klasy i klasy pac-item.
pac-item-query Zakres w elemencie pac-item, który jest główną częścią prognozy. W przypadku lokalizacji geograficznych zawiera nazwę miejsca, np. „Sydney”, lub nazwę ulicy i numer, np. „ul. Królowa 10”. W przypadku wyszukiwań tekstowych, takich jak „pizza w Gdańsku”, zawiera ona pełny tekst zapytania. Domyślnie pac-item-query jest czarny. Jeśli tekst pac-item zawiera dodatkowy tekst, jest on spoza zakresu pac-item-query i dziedziczy jego styl z elementu 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. Dopasowany tekst może znajdować się w dowolnym miejscu w: pac-item. Nie musi być częścią pac-item-query, ale może być częściowo w pac-item-query, a częściowo w pozostałym tekście w pac-item.

Optymalizacja autouzupełniania miejsc

W tej sekcji znajdziesz sprawdzone metody, 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 utworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania w interfejsie Maps JavaScript, widżetu autouzupełniania w pakiecie SDK do Androida lub sposobu kontroli interfejsu użytkownika autouzupełniania w pakiecie SDK dla iOS.
  • Naucz się najważniejszych pól danych autouzupełniania miejsc od samego początku.
  • Pola promowania ze względu na lokalizację i ograniczenia dotyczące lokalizacji są opcjonalne, ale mogą mieć duży wpływ na skuteczność autouzupełniania.
  • Użyj obsługi błędów, aby aplikacja działała płynnie w przypadku błędu interfejsu API.
  • Dopilnuj, aby aplikacja obsługiwała, gdy nie jest wybrana żadna opcja, i aby użytkownicy mogli go kontynuować.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi autouzupełniania miejsc, użyj masek pól w szczegółach szczegółów miejsca i widżetów autouzupełniania miejsc, aby zwracać tylko wymagane pola danych o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ użycie implementacji autouzupełniania miejsc, aby uzyskać dostęp do cennika według żądania i poprosić o wyniki interfejsu API dotyczące geokodowania dotyczące wybranego miejsca zamiast szczegółowych informacji o miejscu. Ceny na żądanie w połączeniu z interfejsem API kodowania geograficznego są bardziej opłacalne niż model na sesję (na podstawie sesji), jeśli spełnione są oba te warunki:

  • Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca użytkownika, interfejs Geocoding API dostarcza te informacje w przypadku mniejszej liczby wywołań miejsca.
  • Jeśli użytkownicy wybiorą prognozę autouzupełniania w średnio 4 żądaniach autouzupełniania prognozowanych lub niższych, ustalanie cen na żądanie może być bardziej opłacalne niż model cenowy sesji.
Aby uzyskać pomoc w implementacji autouzupełniania miejsc, należy wybrać kartę odpowiadającą odpowiedzi na poniższe pytanie.

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

Tak, chcę więcej informacji

Korzystaj z autouzupełniania miejsc na podstawie sesji z informacjami o miejscu.
Twoja aplikacja wymaga szczegółowych informacji o miejscu, takich jak nazwa miejsca, status firmy czy godziny otwarcia, dlatego implementacja autouzupełniania powinna korzystać z tokena sesji (automatycznego albo wbudowanego w widżety JavaScript, Androida lub iOS) za łączny koszt wynoszący 0,017 USD na sesję plus odpowiednie kody danych miejsca w zależności od żądanych pól danych o miejscu.

Implementacja widżetów
Zarządzanie sesją jest automatycznie wbudowane w widżety
JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania miejsc dotyczące wybranych prognoz. Określ parametr fields, aby mieć pewność, że wysyłasz tylko wymagane pola danych o miejscach.

Wdrażanie automatyzacji
W przypadku żądań autouzupełniania w miejscu użyj tokena sesji. Żądając szczegółów miejsca dotyczących wybranej prognozy, podaj te parametry:

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

Nie, wymaga tylko adresu i lokalizacji

W zależności od wydajności użycia funkcji autouzupełniania w miejscu docelowym aplikacja Geocoding API może być bardziej opłacalną opcją niż szczegóły miejsca. Wydajność autouzupełniania każdej aplikacji różni się w zależności od tego, co użytkownicy wpisują, gdzie jest używana i czy zastosowano sprawdzone metody optymalizacji skuteczności.

Aby odpowiedzieć na to pytanie, przeanalizuj średnią liczbę znaków wpisywanych przez użytkownika przed wybraniem podpowiedzi autouzupełniania w aplikacji.

Czy użytkownicy częściej wybierają prognozę autouzupełniania miejsc w maksymalnie 4 żądaniach?

Tak

Zaimplementuj automatyczne uzupełnianie miejsc bez tokenów sesji i wywołuj interfejs Geocoding API w prognozie dotyczącej wybranego miejsca.
Interfejs Geocode API udostępnia adresy i szerokość i szerokość geograficzną w cenie 0,005 USD za żądanie. Wystąpienie 4 żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołanie Geocoding API dotyczące prognozy wybranego miejsca wyniesie 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję wynoszącą 0,017 USD.1

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom wyświetlanie podpowiedzi, których jeszcze nie używają.

Nie

Korzystaj z autouzupełniania miejsc na podstawie sesji z informacjami o miejscu.
Ponieważ średnia liczba żądań, które oczekujesz od użytkownika, zanim użytkownik wybierze prognozę prognozy dotyczącej autouzupełniania miejsc, przekracza koszt ceny na sesję, w Twojej implementacji autouzupełniania miejsc należy użyć tokena sesji zarówno w przypadku żądań autouzupełniania miejsc, jak i powiązanych żądań informacji o miejscu.Ten koszt wynosi 0,017 USD na sesję.1

Implementacja widżetów
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania miejsc dotyczące wybranych prognoz. Określ parametr fields, aby mieć pewność, że wysyłasz tylko żądania dotyczące danych podstawowych.

Wdrażanie automatyzacji
W przypadku żądań autouzupełniania w miejscu użyj tokena sesji. Żądając szczegółów miejsca dotyczących wybranej prognozy, podaj te parametry:

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

Rozważ opóźnienie żądań autouzupełniania miejsc
Możesz stosować strategie, takie jak opóźnienie żądania autouzupełniania miejsc, dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, aby Twoja aplikacja wysyłała mniej żądań. Na przykład wysyłanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze prognozę, w przypadku której wyślesz 1 żądanie interfejsu Geocoding API, całkowity koszt wyniesie 0,01632 PLN (4 * 0,00283 autouzupełniania na żądanie + 0,005 PLN).

Jeśli opóźnione żądania mogą spowodować żądanie średniej automatyzacji poniżej 4, możesz postępować zgodnie ze wskazówkami dotyczącymi implementacji autouzupełniania miejsc z użyciem interfejsu Geocode API. Opóźnienie żądań może być odbierane przez użytkowników, którzy mogą oczekiwać podpowiedzi po każdym nowym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom wyświetlanie podpowiedzi, których szuka (mniej znaków).


  1. Wymienione tutaj koszty są w dolarach amerykańskich. Pełne ceny znajdziesz na stronie Płatności w Google Maps Platform.

Sprawdzone metody dotyczące skuteczności

Te wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj ograniczenia językowe, promowania lokalizacji i preferencji języka w implementacji autouzupełniania miejsc. W przypadku widżetów wybór języka jest niepotrzebny, ponieważ to one wybierają przeglądarkę w przeglądarce lub na urządzeniu mobilnym użytkownika.
  • Jeśli umiejscowieniu autouzupełniania miejsca towarzyszy mapa, możesz odchylenia lokalizacji na podstawie widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze jednego z podpowiedzi autouzupełniania, zwykle dlatego, że żadna z nich nie jest pożądanym adresem wyniku. Aby uzyskać trafniejsze wyniki, możesz ponownie użyć danych wejściowych użytkownika:
    • Jeśli oczekujesz, że użytkownik wpisze tylko informacje adresowe, użyj ponownie danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
    • Jeśli spodziewasz się, że użytkownik wpisze zapytania dotyczące określonego miejsca według nazwy lub adresu, użyj opcji Znajdź miejsce. Jeśli wyniki są oczekiwane tylko w określonym regionie, skorzystaj z funkcji promowania lokalizacji.
    Inne scenariusze, w których najlepiej jest wrócić do interfejsu Geocoding API, to:
    • Użytkownicy wpisują adresy podrzędne w krajach, w których funkcja autouzupełniania adresów miejsc jest niekompletna, np. w Czechach, Estonii i na Litwie. Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściową prognozę w autouzupełnianiu miejsca.
    • Użytkownik wpisuje adres z prefiksem segmentu drogi, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawai'i.

Limity i zasady użytkowania

Limity

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

Zasady

Korzystanie z biblioteki Miejsc oraz interfejsu API JavaScript Map musi być zgodne z zasadami opisanymi w interfejsie Places API.