Autouzupełnianie miejsc

Wprowadzenie

Autouzupełnianie to funkcja biblioteki Miejsca w Maps JavaScript API. Możesz użyć autouzupełniania, aby umożliwić aplikacjom korzystanie z funkcji wyszukiwania typu „type ahead” w polu wyszukiwania w Mapach Google. Usługa autouzupełniania może dopasowywać pełne słowa i podciągi, rozwiązując nazwy miejsc, adresy i kody Plus Code. Aplikacje mogą więc wysyłać zapytania w miarę ich wpisywania przez użytkownika, aby na bieżąco przewidywać nazwy miejsc. Zgodnie z definicją interfejsu Places API „miejscem” może być lokal, lokalizacja geograficzna lub ważny punkt zainteresowania.

Pierwsze kroki

Zanim użyjesz biblioteki Miejsca w interfejsie Maps JavaScript API, upewnij się, że 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 skonfigurowany dla interfejsu Maps JavaScript API i kliknij Otwórz.
3. Na liście interfejsów API w panelu odszukaj Place API.
4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejs API nie jest wymieniony, włącz go:
   1. U góry strony kliknij WŁĄCZ API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
   2. Wyszukaj Places API, a następnie wybierz go z listy wyników.
   3. Wybierz WŁĄCZ. Po zakończeniu procesu interfejs Places API pojawi się na liście interfejsów API w panelu.

Ładowanie biblioteki

Usługa Miejsca to samodzielna biblioteka, oddzielona od głównego kodu Maps JavaScript API. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw ją załadować, używając parametru libraries w adresie URL inicjalizacji 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 artykule Omówienie bibliotek.

Podsumowanie zajęć

Interfejs API udostępnia 2 typy widżetów autouzupełniania, które możesz dodać odpowiednio za pomocą klas Autocomplete i SearchBox. Dodatkowo możesz użyć klasy AutocompleteService, aby pobrać wyniki autouzupełniania programowo (patrz: AutocompleteService API JavaScript).

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

• Autocomplete dodaje na stronie internetowej pole tekstowe, które sprawdza, czy użytkownik wpisuje w nim znaki. Gdy użytkownik wpisze tekst, autouzupełnianie zwróci przewidywane miejsca w postaci listy rozwijanej. Gdy użytkownik wybierze miejsce z listy, informacje o tym miejscu są zwracane do obiektu autouzupełniania i mogą zostać pobrane przez aplikację. Szczegółowe informacje znajdziesz poniżej.

  

  

• SearchBox dodaje pole tekstowe do strony internetowej w podobny sposób do Autocomplete. Różnice są następujące:
  • Główna różnica polega na tym, że na liście dostępnych opcji wyświetlają się inne wyniki. SearchBox udostępnia rozszerzoną listę przewidywań, 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 Jorku”, lista może zawierać wyrażenie „pizza w Nowym Jorku” oraz nazwy różnych pizzerii.
  • SearchBox ma mniej opcji ograniczania wyszukiwania niż Autocomplete. W pierwszym przypadku możesz skoncentrować wyszukiwanie na określonym LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do konkretnego kraju i konkretnych typów miejsc, a także ustawić granice. Więcej informacji znajdziesz poniżej.

  

  Szczegółowe informacje znajdziesz poniżej.
