Nowy styl mapy będzie wkrótce dostępny w Google Maps Platform. Ta aktualizacja stylu mapy obejmuje nową domyślną paletę kolorów oraz ulepszenia ułatwiające obsługę i łatwość obsługi map. Wszystkie style mapy zostaną automatycznie zaktualizowane w marcu 2025 r. Więcej informacji o dostępności i sposobie włączania tej funkcji znajdziesz w artykule Nowy styl mapy w Google Maps Platform.
Na tej stronie opisujemy bibliotekę po stronie klienta dostępną w ramach interfejsu Maps JavaScript API. Jeśli chcesz pracować z usługą internetową interfejsu Places API na swoim serwerze, 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 oraz Go klienta 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ą korzystać z funkcji wyszukiwania z wyprzedzeniem, dostępnej w polu wyszukiwania Map Google.
Usługa autouzupełniania może dopasowywać pełne słowa i podłańcuchy, rozpoznając nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania jako typ użytkownika, aby generować prognozy dotyczące miejsc w czasie rzeczywistym.
Wprowadzenie
Zanim użyjesz biblioteki Places 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 na potrzeby Maps JavaScript API.
Kliknij przycisk Wybierz projekt, wybierz ten sam projekt, który został skonfigurowany na potrzeby interfejsu Maps JavaScript API, a następnie kliknij Otwórz.
Na liście interfejsów API w panelu znajdź Places API.
Jeśli widzisz ten interfejs API na liście, wszystko jest gotowe. Jeśli interfejsu API nie ma na liście, włącz go:
U góry strony wybierz WŁĄCZ API, aby wyświetlić kartę Biblioteka. Możesz też wybrać opcję 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 to biblioteka samodzielna, niezależna od głównego kodu interfejsu Maps JavaScript API. Aby korzystać z funkcji zawartych w tej bibliotece, musisz ją najpierw wczytać za pomocą parametru libraries w adresie URL wczytywania interfejsu API Map Google:
Interfejs API udostępnia 2 typy widżetów autouzupełniania, które można dodawać odpowiednio za pomocą klas Autocomplete i SearchBox.
Możesz też użyć klasy AutocompleteService do automatycznego pobierania wyników autouzupełniania (zobacz dokumentację interfejsu Maps JavaScript API: klasa AutocompleteService).
Poniżej znajduje się podsumowanie dostępnych zajęć:
Autocomplete dodaje do strony internetowej pole tekstowe i monitoruje je 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 może je pobrać aplikacja. Więcej informacji 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 w podobny sposób jak Autocomplete. Różnice są następujące:
Główną różnicą są wyniki wyświetlane 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 wpisze „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie” oraz nazwy różnych pizzerii.
SearchBox oferuje mniej opcji ograniczania wyszukiwania niż Autocomplete. W pierwszym możesz ukierunkować wyszukiwanie na dany element LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do konkretnego kraju i konkretnych typów miejsc, a także określić granice. Więcej informacji znajdziesz poniżej.
Rys. 3: Pole SearchBox przedstawia wyszukiwane hasła i przewidywane miejsca.Szczegółowe informacje znajdziesz poniżej.
Aby automatycznie pobierać prognozy, możesz utworzyć obiekt AutocompleteService. Zadzwoń pod numer getPlacePredictions(), aby pobrać pasujące miejsca, lub zadzwoń pod numer getQueryPredictions(), aby pobrać pasujące miejsca oraz sugerowane zapytania.
Uwaga: AutocompleteService nie dodaje żadnych opcji 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ół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 na stronie internetowej pole do wprowadzania tekstu, dostarcza prognozy miejsc na liście wyboru elementów i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każda pozycja na liście wyboru odpowiada jednemu miejscu (zgodnie z definicją w interfejsie Places API).
Konstruktor Autocomplete przyjmuje 2 argumenty:
Element HTML input typu text. Jest to pole do wprowadzania danych, które usługa autouzupełniania będzie monitorować i dołączać do niego swoje wyniki.
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 przez użytkownika pola PlaceResult. Jeśli właściwość nie jest ustawiona lub jest przekazywana instrukcja ['ALL'], zwracane są wszystkie dostępne pola i na nich naliczane są opłaty (nie jest to zalecane w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
Tablica types, która określa jawny typ lub kolekcję typów wymienionych na liście obsługiwanych typów. Jeśli nie określisz typu, zwracane będą wszystkie typy.
bounds to obiekt google.maps.LatLngBounds określający
obszar, na którym chcesz szukać miejsc. Wyniki są stronnicze, ale nie tylko w odniesieniu do miejsc znajdujących się w tych granicach.
strictBounds to typ boolean określający, czy interfejs API musi zwracać tylko te miejsca, które znajdują się bezpośrednio 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.
Za pomocą componentRestrictions można ograniczyć wyniki do określonych grup. Obecnie możesz używać componentRestrictions do filtrowania według maksymalnie 5 krajów. Kraje należy przekazywać jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2. W postaci listy kodów krajów należy przekazać więcej niż jedną liczbę krajów.
placeIdOnly może służyć do instruowania widżetu Autocomplete, by pobierał tylko identyfikatory miejsc. Po wywołaniu funkcji 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 wywołaniach usług Places, Geocoding, Directions and Range Matrix.
Ograniczanie podpowiedzi autouzupełniania
Domyślnie autouzupełnianie miejsc prezentuje wszystkie typy miejsc, bierze pod uwagę prognozy dotyczące lokalizacji użytkownika i pobiera wszystkie dostępne pola danych dotyczące wybranego przez użytkownika miejsca. Ustaw opcje autouzupełniania miejsc, aby wyświetlać trafniejsze prognozy na podstawie swojego przypadku użycia.
Ustaw opcje przy budowie
Konstruktor Autocomplete akceptuje parametr AutocompleteOptions, aby ustawiać ograniczenia podczas tworzenia widżetu. Poniższy przykład ustawia opcje bounds, componentRestrictions i types żądające miejsc typu establishment, preferując miejsca z określonego obszaru geograficznego i ograniczając prognozy tylko do miejsc w Stanach Zjednoczonych. Jeśli ustawisz opcję fields, określ, jakie informacje o wybranym miejscu 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 elemencie 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.
Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących progów, niezależnie od tego, czy zależą one od widocznego obszaru mapy, czy też prostokątnych granic.
autocomplete.setOptions({ strictBounds: true });
Ogranicz prognozy do konkretnego kraju
Użyj opcji componentRestrictions lub wywołaj setComponentRestrictions(), aby ograniczyć wyszukiwanie autouzupełniania do maksymalnie 5 krajów.
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 określono ograniczenia, zwracane są wszystkie typy.
W przypadku wartości opcji types lub wartości przekazanej do setTypes() możesz określić:
Gdy użytkownik wybierze miejsce z prognoz załączonych do pola tekstowego autouzupełniania, usługa uruchomi zdarzenie place_changed. Aby uzyskać szczegóły miejsca:
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 Ty będziesz naliczać odpowiednie opłaty.
Aby określić, które pola danych miejsc mają zostać zwrócone, użyj funkcji Autocomplete.setFields(). Dowiedz się więcej o obiekcie PlaceResult, w tym listę pól danych miejsc, o które możesz poprosić. Aby uniknąć płacenia za niepotrzebne dane, używaj funkcji Autocomplete.setFields() do określania tylko tych danych o miejscach, których będziesz używać.
Właściwość name zawiera description z prognoz autouzupełniania w miejscach. Więcej informacji o właściwości description znajdziesz w dokumentacji autouzupełniania w Miejscach.
W przypadku formularzy adresowych warto uzyskać adres w uporządkowanym formacie. Aby zwrócić ustrukturyzowany adres wybranego miejsca, wywołaj metodę Autocomplete.setFields() i podaj pole address_components.
Poniższy przykład pokazuje użycie autouzupełniania do wypełnienia 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;
Domyślnie pole tekstowe utworzone przez usługę autouzupełniania zawiera standardowy tekst zastępczy. Aby zmodyfikować tekst, ustaw atrybut placeholder w elemencie input:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Uwaga: domyślny tekst zastępczy jest lokalizowany automatycznie. Jeśli określisz własną wartość zmiennej, musisz ją zlokalizować w aplikacji. Informacje o tym, jak interfejs Google Maps JavaScript API wybiera język, znajdziesz w dokumentacji dotyczącej
lokalizacji.
SearchBox umożliwia użytkownikom przeprowadzanie wyszukiwania geograficznego według tekstu, np. „pizza w Krakowie” lub „sklepy obuwnicze w pobliżu Mokotów”.
Możesz dołączyć SearchBox do pola tekstowego, a w miarę wpisywania tekstu usługa będzie zwracać prognozy w formie listy 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 wpisze „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie” oraz nazwy różnych pizzerii. Gdy użytkownik wybierze miejsce z listy, informacje o nim są zwracane do obiektu SearchBox i mogą zostać pobrane przez aplikację.
Konstruktor SearchBox przyjmuje 2 argumenty:
Element HTML input typu text. To pole do wprowadzania danych, które usługa SearchBox będzie monitorować i do niego 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 wyszukiwania miejsc. Wyniki są stronnicze, ale nie tylko w odniesieniu do miejsc znajdujących się w tych granicach.
W poniższym kodzie użyto parametru bounds do uporządkowania wyników względem miejsc na określonym obszarze geograficznym, określonych 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 pola wyszukiwania
Aby zmienić obszar wyszukiwania istniejącego obiektu SearchBox, wywołaj setBounds() w obiekcie SearchBox i przekaż odpowiedni obiekt LatLngBounds.
Gdy użytkownik wybierze element z prognoz dołączonych do pola wyszukiwania, usługa uruchomi zdarzenie places_changed. Możesz wywołać getPlaces() w obiekcie SearchBox, aby pobrać tablicę zawierającą kilka prognoz, z których każda 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);
});
Automatyczne pobieranie prognoz usługi autouzupełniania miejsc
Aby pobierać prognozy automatycznie, użyj klasy AutocompleteService. AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zwraca natomiast tablicę obiektów prognozy, 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, jeśli chcesz mieć większą kontrolę nad interfejsem w stosunku do funkcji Autocomplete i SearchBox opisanych powyżej.
AutocompleteService ujawnia te metody:
Funkcja getPlacePredictions() zwraca przewidywane miejsca.
Uwaga: „miejscem” może być instytucja, lokalizacja geograficzna lub ważne ciekawe miejsce zgodnie z definicją podaną w interfejsie Places API.
getQueryPredictions() zwraca rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją w interfejsie Places API) oraz sugerowane wyszukiwane hasła. Jeśli np. użytkownik wpisze „pizza w nowej”, lista opcji może zawierać wyrażenie „pizza w Krakowie” oraz nazwy różnych pizzerii.
distance_meters to odległość od danego miejsca (w metrach) od określonej wartości AutocompletionRequest.origin.
matched_substrings zawiera zbiór podłańcuchów w opisie, które pasują 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 zazwyczaj stanowi 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ące hasło.
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() może używać tokenów sesji (jeśli zostały zaimplementowane) do grupowania żądań autouzupełniania na potrzeby płatności. Tokeny sesji grupują fazy zapytania i wyboru użytkownika autouzupełniania wyszukiwania w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, gdy wybiera miejsce. Każda sesja może obejmować wiele zapytań, z którymi można wybrać tylko 1 miejsce.
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 ponownie użyjesz tokena sesji, opłata za sesję zostanie naliczona tak, jakby nie została podana żadna token sesji (każde żądanie jest rozliczane oddzielnie).
Za pomocą tego samego tokena sesji możesz utworzyć jedno żądanie Place Details (Szczegóły miejsca) w odniesieniu do miejsca, które jest wynikiem wywołania metody AutocompleteService.getPlacePredictions().
W takim przypadku żądanie autouzupełniania zostaje połączone z prośbą o szczegóły miejsca, a za połączenie jest naliczana jak standardowa prośba o szczegóły miejsca. Żądanie autouzupełniania
nie wiąże się z żadnymi opłatami.
Pamiętaj, aby przekazywać unikalny token sesji dla każdej nowej sesji. Używanie tego samego tokena w więcej niż jednej sesji autouzupełniania spowoduje, że te sesje autouzupełniania zostaną unieważnione. Wszystkie żądania autouzupełniania w nieprawidłowych sesjach będą rozliczane indywidualnie za pomocą kodu SKU autouzupełniania według żądania. Więcej informacji o tokenach sesji
Poniższy przykład pokazuje, jak utworzyć token sesji, a następnie przekazać go w 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, aby przekazywać unikalny token sesji dla każdej nowej sesji. Używanie tego samego tokena w więcej niż 1 sesji spowoduje, że każde żądanie będzie rozliczane osobno.
Styl widżetów autouzupełniania i pola wyszukiwania
Domyślnie elementy interfejsu udostępniane przez Autocomplete i SearchBox są skonfigurowane tak, aby można było je uwzględnić w mapie Google. Możesz dostosować styl do swojej witryny. Dostępne są poniższe klasy CSS. Wszystkie wymienione poniżej klasy 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 jest wyświetlana pod widżetem Autocomplete lub SearchBox.
pac-icon
Ikona wyświetlana po lewej stronie każdego elementu na liście prognoz.
pac-item
Pozycja 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 po kliknięciu przez użytkownika na klawiaturze. Uwaga: wybrane elementy będą należeć do tej klasy i klasy pac-item.
pac-item-query
Rozpiętość w elemencie pac-item, który jest główną częścią prognozy. W przypadku lokalizacji geograficznych jest to nazwa miejsca, np. „Gdańsk”, lub nazwa i numer ulicy, np. „ul. Główna 10”. W przypadku wyszukiwań tekstowych, takich jak „pizza w Krakowie”, wyświetlane jest pełne zapytanie. Domyślnie obiekt pac-item-query jest w kolorze czarnym. Jeśli pac-item zawiera dodatkowy tekst, znajduje się on poza polem pac-item-query i dziedziczy jego styl z pac-item. Domyślnym kolorem jest on szary. Dodatkowy tekst to zwykle adres.
pac-matched
Część zwróconej prognozy, która pasuje do danych wejściowych użytkownika. Ten dopasowany tekst jest domyślnie pogrubiony. Pamiętaj, że dopasowany tekst może znajdować się w dowolnym miejscu w obrębie treści pac-item. Nie musi być częścią elementu pac-item-query. Może się znajdować częściowo w elemencie pac-item-query, a częściowo w pozostałym tekście w tagu pac-item.
Korzystanie z komponentu Selektor miejsc
Uwaga: w tym przykładzie korzystamy z biblioteki open source. Otwórz README, aby uzyskać pomoc i opinie dotyczące biblioteki.
Wypróbuj komponenty internetowe. Użyj
komponentu internetowego selektora miejsc, aby włączyć funkcję wpisywania tekstu, która umożliwia użytkownikom wyszukiwanie określonego adresu lub miejsca za pomocą autouzupełniania.
Rys. 1. Wpisywanie tekstu do wyszukania konkretnego adresu lub miejsca za pomocą autouzupełniania
Optymalizacja autouzupełniania miejsc
W tej sekcji opisujemy sprawdzone metody, 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ń lokalizacji są opcjonalne, ale mogą mieć znaczny wpływ na wydajność autouzupełniania.
Użyj obsługi błędów, aby zapewnić płynne działanie aplikacji w przypadku zwrócenia błędu przez interfejs API.
Zadbaj o to, aby aplikacja działała, gdy nie ma możliwości wyboru, i umożliwiała użytkownikom 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 szczegółach miejsca, a widżety autouzupełniania miejsc zwracają tylko potrzebne pola danych miejsc.
Zaawansowana optymalizacja kosztów
Rozważ automatyczną implementację autouzupełniania miejsc, aby uzyskiwać dostęp do cen według żądania i wysyłać żądania wyników z interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca. Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za 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 przez użytkownika, interfejs Geocoding API dostarczy te informacje w czasie krótszym niż wywołanie Place Details.
Jeśli użytkownicy wybiorą podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań prognozy autouzupełniania, model cenowy za żądanie może być bardziej opłacalny niż model cenowy za sesję.
Aby uzyskać pomoc w wyborze implementacji autouzupełniania miejsca pasującej do Twoich potrzeb, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.
Czy Twoja aplikacja wymaga podania innych informacji niż adres i szerokość geograficzna wybranej prognozy?
Dodaj do implementacji autouzupełniania miejsc ograniczenia związane z krajem, promowaniem lokalizacji i (w przypadku implementacji automatycznej) ustawienia języka. Preferencje językowe nie są potrzebne w przypadku widżetów, ponieważ określają one język w przeglądarce lub na urządzeniu mobilnym użytkownika.
Jeśli autouzupełnianiem miejsc towarzyszy mapa, możesz odchylać lokalizację według widocznego obszaru mapy.
Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (zwykle nie jest to adres pożądanego adresu), możesz ponownie użyć pierwotnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
Jeśli oczekujesz, że użytkownik będzie wpisywać tylko informacje adresowe, użyj tych samych danych w wywołaniu interfejsu Geocoding API.
Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca, wpisując jego nazwę lub adres, skorzystaj z prośby o znajdowanie miejsca.
Jeśli wyniki są oczekiwane tylko w konkretnym regionie, użyj promowania lokalizacji.
Inne sytuacje, w których warto wrócić do interfejsu Geocoding API, to m.in.:
Użytkownicy wpisują 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 ramach autouzupełniania miejsc.
Użytkownicy, którzy 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'i.
