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. Zgodnie z definicją w interfejsie Places API „miejscem” może być instytucja, lokalizacja geograficzna lub ważne miejsce.
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.
Aby wyświetlić listę włączonych interfejsów API:
- Otwórz Google Cloud Console.
- 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:
<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ż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. -
SearchBox
dodaje do strony internetowej pole tekstowe w podobny sposób jakAutocomplete
. 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 elementLatLngBounds
. 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.
- Główną różnicą są wyniki wyświetlane na liście wyboru.
- Aby automatycznie pobierać prognozy, możesz utworzyć obiekt
AutocompleteService
. Zadzwoń pod numergetPlacePredictions()
, aby pobrać pasujące miejsca, lub zadzwoń pod numergetQueryPredictions()
, 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
typutext
. 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 odpowiedziPlace Details
dla wybranego przez użytkownika polaPlaceResult
. 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 sekcjiPlaceResult
. - 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 obiektgoogle.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 typboolean
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.Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używany jest kod zawierający określone kraje, terytoria zależne i specjalne obszary geograficzne. Informacje o kodzie znajdziesz na stronie Wikipedia: lista kodów krajów w formacie ISO 3166 lub na platformie przeglądania ISO do przeglądania internetu.
placeIdOnly
może służyć do instruowania widżetuAutocomplete
, by pobierał tylko identyfikatory miejsc. Po wywołaniu funkcjigetPlace()
w obiekcieAutocomplete
udostępnionyPlaceResult
będzie miał ustawione tylko właściwościplace id
,types
iname
. Zwróconego identyfikatora miejsca możesz używać w wywołaniach usług Places, Geocoding, Directions and Range Matrix.
- Tablica danych
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);
JavaScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
Określ pola danych
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
.
autocomplete.setFields(["place_id", "geometry", "name"]);
Zdefiniuj odchylenia i granice obszarów wyszukiwania na potrzeby autouzupełniania
Możesz uchylić wyniki autouzupełniania, aby preferować przybliżoną lokalizację lub obszar. Oto możliwe sposoby:
- Wyznacz granice podczas tworzenia obiektu
Autocomplete
. - Zmień granice istniejącego obiektu
Autocomplete
. - Ustaw granice widocznego obszaru mapy.
- Ogranicz wyszukiwanie do granic.
- Ograniczyć wyszukiwanie do konkretnego kraju.
W poprzednim przykładzie pokazaliśmy granice podczas tworzenia konta. Poniższe przykłady pokazują inne techniki promowania wyników.
Zmiana granic istniejącego autouzupełniania
Wywołaj setBounds()
, aby zmienić obszar wyszukiwania w istniejącym elemencie Autocomplete
na prostokątne granice.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Ustaw granice widocznego obszaru mapy
Korzystając z funkcji bindTo()
, możesz wyświetlać wyniki zgodnie z widocznym obszarem mapy, nawet jeśli ten widoczny obszar się zmienia.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Użyj klawisza unbind()
, aby usunąć powiązanie podpowiedzi autouzupełniania z widocznym obszarem mapy.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Ogranicz wyszukiwanie do bieżących granic
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.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Ogranicz typy miejsc
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ć:
Tablica zawierająca maksymalnie 5 wartości z tabeli 1 lub tabeli 2 z typów miejsc. Na przykład:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Lub:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Każdy filtr w tabeli 3 z sekcji Typy miejsc. Możesz podać tylko jedną wartość z tabeli 3.
Prośba zostanie odrzucona, jeśli:
- Możesz określić więcej niż 5 typów.
- Podano nierozpoznane typy.
- Możesz łączyć dowolne typy z tabeli 1 i tabeli 2 z dowolnym filtrem z tabeli 3.
Prezentacja autouzupełniania miejsc pokazuje różnice w przewidywaniach różnych typów miejsc.
Uzyskiwanie informacji o miejscu
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łajaddListener()
w obiekcieAutocomplete
, aby go dodać. - Wywołaj
Autocomplete.getPlace()
w obiekcieAutocomplete
, aby pobrać obiektPlaceResult
, 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(); }
JavaScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
Dostosowywanie tekstu zastępczego
Domyślnie pole tekstowe utworzone przez usługę autouzupełniania zawiera standardowy tekst zastępczy. Aby zmodyfikować tekst, ustaw atrybut placeholder
w elemencie input
:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Uwaga: domyślny tekst zastępczy jest lokalizowany automatycznie. Jeśli określisz własną wartość zmiennej, musisz ją zlokalizować w aplikacji. Informacje o tym, jak interfejs Google Maps JavaScript API wybiera język, znajdziesz w dokumentacji dotyczącej lokalizacji.
Aby dowiedzieć się, jak dostosować wygląd widżetu, zobacz Ustawianie stylu widżetów autouzupełniania i pola wyszukiwania.
Dodawanie widżetu SearchBox
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
typutext
. To pole do wprowadzania danych, które usługaSearchBox
będzie monitorować i do niego dołączać swoje wyniki. - Argument
options
, który może zawierać właściwośćbounds
:bounds
to obiektgoogle.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
.
Uzyskiwanie informacji o miejscu
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
.
Więcej informacji o obiekcie PlaceResult
znajdziesz w dokumentacji
wyników ze szczegółami miejsc.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
JavaScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
Aby dowiedzieć się, jak dostosować wygląd widżetu, zobacz Ustawianie stylu widżetów autouzupełniania i pola wyszukiwania.
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.
Obie metody zwracają tablicę obiektów prognoz w tej postaci:
- Dopasowana prognoza:
description
. distance_meters
to odległość od danego miejsca (w metrach) od określonej wartościAutocompletionRequest.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.
place_id
to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w poluplaceId
w żądaniu szczegółów 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 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;
JavaScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
CSS
HTML
<html> <head> <title>Retrieving Autocomplete Predictions</title> <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>
Wypróbuj fragment
Tokeny sesji
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.
Więcej informacji o tokenach sesji
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
.
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.
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.
Oto kilka ogólnych wskazówek:
- Najszybszym sposobem opracowania działającego interfejsu użytkownika jest użycie widżetu autouzupełniania interfejsu Maps JavaScript API, widżetu autouzupełniania w usłudze Places SDK na Androida lub elementu autouzupełniania interfejsu Places SDK dla iOS.
- 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ę.
Czy Twoja aplikacja wymaga podania innych informacji niż adres i szerokość geograficzna wybranej prognozy?
Tak, potrzebuję więcej szczegółów
Użyj autouzupełniania miejsc na podstawie sesji z wykorzystaniem szczegółów miejsca.
Aplikacja wymaga informacji o miejscu, takich jak nazwa miejsca, status firmy lub godziny otwarcia, więc implementacja autouzupełniania miejsc powinna korzystać z tokena sesji (automatycznie lub wbudowanego w widżety JavaScript, Androida bądź iOS). Całkowity koszt to 0, 017 USD za sesję plus odpowiednie kody SKU danych miejsc w zależności od żądanych pól danych miejsc.
Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Androida i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądanie informacji o miejscu w przypadku wybranej prognozy. Pamiętaj o określeniu parametru fields
, aby mieć pewność, że wysyłasz tylko te pola danych miejsc, których potrzebujesz.
Implementacja automatyczna
W przypadku żądań autouzupełniania miejsc używaj tokena sesji. Wysyłając żądanie informacji o miejscu dla wybranej prognozy, podaj te parametry:
- identyfikator miejsca z odpowiedzi autouzupełniania miejsc,
- Token sesji używany w żądaniu autouzupełniania miejsca.
- Parametr
fields
określający pola danych miejsc, których potrzebujesz.
Nie, potrzebna jest tylko lokalizacja i adres
Interfejs Geocoding API może być tańszy niż w przypadku aplikacji Szczegóły miejsca, w zależności od wydajności korzystania z funkcji autouzupełniania. Skuteczność autouzupełniania poszczególnych aplikacji różni się w zależności od tego, co wpisują użytkownicy, gdzie dana aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji wydajności.
Aby odpowiedzieć na to pytanie, sprawdź, ile znaków średnio wpisuje użytkownik, zanim wybierzesz podpowiedź autouzupełniania miejsca w aplikacji.
Czy użytkownicy wybierają średnio 4 podpowiedzi autouzupełniania miejsca w maksymalnie 4 żądaniach?
Tak
Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API dla wybranej prognozy miejsca.
Geocoding API dostarcza adresów i współrzędnych szerokości i długości geograficznej za 0,005 USD za każde żądanie. Wykonanie czterech żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań i wywołania Geocoding API dla prognozy wybranego miejsca wynosi 0,01632 USD, czyli mniej niż 0,017 USD za sesję, czyli 0,017 USD za sesję1.
Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby użytkownicy mogli wyświetlać oczekiwane przez nich podpowiedzi przy użyciu jeszcze mniejszej liczby znaków.
Nie
Użyj autouzupełniania miejsc na podstawie sesji z wykorzystaniem szczegółów miejsca.
Ze względu na to, że średnia liczba żądań, które spodziewasz się wysłać przed wybraniem prognozy autouzupełniania miejsca przez użytkownika, przekracza koszt na sesję, dlatego Twoja implementacja autouzupełniania miejsc powinna używać tokena sesji zarówno w przypadku żądań autouzupełniania miejsc, jak i powiązanych z nimi żądania szczegółów miejsca.Łączny koszt wynosi 0,017 za sesję1.
Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Androida i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądanie informacji o miejscu w przypadku wybranej prognozy. Określ parametr fields
, by mieć pewność, że wysyłasz tylko żądania danych podstawowych.
Implementacja automatyczna
W przypadku żądań autouzupełniania miejsc używaj tokena sesji. Wysyłając żądanie informacji o miejscu dla wybranej prognozy, podaj te parametry:
- identyfikator miejsca z odpowiedzi autouzupełniania miejsc,
- Token sesji używany w żądaniu autouzupełniania miejsca.
- Parametr
fields
określający pola danych podstawowych, takich jak adres i geometria
Rozważ opóźnianie żądań autouzupełniania miejsc
Możesz na przykład opóźnić żądanie autouzupełniania miejsca do momentu, w którym użytkownik wpisze pierwsze 3–4 znaki. Dzięki temu aplikacja będzie wysyłać mniej żądań. Na przykład wysyłanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku przez użytkownika oznacza, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze prognozę, dla której utworzysz jedno żądanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 * 0,00283 USD za autouzupełnianie na żądanie + 0,005 geokodowania)1.
Jeśli opóźnione żądania pozwalają uzyskać średnią wartość żądania zautomatyzowanego poniżej 4, postępuj zgodnie ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania miejsc z użyciem interfejsu Geocoding API. Pamiętaj, że żądania opóźnione mogą być postrzegane jako czas oczekiwania dla użytkowników, którzy mogą oczekiwać podpowiedzi po każdym naciśnięciu klawisza.
Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby użytkownicy mogli otrzymywać oczekiwane przez nich prognozy w mniejszej liczbie znaków.
-
Wymienione tutaj koszty są podane w dolarach amerykańskich. Pełne informacje o cenach znajdziesz na stronie Rozliczenia za Google Maps Platform.
Sprawdzone metody zwiększania skuteczności
Poniższe wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:
- 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.
- 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.
Limity i zasady użytkowania
Limity
Informacje o limitach i cenach znajdziesz w dokumentacji dotyczącej użytkowania i rozliczeń dotyczącej interfejsu Places API.
Zasady
Korzystanie z biblioteki Miejsc Google i interfejsu Maps JavaScript API musi być zgodne z zasadami dotyczącymi interfejsu Places API.