Na tej stronie opisujemy bibliotekę po stronie klienta, która jest dostępna z interfejsem Maps JavaScript API. Jeśli chcesz pracować na swoim serwerze z usługą internetową Places API, zapoznaj się z klientem Node.js dla usług Map Google. Na stronie, która znajduje się pod tym linkiem, przedstawiamy również klienta Java, klienta Pythona i klienta Go dla usług Map Google.
Wstęp
Autouzupełnianie to funkcja biblioteki Miejsca w interfejsie Maps JavaScript API. Dzięki autouzupełnianiu Twoje aplikacje mogą wyszukiwać z wyprzedzeniem w polu wyszukiwania Map Google.
Usługa autouzupełniania dopasowuje pełne słowa i podłańcuchy, rozpoznając nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w miarę wpisywania przez użytkowników, aby generować prognozy dotyczące miejsc na bieżąco.
Pierwsze kroki
Zanim użyjesz biblioteki Miejsc w interfejsie Maps JavaScript API, upewnij się, że interfejs Places API jest włączony w Google Cloud Console w tym samym projekcie, który został skonfigurowany na potrzeby Maps JavaScript API.
Kliknij przycisk Wybierz projekt, a następnie wybierz projekt skonfigurowany na potrzeby interfejsu Maps JavaScript API i kliknij Otwórz.
Na liście interfejsów API w panelu znajdź Places API.
Jeśli widzisz interfejs API na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
Aby wyświetlić kartę Biblioteka, u góry strony wybierz WŁĄCZ API. Możesz też wybrać Biblioteka w menu po lewej stronie.
Wyszukaj interfejs Places API, a następnie wybierz go z listy wyników.
Wybierz WŁĄCZ. Po zakończeniu procesu Places API pojawi się na liście interfejsów API w panelu.
Wczytuję bibliotekę
Usługa Miejsca jest samodzielną biblioteką, niezależną od głównego kodu interfejsu Maps JavaScript API. Aby korzystać z funkcji dostępnych w tej bibliotece, musisz ją najpierw wczytać za pomocą parametru libraries w adresie URL wczytywania interfejsu API Map Google:
Interfejs API udostępnia 2 rodzaje widżetów autouzupełniania, które można dodawać odpowiednio za pomocą klas Autocomplete i SearchBox.
Dodatkowo możesz używać klasy AutocompleteService do automatycznego pobierania wyników autouzupełniania (zobacz dokumentację interfejsu Maps JavaScript API: klasa AutocompleteService).
Poniżej znajdziesz podsumowanie dostępnych zajęć:
Autocomplete dodaje do strony internetowej pole tekstowe i monitoruje to pole pod kątem wpisów znaków. Gdy użytkownik wpisuje tekst, autouzupełnianie zwraca prognozy miejsc w postaci listy wyboru. Gdy użytkownik wybierze miejsce z listy, informacje o nim są zwracane do obiektu autouzupełniania i mogą być pobierane przez aplikację. Szczegółowe informacje znajdziesz poniżej.
Rys. 1. Pole tekstowe autouzupełniania i lista wyboruRys. 2. Wypełniony formularz z adresem
SearchBox dodaje do strony internetowej pole tekstowe podobne do Autocomplete. Różnice są następujące:
Główna różnica polega na wynikach wyświetlanych na liście wyboru. SearchBox dostarcza rozszerzoną listę prognoz, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wprowadzi hasło „pizza w nowym”, lista opcji może zawierać wyrażenie „pizza w Krakowie”, a także nazwy różnych pizzerii.
SearchBox oferuje mniej opcji ograniczania wyszukiwania niż Autocomplete. W pierwszym przypadku możesz ukierunkować wyszukiwanie na konkretną wartość LatLngBounds. W drugim przypadku możesz ograniczyć wyszukiwanie do określonych krajów i typów miejsc, a także określić granice. Więcej informacji znajdziesz poniżej.
Rysunek 3. Pole SearchBox przedstawia wyszukiwane hasła i prognozy miejsc.
Więcej informacji znajdziesz poniżej.
Aby automatycznie pobierać prognozy, możesz utworzyć obiekt AutocompleteService. Zadzwoń pod numer getPlacePredictions(), aby pobrać pasujące miejsca, lub getQueryPredictions(), aby pobrać pasujące miejsca i sugerowane wyszukiwane hasła.
Uwaga: AutocompleteService nie dodaje żadnych elementów sterujących interfejsu.
Zamiast tego powyższe metody zwracają tablicę obiektów prognoz. Każdy obiekt prognozy zawiera tekst prognozy, a także informacje referencyjne oraz szczegóły dotyczące tego, jak wynik pasuje do danych wejściowych użytkownika. Więcej informacji znajdziesz poniżej.
Dodawanie widżetu autouzupełniania
Widżet Autocomplete tworzy pole do wprowadzania tekstu na stronie internetowej, dostarcza prognozy miejsc na liście wyboru w interfejsie i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każda pozycja na liście wyboru odpowiada pojedynczemu miejscu (zgodnie z definicją w interfejsie Places API).
Konstruktor Autocomplete przyjmuje 2 argumenty:
Element HTML input typu text. Jest to pole do wprowadzania danych, które będzie monitorować usługa autouzupełniania i dołącza do niego swoje wyniki.
Opcjonalny argument AutocompleteOptions, który może zawierać te właściwości:
Tablica danych fields, które mają być uwzględnione w odpowiedzi Place Details dla wybranego przez użytkownika elementu PlaceResult. Jeśli właściwość nie jest ustawiona lub jest przekazywana ['ALL'], wszystkie dostępne pola są zwracane i rozliczane (nie jest to zalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
Tablica types, która określa konkretny typ lub kolekcję typów wymienionych na liście obsługiwanych typów. Jeśli nie określisz typu, zwrócone zostaną wszystkie typy.
bounds to obiekt google.maps.LatLngBounds określający obszar wyszukiwania miejsc. Wyniki są stronnicze, ale nie ograniczają się do miejsc znajdujących się w tych granicach.
strictBounds to właściwość boolean określająca, czy interfejs API może zwracać tylko te miejsca, które znajdują się wyłącznie w regionie określonym przez podaną wartość bounds. Interfejs API nie zwraca wyników spoza tego regionu, nawet jeśli pasują one do danych wejściowych użytkownika.
componentRestrictions może służyć do ograniczania wyników do określonych grup. Obecnie za pomocą componentRestrictions możesz filtrować według maksymalnie 5 krajów. Kraje należy przekazywać w postaci dwuznakowego kodu kraju zgodnego z normą ISO 3166-1 alfa-2. W postaci listy kodów krajów należy przekazać wiele krajów.
Za pomocą parametru placeIdOnly możesz nakazać widżetowi Autocomplete pobieranie tylko identyfikatorów miejsc. Po wywołaniu getPlace() w obiekcie Autocomplete udostępniony PlaceResult będzie miał ustawione tylko właściwości place id, types i name. Zwróconego identyfikatora miejsca możesz używać w połączeniach z usługami Miejsca, Geokodowanie, Wskazówki dojazdu lub Macierz odległości.
Ograniczanie podpowiedzi autouzupełniania
Domyślnie autouzupełnianie miejsc prezentuje wszystkie typy miejsc na podstawie prognoz dotyczących lokalizacji użytkownika oraz pobiera wszystkie dostępne pola danych dotyczące wybranego miejsca. Ustaw opcje autouzupełniania miejsc, aby wyświetlać trafniejsze podpowiedzi na podstawie Twojego przypadku użycia.
Ustaw opcje na etapie budowy
Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, aby ustawić ograniczenia podczas tworzenia widżetu. W poniższym przykładzie ustawione są opcje bounds, componentRestrictions i types, które żądają miejsc typu establishment, preferując te znajdujące się na określonym obszarze geograficznym i ograniczając prognozy tylko do miejsc w Stanach Zjednoczonych. Ustawienie opcji fields określa, jakie informacje o wybranym miejscu przez użytkownika mają być zwracane.
Wywołaj setOptions(), aby zmienić wartość opcji dla istniejącego widżetu.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
Określ pola danych, by uniknąć opłat za kody SKU danych Miejsc, których nie potrzebujesz. Umieść w obiekcie AutocompleteOptions właściwość fields, która jest przekazywana do konstruktora widżetu, jak pokazano w poprzednim przykładzie, lub wywołaj setFields() w istniejącym obiekcie Autocomplete.
Użyj opcji types lub wywołaj setTypes(), aby ograniczyć prognozy do określonych typów miejsc. To ograniczenie określa typ lub kolekcję typów wymienionych w sekcji Typy miejsc.
Jeśli nie podasz ograniczenia, zwracane będą wszystkie typy.
W przypadku wartości opcji types lub wartości przekazanej do setTypes() możesz określić:
Gdy użytkownik wybierze miejsce z podpowiedzi dołączonych do pola tekstowego autouzupełniania, usługa uruchomi zdarzenie place_changed. Aby uzyskać szczegółowe informacje o miejscu:
Utwórz moduł obsługi zdarzeń place_changed i wywołaj addListener() w obiekcie Autocomplete, aby go dodać.
Wywołaj Autocomplete.getPlace() w obiekcie Autocomplete, aby pobrać obiekt PlaceResult, którego możesz potem użyć, aby uzyskać więcej informacji o wybranym miejscu.
Domyślnie, gdy użytkownik wybierze miejsce, autouzupełnianie zwraca wszystkie dostępne pola danych dotyczące wybranego miejsca, a Twoje konto jest odpowiednio rozliczane.
Aby określić, które pola danych miejsca mają zostać zwrócone, użyj funkcji Autocomplete.setFields(). Dowiedz się więcej o obiekcie PlaceResult, w tym o liście pól danych miejsc, o które możesz poprosić. Aby uniknąć płacenia za niepotrzebne dane, użyj funkcji Autocomplete.setFields() do określenia tylko tych danych o miejscach, których będziesz używać.
Właściwość name zawiera description z podpowiedzi autouzupełniania Miejsc. Więcej informacji o funkcji description znajdziesz w dokumentacji autouzupełniania Miejsc.
W przypadku formularzy adresowych przydatne jest uzyskanie adresu w formacie strukturalnym. Aby zwrócić uporządkowany adres dla wybranego miejsca, wywołaj Autocomplete.setFields() i określ pole address_components.
Poniższy przykład pokazuje użycie autouzupełniania do wypełniania pól w formularzu adresowym.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
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;
Pole tekstowe utworzone przez usługę autouzupełniania domyślnie zawiera standardowy tekst zastępczy. Aby zmodyfikować tekst, ustaw atrybut placeholder w elemencie input:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Uwaga: domyślny tekst zastępczy jest lokalizowany automatycznie. Jeśli określisz własną wartość zmiennej, musisz ją zlokalizować w swojej aplikacji. Informacje o tym, jak interfejs Google Maps JavaScript API wybiera język do użycia, znajdziesz w dokumentacji dotyczącej
lokalizacji.
SearchBox umożliwia użytkownikom przeprowadzanie wyszukiwania geograficznego, np. „pizza w Krakowie” lub „sklepy z obuwiem w pobliżu Mokotów”.
Możesz dołączyć SearchBox do pola tekstowego, a po wpisaniu tekstu usługa będzie zwracać prognozy w postaci listy wyboru.
SearchBox udostępnia rozszerzoną listę podpowiedzi, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wprowadzi hasło „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie”, a także nazwy różnych pizzerii. Gdy użytkownik wybierze miejsce z listy, informacje o nim są zwracane do obiektu SearchBox i mogą być pobierane przez aplikację.
Konstruktor SearchBox przyjmuje 2 argumenty:
Element HTML input typu text. Jest to pole do wprowadzania danych, które będzie monitorować usługa SearchBox i do którego dołącza swoje wyniki.
Argument options, który może zawierać właściwość bounds: bounds to obiekt google.maps.LatLngBounds określający obszar, w którym wyszukiwane są miejsca. Wyniki są stronnicze, ale nie ograniczają się do miejsc znajdujących się w tych granicach.
W poniższym kodzie użyto parametru granic do odchylenia wyników pod kątem miejsc w konkretnym obszarze geograficznym, który jest określony za pomocą współrzędnych szerokości i długości geograficznej.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
Zmiana obszaru wyszukiwania w polu wyszukiwania
Aby zmienić obszar wyszukiwania dla istniejącego obiektu SearchBox, wywołaj setBounds() w obiekcie SearchBox i przekaż odpowiedni obiekt LatLngBounds.
Gdy użytkownik wybierze element z prognoz załączonych do pola wyszukiwania, usługa wywoła zdarzenie places_changed. Możesz wywołać getPlaces() w obiekcie SearchBox, aby pobrać tablicę zawierającą kilka prognoz, z których każde jest obiektem PlaceResult.
// 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);
});
// 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);
});
Aby pobierać prognozy programowo, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego zwraca tablicę obiektów prognoz, z których każdy zawiera tekst prognozy, informacje referencyjne oraz szczegóły dotyczące tego, jak wynik pasuje do danych wejściowych użytkownika.
Jest to przydatne, gdy chcesz mieć większą kontrolę nad interfejsem w stosunku do opisanych powyżej metod Autocomplete i SearchBox.
AutocompleteService udostępnia te metody:
getPlacePredictions() zwraca przewidywane miejsca.
Uwaga: „miejscem” może być instytucja, lokalizacja geograficzna lub ważne ciekawe miejsce określone w interfejsie Places API.
getQueryPredictions() zwraca rozszerzoną listę prognoz, która może obejmować miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wprowadzi hasło „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie”, a także nazwy różnych pizzerii.
distance_meters to odległość w metrach od miejsca od określonej lokalizacji AutocompletionRequest.origin.
matched_substrings zawiera w opisie zestaw podłańcuchów pasujących do elementów wpisanych przez użytkownika. Przydaje się to do wyróżniania tych podłańcuchów w aplikacji. W wielu przypadkach zapytanie pojawi się jako podłańcuch pola opisu.
length to długość podłańcucha.
offset to przesunięcie znaku mierzone od początku ciągu znaków opisu, w którym pojawia się pasujący podłańcuch.
terms to tablica zawierająca elementy zapytania. W przypadku miejsca każdy element stanowi zwykle część adresu.
offset to przesunięcie znaku mierzone od początku ciągu znaków opisu, w którym pojawia się pasujący podłańcuch.
value to pasujący termin.
Poniższy przykład wykonuje żądanie prognozy zapytania dla wyrażenia „pizza w pobliżu” i wyświetla wynik w postaci listy.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// 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;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the callback to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises.
See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions() używa tokenów sesji do grupowania żądań autouzupełniania na potrzeby płatności. Tokeny sesji grupują fazy zapytania i selekcji użytkownika w ramach autouzupełniania wyszukiwania w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, i kończy, gdy wybiera miejsce. Każda sesja może obejmować wiele zapytań, a następnie wybrać jedno miejsce.
Po zakończeniu sesji token traci ważność. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji
we wszystkich sesjach autouzupełniania. Jeśli pominiesz parametr sessionToken lub użyjesz ponownie tokena sesji, opłata za sesję zostanie naliczona tak, jakby nie został dostarczony żaden token sesji (każde żądanie jest rozliczane osobno).
Za pomocą tego samego tokena sesji możesz wysłać jedno żądanie Place Details (Szczegóły miejsca) w przypadku danego miejsca, które jest wynikiem wywołania metody AutocompleteService.getPlacePredictions().
W takim przypadku żądanie autouzupełniania jest połączone z prośbą o szczegóły miejsca, a połączenie jest płatne jak zwykłe żądanie informacji o miejscu. Automatyczne uzupełnianie żądania
jest bezpłatne.
Pamiętaj, by w każdej nowej sesji przekazywać unikalny token. Użycie tego samego tokena w więcej niż jednej sesji autouzupełniania spowoduje, że te sesje autouzupełniania będą unieważnione, a wszystkie żądania autouzupełniania w nieprawidłowych sesjach będą rozliczane indywidualnie za pomocą kodu SKU autouzupełniania na żądanie. Więcej informacji o tokenach sesji
Poniższy przykład pokazuje, jak utworzyć token sesji, a następnie przekazać go w elemencie AutocompleteService (funkcja displaySuggestions() została pominięta ze względu na długość):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
Pamiętaj, by w każdej nowej sesji przekazywać unikalny token. Używanie tego samego tokena w więcej niż 1 sesji sprawia, że każde żądanie jest rozliczane osobno.
Zmienianie stylu widżetów autouzupełniania i SearchBox
Domyślnie elementy interfejsu udostępniane przez Autocomplete i SearchBox są dostosowane do umieszczenia na mapie Google. Możesz dostosować styl do swojej witryny. Dostępne są poniższe klasy CSS. Wszystkie klasy wymienione poniżej dotyczą zarówno widżetów Autocomplete, jak i SearchBox.
Klasy CSS dla widżetów autouzupełniania i SearchBox
Klasa CSS
Opis
pac-container
Element wizualny zawierający listę prognoz zwracanych przez usługę autouzupełniania miejsc. Ta lista ma postać menu pod widżetem Autocomplete lub SearchBox.
pac-icon
Ikona wyświetlana po lewej stronie każdego elementu na liście prognoz.
pac-item
Element na liście prognoz dostarczanych przez widżet Autocomplete lub SearchBox.
pac-item:hover
Element, gdy użytkownik najedzie na niego kursorem myszy.
pac-item-selected
Element wybrany po wybraniu przez użytkownika na klawiaturze. Uwaga: wybrane elementy będą należeć do tej klasy i klasy pac-item.
pac-item-query
Rozpiętość wewnątrz elementu pac-item, który jest główną częścią prognozy. W przypadku lokalizacji geograficznych jest to nazwa miejsca, np. „Gdańsk”, lub nazwa ulicy i numer domu, np. „ul. 10 Kraków”. W przypadku wyszukiwań tekstowych, np. „pizza w Krakowie”, zawiera on pełny tekst zapytania. Domyślnie pac-item-query jest w kolorze czarnym. Jeśli pac-item zawiera dodatkowy tekst, znajduje się on poza domeną pac-item-query i dziedziczy jej styl z pac-item. Domyślnie jest on szary. Dodatkowy tekst to zwykle adres.
pac-matched
Część zwróconej prognozy, która pasuje do danych wejściowych użytkownika. Domyślnie dopasowany tekst jest pogrubiony. Pamiętaj, że pasujący tekst może znajdować się w dowolnym miejscu w obrębie zakresu pac-item. Nie musi być częścią elementu pac-item-query. Może znajdować się częściowo w elemencie pac-item-query, a częściowo w pozostałym tekście w języku pac-item.
Optymalizacja autouzupełniania miejsc
W tej sekcji znajdziesz opis sprawdzonych metod, które pomogą Ci w pełni wykorzystać możliwości usługi autouzupełniania miejsc.
Opanuj od samego początku najważniejsze pola danych autouzupełniania miejsc.
Pola promowania lokalizacji i ograniczeń dotyczących lokalizacji są opcjonalne, ale mogą mieć znaczny wpływ na wydajność autouzupełniania.
Obsługuj błędy, aby zadbać o płynne działanie aplikacji, gdy interfejs API zwróci błąd.
Sprawdź, czy aplikacja obsługuje, gdy nie ma możliwości wyboru, i zapewni użytkownikom możliwość kontynuowania.
Sprawdzone metody optymalizacji kosztów
Podstawowa optymalizacja kosztów
Aby zoptymalizować koszty korzystania z usługi autouzupełniania miejsc, użyj masek pól w szczegółach miejsca i widżetów autouzupełniania miejsc, aby zwracać tylko te pola danych miejsc, których potrzebujesz.
Zaawansowana optymalizacja kosztów
Rozważ automatyczną implementację autouzupełniania miejsca, aby mieć dostęp do cen według żądania i wysyłać żądania wyników interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca. Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej ekonomiczne niż ceny na sesję (ustalane na podstawie sesji), jeśli są spełnione oba te warunki:
Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego przez użytkownika, interfejs Geocoding API dostarcza te informacje do wartości krótszych niż wywołanie szczegółów miejsca.
Jeśli użytkownicy wybiorą prognozę autouzupełniania nie więcej niż cztery żądania, model cenowy na żądanie może być bardziej opłacalny niż model cenowy na sesję.
Aby uzyskać pomoc przy wyborze implementacji autouzupełniania miejsc, która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą Twojej odpowiedzi na poniższe pytanie.
Czy Twoja aplikacja wymaga podania innych informacji niż adres i szerokość/długość geograficzna wybranej prognozy?
Dodaj do implementacji autouzupełniania miejsc ograniczenia związane z krajem, promowaniem lokalizacji i ustawienia języka (w przypadku implementacji zautomatyzowanych). Widżety nie wymagają wyboru języka, ponieważ są one wybierane w przeglądarce lub na urządzeniu mobilnym użytkownika.
Jeśli autouzupełnianie miejsc towarzyszy mapie, możesz odchylać lokalizację według widocznego obszaru mapy.
Jeśli użytkownik nie wybierze jednego z podpowiedzi autouzupełniania, zwykle dlatego, że żadne z nich nie jest pożądanym adresem wyniku, możesz ponownie wykorzystać pierwotne dane wejściowe, aby uzyskać trafniejsze wyniki:
Jeśli oczekujesz, że użytkownik będzie podawać tylko informacje adresowe, użyj tych samych danych w wywołaniu Geocoding API.
Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytanie o konkretne miejsce, podając jego nazwę lub adres, skorzystaj z funkcji Znajdź prośbę o miejsce.
Jeśli wyniki są oczekiwane tylko w konkretnym regionie, użyj promowania lokalizacji.
Inne scenariusze, w których warto wrócić do interfejsu Geocoding API, to między innymi:
Użytkownicy podający adresy podrzędne w krajach, w których autouzupełnianie miejsc nie obsługuje adresów podrzędnych, np. w Czechach, Estonii i Litwie. Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściowe podpowiedzi w funkcji autouzupełniania miejsc.
Użytkownicy wpisują adresy z prefiksem segmentu drogi, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawai.