• Możesz utworzyć obiekt AutocompleteService, aby pobierać prognozy programowo. Wywołaj funkcję getPlacePredictions(), aby pobrać pasujące miejsca, lub funkcję getQueryPredictions(), aby pobrać pasujące miejsca oraz sugerowane hasła wyszukiwania. Uwaga: AutocompleteService nie dodaje żadnych elementów sterujących interfejsem. Zamiast tego podane wyżej metody zwracają tablicę obiektów prognozy. Każdy obiekt prognozy zawiera tekst prognozy, a także informacje referencyjne i szczegóły dotyczące dopasowania wyniku do danych wejściowych użytkownika. Szczegółowe informacje znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widget Autocomplete tworzy pole tekstowe na stronie internetowej, podaje prognozy miejsc w liście wyboru w interfejsie i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każdy wpis na liście wyboru odpowiada jednemu miejscu (zdefiniowanemu przez interfejs 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 którego będzie dołączać 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 PlaceResult. Jeśli właściwość nie jest ustawiona lub jeśli przekazana zostanie wartość ['ALL'], zwracane są wszystkie dostępne pola i obliczane (nie zalecamy tego w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
  • Tablica types, która określa jawny typ lub zbiór typów wymienionych w obsługiwanych typach. Jeśli nie podasz typu, zwrócone zostaną wszystkie typy.
  • bounds to obiekt google.maps.LatLngBounds określający obszar, w którym mają być wyszukiwane miejsca. Wyniki są zorientowane na miejsca znajdujące się w tych granicach, ale nie są do nich ograniczone.
  • strictBounds to booleanokreślający, czy interfejs API musi zwracać tylko te miejsca, które znajdują się w regionie zdefiniowanym przez dany bounds. Interfejs API nie zwraca wyników spoza tego regionu, nawet jeśli pasują one do danych wejściowych użytkownika.
  • componentRestrictions możesz użyć, aby ograniczyć wyniki do konkretnych grup. Obecnie za pomocą componentRestrictions możesz filtrować według maksymalnie 5 krajów. Kraje muszą być przekazywane jako dwuliterowe kody zgodne ze standardem ISO 3166-1 alfa-2. Wiele krajów musi być podanych 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 specjalne obszary o zainteresowaniach geograficznych. Informacje o kodach znajdziesz na Wikipedii: liście kodów ISO 3166 lub na platformie ISO Online Browsing Platform.

  • placeIdOnly może służyć do przekazywania widgetowi Autocomplete instrukcji pobierania tylko identyfikatorów miejsc. Po wywołaniu funkcji getPlace() obiektu Autocomplete udostępniony obiekt PlaceResult będzie miał tylko właściwości place id, types i name. Zwrócony identyfikator miejsca możesz używać w wywołaniach usług Miejsca, Geokodowania, Wskazówek dojazdu i Matricis Dystansów.

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc wyświetla wszystkie typy miejsc, preferując przewidywania w pobliżu lokalizacji użytkownika, i pobiera wszystkie dostępne pola danych dla wybranego miejsca. Ustaw opcje Autouzupełniania Miejsca, aby wyświetlać trafniejsze przewidywania na podstawie Twojego przypadku użycia.

Ustawianie opcji podczas tworzenia

Konstruktor Autocomplete przyjmuje parametr AutocompleteOptions, który służy do ustawiania ograniczeń podczas tworzenia widgeta. W tym przykładzie opcje bounds, componentRestrictions i types są ustawione tak, aby prosić o miejsca typu establishment, preferując te znajdujące się w określonym obszarze geograficznym i ograniczając prognozy tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje o wybranym miejscu mają być zwracane.

Aby zmienić wartość opcji w istniejącym widżecie, wywołaj funkcję setOptions().

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 SKU danych Places, których nie potrzebujesz. Uwzględnij właściwości fields w obiekcie AutocompleteOptions przekazywanym do konstruktora widgeta, jak w poprzednim przykładzie, lub wywołaj metodę setFields() w obiekcie Autocomplete.

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

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

Możesz wpływać na wyniki autouzupełniania, aby preferowały przybliżoną lokalizację lub obszar. Możesz to zrobić na te sposoby:

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

Poprzedni przykład pokazuje ustawienie ograniczeń podczas tworzenia. Poniższe przykłady pokazują inne techniki wprowadzania stronniczości.

Zmiana zakresu dotychczasowego okna Autouzupełniania

Wywołaj funkcję setBounds(), aby zmienić obszar wyszukiwania w dotychczasowym Autocomplete na prostokątny.

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

Ustaw granice na widoczny obszar mapy

Użyj opcji bindTo(), aby wyniki były bardziej dopasowane do widocznego obszaru mapy, nawet gdy ten obszar się zmienia.

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

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

Użyj unbind(), aby odłączyć przewidywania autouzupełniania od widoku mapy.

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

Aby ograniczyć wyniki do bieżących granic, np. na podstawie widocznego obszaru mapy lub prostokątnych granic, ustaw opcję strictBounds.

autocomplete.setOptions({ strictBounds: true });

Ograniczanie prognoz do konkretnego kraju

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

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 wywołania 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 zostanie określone żadne ograniczenie, zwrócone zostaną wszystkie typy.

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

• Tablica zawierająca do 5 wartości z tabeli 1 lub tabeli 2 w typach miejsc. Na 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:

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

Demonstracja autouzupełniania miejsc pokazuje różnice w prognozach między różnymi typami miejsc.

Otwórz wersję demonstracyjną

Pobieranie informacji o miejscu

Gdy użytkownik wybierze miejsce z podpowiedzi dołączonych do pola tekstowego automatycznego uzupełniania, usługa uruchamia zdarzenie place_changed. Aby uzyskać szczegóły miejsca:

1. Utwórz moduł obsługi zdarzenia place_changed i wywołaj metodę addListener() obiektu Autocomplete, aby dodać moduł obsługi.
2. Wywołaj metodę Autocomplete.getPlace() obiektu Autocomplete, aby pobrać obiekt PlaceResult, który pozwoli Ci uzyskać więcej informacji o wybranym miejscu.

Domyślnie, gdy użytkownik wybierze miejsce, autouzupełnianie zwraca wszystkie dostępne pola danych dla wybranego miejsca. Opłaty będą naliczane odpowiednio. Użyj parametru Autocomplete.setFields(), aby określić, które pola danych o miejscach 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 elementu Autocomplete.setFields(), aby określić tylko te dane o miejscach, których będziesz używać.

Właściwość name zawiera wartość description z podpowiedzi autouzupełniania w usłudze Places. Więcej informacji o description znajdziesz w dokumentacji dotyczącej autouzupełniania miejsc.

W przypadku formularzy adresowych warto uzyskać adres w formacie ustrukturyzowanym. Aby zwrócić adres uporządkowany wybranego miejsca, wywołaj funkcję Autocomplete.setFields() i wskaż pole address_components.

W tym przykładzie pola w formularzu adresu są wypełniane za pomocą autouzupełniania.

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ępczynny. 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 samodzielnie zadbać o jej lokalizowanie 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, przeczytaj artykuł Nadawanie stylu widżetom Autouzupełnianie i wyszukiwania.

Dodawanie widżetu SearchBox

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

SearchBox udostępnia rozszerzoną listę prognoz, która może obejmować miejsca (zdefiniowane przez interfejs Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wpisze „pizza w Nowym Jorku”, 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 mogą zostać pobrane przez aplikację.

Konstruktor SearchBox przyjmuje 2 argumenty:

• Element HTML input typu text. 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ą przybliżone do miejsc znajdujących się w tych granicach, ale nie są do nich ograniczone.

Podany niżej kod używa parametru granice, aby skoncentrować wyniki na miejscach w 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
});

Zmień obszar wyszukiwania w SearchBox

Aby zmienić obszar wyszukiwania dla istniejącego obiektu SearchBox, wywołaj metodę setBounds() obiektu SearchBox i podaj odpowiedni obiekt LatLngBounds.

Zobacz przykład

Pobieranie informacji o miejscu

Gdy użytkownik wybierze element z podpowiedzi dołączonych do pola wyszukiwania, usługa uruchamia zdarzenie places_changed. Możesz wywołać funkcję getPlaces() obiektu 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ółowych miejsc.

// 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 Dostosowywanie wyglądu widżetów Autouzupełnianie i wyszukiwarki.

Pobieranie podpowiedzi usługi autouzupełniania miejsc za pomocą kodu

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

AutocompleteService udostępnia te metody:

• getPlacePredictions() zwraca prognozy dotyczące miejsc. Uwaga: „miejscem” może być lokal, lokalizacja geograficzna lub ważny punkt zainteresowania zdefiniowany przez interfejs Places API.
• getQueryPredictions() zwraca rozszerzoną listę prognoz, która może zawierać miejsca (zdefiniowane przez Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wpisze „pizza w Nowym Jorku”, lista może zawierać wyrażenie „pizza w Nowym Jorku” oraz nazwy różnych pizzerii.

Obie te metody zwracają tablicę obiektów prognozy o tym formacie:

• description to dopasowana prognoza.
• distance_meters to odległość w metrach od miejsca do określonego AutocompletionRequest.origin.
• matched_substrings zawiera w opisie zbiór podciągów, które pasują do elementów podanych przez użytkownika. Jest to przydatne do wyróżniania tych podciągów w aplikacji. W wielu przypadkach zapytanie będzie występować jako podciąg w polu opisu.
  • length to długość podciągu.
  • offset to przesunięcie znaku liczone od początku ciągu znaków w opisie, w którym występuje dopasowany podciąg znaków.
• place_id to identyfikator tekstowy jednoznacznie identyfikujący miejsce. Aby pobrać informacje o miejscu, prześlij ten identyfikator w polu placeId w prośbie o 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 zwykle stanowi część adresu.
  • offset to przesunięcie znaku liczone od początku ciągu znaków w opisie, w którym występuje dopasowany podciąg znaków.
  • value to pasujące hasło.

W przykładzie poniżej wykonujemy żądanie prognozy zapytania dotyczące wyrażenia „pizza near” 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 są zaimplementowane) do grupowania żądań autouzupełniania na potrzeby rozliczeń. Na potrzeby rozliczeń tokeny sesji łączą fazy zapytania i wyboru w autouzupełnianiu w jedną sesję. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, 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. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania. Jeśli parametr sessionToken zostanie pominięty lub jeśli token sesji zostanie użyty ponownie, sesja zostanie obciążona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane osobno).

Możesz użyć tego samego tokenu sesji, aby wysłać pojedyncze żądanie Dane miejsca dotyczące miejsca, które jest wynikiem wywołania funkcji AutocompleteService.getPlacePredictions(). W takim przypadku prośba o autouzupełnianie jest połączona z prośbą o szczegóły miejsca, a za wywołanie usługi zostanie naliczona opłata jak za zwykłą prośbę o szczegóły miejsca. Za żądanie autouzupełniania nie są pobierane żadne opłaty.

Pamiętaj, aby w przypadku każdej nowej sesji przekazać unikalny token sesji. Użycie tego samego tokena w więcej niż 1 sesji autouzupełniania spowoduje unieważnienie tych sesji, a wszystkie żądania autouzupełniania w nieważnych sesjach zostaną naliczone osobno za pomocą SKU autouzupełniania na żądanie. Więcej informacji o tokenach sesji

Poniższy przykład pokazuje, jak utworzyć token sesji i przekazać go w formie 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 przekazać unikalny token sesji. Użycie tego samego tokena w więcej niż 1 sesji spowoduje, że za każde żądanie zostanie naliczona osobna opłata.

Więcej informacji o tokenach sesji

Nadawanie stylu widżetom Autouzupełnianie i SearchBox

Domyślnie elementy interfejsu użytkownika udostępniane przez Autocomplete i SearchBox są stylizowane pod kątem wyświetlania na mapie Google. Możesz dostosować stylizację do swojej witryny. Dostępne są te klasy CSS: Wszystkie klasy wymienione poniżej mają zastosowanie zarówno do widżetów Autocomplete, jak i SearchBox.

Optymalizacja autouzupełniania miejsc

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

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie: Widżetu autouzupełniania z Maps JavaScript API, Widżetu autouzupełniania z pakietu SDK Miejsc na Androida lub Widżetu autouzupełniania z pakietu SDK Miejsc na iOS.
• Na początku zaznaj się z najważniejszymi polami danych usługi Autouzupełnianie miejsc.
• Pola preferencji lokalizacji i ograniczeń lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie funkcji autouzupełniania.
• Użyj obsługi błędów, aby zapewnić płynne działanie aplikacji, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje przypadki, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

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 widżetach Szczegóły miejsca i Autouzupełnianie miejsc, aby zwracać tylko potrzebne pola z danymi o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrażanie funkcji Autocomplete miejsc, aby uzyskać dostęp do cen za prośbę i wysłać wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast Szczegółów miejsca. Cena taryfy „za żądanie” w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż taryfa „za sesję” (obejmująca poszczególne sesje) pod warunkiem spełnienia obu tych warunków:

• Jeśli interesuje Cię tylko szerokość geograficzna, długość geograficzna lub adres wybranego miejsca przez użytkownika, interfejs Geocoding API dostarczy te informacje w mniejszym stopniu niż wywołanie interfejsu PlaceDetails.
• Jeśli użytkownicy wybierają prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognozy autouzupełniania, cena za żądanie może być bardziej opłacalna niż cena za sesję.

Czy Twoja aplikacja wymaga jakichkolwiek informacji oprócz adresu i szerokości geograficznej/długości geograficznej wybranej prognozy?

Sprawdzone metody dotyczące wydajności

W tych wytycznych znajdziesz wskazówki dotyczące optymalizacji działania autouzupełniania w Google Maps:

• Dodaj ograniczenia dotyczące kraju, preferencje dotyczące lokalizacji oraz (w przypadku implementacji programowych) preferencje językowe do implementacji funkcji Autouzupełniania miejsc. W przypadku widżetów nie trzeba podawać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianie miejsc jest wyświetlane z mapą, możesz dostosować lokalizację do widoku mapy.
• Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, ponieważ żadna z nich nie jest pożądanym adresem, możesz ponownie użyć oryginalnego danych wejściowych użytkownika, aby uzyskać bardziej trafne wyniki:
  • Jeśli oczekujesz, że użytkownik poda tylko informacje o adresie, ponownie użyj 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 znajdowania miejsc. Jeśli wyniki mają być uzyskiwane tylko w konkretnym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których warto użyć interfejsu Geocoding API:
  • Użytkownicy wpisują adresy pomieszczeń w budynku, np. adresy konkretnych lokali w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” daje częściową podpowiedź w autouzupełnianiu adresów.
  • 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 i zasady dotyczące wykorzystania

Limity

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

Zasady

Korzystanie z biblioteki Miejsca, interfejsu Maps JavaScript API musi być zgodne z zasadami opisanymi w przypadku interfejsu Places API.