Autouzupełnianie miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Wprowadzenie

Autouzupełnianie to funkcja biblioteki Miejsc Maps JavaScript API. Za pomocą autouzupełniania możesz określić, korzysta z funkcji wyszukiwania z wyprzedzeniem w polu wyszukiwania Map Google. Usługa autouzupełniania może dopasowywać całe słowa i podłańcuchy, nazwy miejsc, adresy oraz plus . Dzięki temu aplikacje mogą wysyłać zapytania w miarę wpisywania tekstu przez użytkownika, aby i dostarczają prognozy miejsc na bieżąco. Zgodnie z definicją w usłudze Places API „miejscem” może być lokalizacja geograficzna, punkt widokowy lub punkt zainteresowania.

Pierwsze kroki

Zanim użyjesz biblioteki Miejsca w Maps JavaScript API, upewnij się, w konsoli Google Cloud włączony jest interfejs Places API – projektu skonfigurowanego na potrzeby Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

  1. Przejdź do Konsola Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam skonfigurowany projekt. Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu odszukaj Place API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejsu API nie ma na liście, włącz:
    1. U góry strony kliknij WŁĄCZ INTERFEJS API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybierz opcję Biblioteka.
    2. Wyszukaj Places API, a następnie wybierz go z listy wyników.
    3. Kliknij WŁĄCZ. Po zakończeniu procesu interfejs Places API pojawi się na liście interfejsów API w panelu.

Ładowanie biblioteki

Usługa Miejsca to autonomiczna biblioteka, odrębna od głównej Kod JavaScript API Map Google. Aby korzystać z zawartych w niej funkcji w tej bibliotece, musisz najpierw wczytać ją za pomocą pakietu 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>

Zobacz Omówienie bibliotek, aby dowiedzieć się więcej.

Podsumowanie zajęć

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

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

  • Autocomplete dodaje na stronie internetowej pole tekstowe, które sprawdza, czy użytkownik wpisuje w nim znaki. Gdy użytkownik wpisze tekst, autouzupełnianie zwróci prognozy miejsc w postaci listy rozwijanej. Gdy użytkownik wybierze miejsce z listy, informacje informacje o miejscu są zwracane do obiektu autouzupełniania i można je pobrać przez Twoją aplikację. Szczegółowe informacje znajdziesz poniżej.
    Pole tekstowe autouzupełniania oraz lista prognozowanych miejsc wyświetlana użytkownikowi podczas wpisywania zapytania.
    Rysunek 1. Pole tekstowe i lista do autouzupełniania
    Wypełniony formularz adresowy.
    Rysunek 2. Wypełniony formularz adresowy
  • SearchBox dodaje pole do wprowadzania tekstu na stronie internetowej w podobny sposób do elementu Autocomplete. Różnice są następujące:
    • Główna różnica polega na tym, które pojawią się na liście wyboru. SearchBox – materiały rozszerzoną listę prognoz, która może zawierać miejsca (zgodnie z definicją interfejsu Places API) i sugerowanych wyszukiwanych haseł. Jeśli na przykład użytkownik wpisz „Nowa pizza”, lista wyboru może zawierać wyrażenie „pizza w Krakowie” a także nazwy różnych pizzy gniazdka elektryczne.
    • SearchBox oferuje mniej opcji niż Autocomplete za ograniczenie wyszukiwania. W pierwszym przypadku możesz skoncentrować wyszukiwanie na określonym LatLngBounds. W można ograniczyć wyszukiwanie do konkretnego kraju i typów miejsc i wyznaczać granice. Więcej informacji znajdziesz poniżej.
    .
    Wypełniony formularz adresowy.
    Rysunek 3. Pole wyszukiwania zawiera wyszukiwane hasła i prognozy dotyczące miejsc.
    Szczegółowe informacje znajdziesz poniżej.
  • Możesz utworzyć AutocompleteService obiekt do pobrania w sposób zautomatyzowany. Zadzwoń pod numer getPlacePredictions() do pobierz pasujące miejsca lub zadzwoń pod numer getQueryPredictions(), aby pobrać pasujące miejsca oraz sugerowane wyszukiwane hasła. Uwaga: AutocompleteService nie dodaje żadnych elementów sterujących interfejsu. Zamiast tego powyższe metody zwracają tablicę obiektów prognozowania. Każdy obiekt prognozy zawiera tekst prognozy oraz odwołanie i szczegółowe informacje o tym, jak wynik pasuje do danych wejściowych użytkownika. Zobacz Więcej informacji znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widget Autocomplete tworzy pole tekstowe na stronie internetowej, podaje prognozy miejsc w liście wyboru w interfejsie i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każda pozycja w lista wyboru odpowiada pojedynczemu miejscu (zgodnie z definicją interfejsu Places API).

Konstruktor Autocomplete przyjmuje 2 argumenty:

  • Element HTML input typu text. To pole danych, które usługa automatycznego uzupełniania będzie monitorować i do którego będzie dołączać wyniki.
  • Opcjonalny argument AutocompleteOptions, który może zawierać te właściwości:
    • Tablica danych fields, która ma zostać uwzględniona w odpowiedź Place Details na element PlaceResult wybrany przez użytkownika. Jeśli nie została skonfigurowana lub jeśli przekazano wartość ['ALL'], zwracane są wszystkie dostępne pola i rozliczany dla (niezalecane) w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz tutaj: PlaceResult.
    • Tablica types, która określa jawny typ lub zbiór typów wymienionych w obsługiwanych typach. Jeśli nie określisz typu, wszystkie typy .
    • bounds to obiekt google.maps.LatLngBounds określający obszaru, w którym mają być szukane miejsca. Wyniki są stronnicze, ale nie tylko oraz o miejscach znajdujących się w tych granicach.
    • strictBounds ma status boolean określając, czy interfejs API może zwracać tylko miejsca, które znajdują się ściśle w regionie zdefiniowanym 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 możesz użyć opcji componentRestrictions, by filtrować według maksymalnie 5 krajach. Kraje muszą być przekazywane jako dwuliterowe kody zgodne ze standardem ISO 3166-1 alfa-2. Jako listę kodów krajów należy przekazać wiele krajów.

      Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i specjalne obszary o zainteresowaniach geograficznych. Informacje dotyczące kodu znajdziesz na stronie Wikipedia: lista ISO Kody krajów 3166 lub ISO Online Browsing Platforma.

    • placeIdOnly może służyć do przekazywania widgetowi Autocomplete instrukcji pobierania tylko identyfikatorów miejsc. W trakcie rozmowy getPlace() na obiekcie Autocomplete, PlaceResult będą mieć tylko place id, Ustawiono właściwości types i name. Za pomocą zwróconego identyfikator miejsca z wywołaniami funkcji Miejsca, Geokodowanie, Trasa dojazdu lub Macierz odległości usług Google.

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie miejsc przedstawia wszystkie typy miejsc, stronnicze dla podpowiedzi w pobliżu lokalizację użytkownika i pobiera wszystkie dostępne pola danych dotyczące wybranego przez niego miejsca. Ustaw opcje Autouzupełniania Miejsca, aby wyświetlać trafniejsze przewidywania na podstawie Twojego przypadku użycia.

Ustawianie opcji podczas tworzenia

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

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

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);
index.ts

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);

index.js

Określanie pól danych

Określ pola danych, aby uniknąć opłat za kody SKU danych z Miejsc, których nie potrzebujesz. W komponencie widgeta uwzględnij właściwości fields w komponencie AutocompleteOptions przekazywane do konstruktora widgeta, jak w poprzednim przykładzie, lub wywołaj metodę setFields() w obiekcie Autocomplete.

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

Zdefiniuj uprzedzenia i granice obszarów wyszukiwania dla Autouzupełnianie

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

  • Ustaw granice tworzenia obiektu Autocomplete.
  • Zmień granice w istniejącym obiekcie Autocomplete.
  • Ustaw granice na potrzeby widocznego obszaru mapy.
  • Ogranicz wyszukiwanie do określonych granic.
  • Ograniczyć wyszukiwanie do konkretnego kraju.

Poprzedni przykład pokazuje ustawienie ograniczeń podczas tworzenia. Poniższe przykłady obrazują inne techniki promowania.

Zmiana granic istniejącej funkcji autouzupełniania

Zadzwoń pod numer setBounds(), aby zmienić obszar wyszukiwania w istniejącej Autocomplete do prostokątnych granic.

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);
index.ts

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);

index.js
Ustaw granice na widoczny obszar mapy.

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

TypeScript

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

JavaScript

autocomplete.bindTo("bounds", map);

index.js

Użyj narzędzia 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 });
index.ts

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

Zobacz przykład

Ogranicz wyszukiwanie do bieżących granic

Ustaw opcję strictBounds, aby ograniczyć wyniki do bieżących granic, zarówno na podstawie widocznego obszaru mapy, jak i prostokątnych granic.

autocomplete.setOptions({ strictBounds: true });
Ograniczanie prognoz do konkretnego kraju

Użyj opcji componentRestrictions lub zadzwoń pod numer setComponentRestrictions(), aby ograniczyć autouzupełniania do określonego zestawu do pięciu krajów.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

index.js

Zobacz przykład

Typy miejsc ograniczających

Użyj opcji types lub wywołaj setTypes(), aby ograniczyć dla określonych typów miejsc. To ograniczenie określa typ lub kolekcję typów, jak wymienione w sekcji Typy miejsc. Jeśli nie określisz ograniczenia, zwracane są wszystkie typy.

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

  • Tablica zawierająca do 5 wartości z tabeli 1 lub tabeli 2 z Typy miejsc. Na przykład:

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

    Lub:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • dowolny filtr z tabeli 3 w sekcji Typy miejsc. Możesz określić tylko jedną wartość z tabeli 3.

Prośba zostanie odrzucona, jeśli:

  • W sposób nieprawidłowy określasz więcej niż 5 typów.
  • Określasz dowolne nierozpoznane typy.
  • Mieszasz dowolne typy z tabeli 1 lub tabeli 2 z dowolnym filtrem z tabeli 3.

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

Otwórz wersję demonstracyjną

Pobieranie informacji o miejscu

Gdy użytkownik wybierze miejsce z podpowiedzi dołączonych do autouzupełniania. polu tekstowym, usługa uruchamia zdarzenie place_changed. Aby uzyskać szczegółowe informacje o miejscu:

  1. Utwórz moduł obsługi zdarzeń dla zdarzenia place_changed i wywołaj funkcję addListener() na obiekcie Autocomplete, aby dodać moduł obsługi.
  2. Wywołaj metodę Autocomplete.getPlace() obiektu Autocomplete, aby pobrać obiekt PlaceResult, którego możesz 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 dla wybranego miejsca. Opłaty będą naliczane odpowiednio. Użyj formatu Autocomplete.setFields() w celu określenia pól danych dotyczących miejsc, które mają być zwracane. Dowiedz się więcej o obiekcie PlaceResult, w tym o liście pól danych o miejscach, o które możesz poprosić. Aby uniknąć płacenia za dane, których nie potrzebujesz, użyj parametru Autocomplete.setFields(), aby określić tylko dane o miejscu, których będziesz używać.

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

W przypadku formularzy adresowych warto uzyskać adres w ustrukturyzowanym formacie. Do zwraca uporządkowany adres dla wybranego miejsca, wywołaj Autocomplete.setFields() i podaj pole address_components.

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

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();
}
index.ts

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;

index.js

Zobacz przykład

Dostosowywanie tekstu zastępczego

Domyślnie pole tekstowe utworzone przez usługę autouzupełniania zawiera standardowy tekst zastępczynny. Aby go zmodyfikować, ustaw parametr Atrybut placeholder w elemencie input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Uwaga: domyślny tekst zastępczy jest tłumaczony automatycznie. Jeśli określisz własną wartość symbolu zastępczego, musisz samodzielnie zadbać o jej lokalizowanie w aplikacji. Informacje o tym, jak interfejs Maps JavaScript API wybiera język, znajdziesz w dokumentacji dotyczącej lokalizacji.

Aby dostosować wygląd widżetu, zobacz Zmienianie stylu widżetów Autouzupełnianie i Pole wyszukiwania.

SearchBox umożliwia użytkownikom wykonanie tekstowych działań geograficznych wyszukiwanie, na przykład „pizza w Krakowie” lub „sklep obuwniczy w pobliżu ronda”. Możesz dołączyć funkcję SearchBox do pola tekstowego, a w miarę wpisywania tekstu usługa będzie zwracać prognozy w postaci listy rozwijanej.

SearchBox udostępnia rozszerzoną listę przewidywań, która może zawierać miejsca (zdefiniowane przez interfejs Places API) oraz sugerowane wyszukiwane hasła. Jeśli na przykład użytkownik wpisze „Nowa pizza”, lista wyboru może Umieścić wyrażenie „pizza w Krakowie” a także nazwy różnych pizzerii. Gdy użytkownik wybierze miejsce z listy, informacje o tym miejscu zostaną zwrócone do obiektu SearchBox i będą dostępne dla aplikacji.

Konstruktor SearchBox przyjmuje 2 argumenty:

  • Element HTML input typu text. To jest pole do wprowadzania danych, które usługa SearchBox będzie monitorować, i dołączaj do niego jej wyniki.
  • Argument options, który może zawierać Właściwość bounds: bounds ma status google.maps.LatLngBounds określający obszar, na którym mają być szukane miejsca. Wyniki są przybliżone do miejsc znajdujących się w tych granicach, ale nie są do nich ograniczone.

Poniższy kod używa parametru granice, aby kierować wyniki w stronę miejsc w określonym obszarze geograficznym, określonym za pomocą współrzędnych geograficznych.

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 SearchBox

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

Zobacz przykład

Pobieranie informacji o miejscu

Gdy użytkownik wybierze element z podpowiedzi powiązanych z wyszukiwaniem usługa uruchamia zdarzenie places_changed. Dostępne opcje wywołaj funkcję getPlaces() w obiekcie SearchBox, aby pobrania tablicy zawierającej kilka prognoz, z których każda jest PlaceResult obiekt.

Więcej informacji o obiekcie PlaceResult znajdziesz w dokumentacji dotyczącej wyników szczegółowych 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);
});
index.ts

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);
});
index.js

Zobacz przykład

Aby dostosować wygląd widżetu, zobacz Zmienianie stylu widżetów Autouzupełnianie i Pole wyszukiwania.

Automatyczne pobieranie podpowiedzi usługi autouzupełniania miejsc

Aby pobierać prognozy programowo, użyj klasy AutocompleteService. AutocompleteServicenie dodaje żadnych elementów sterujących interfejsem. Zamiast tego zwraca tablicę prognozy obiekty, z których każdy zawiera tekst prognozy, informacje o odwołaniach i szczegółowe informacje o tym, jak wynik pasuje do danych wejściowych użytkownika. Jest to przydatne, jeśli chcesz mieć większą kontrolę nad interfejsem użytkownika niż zapewniają to opcje Autocomplete i SearchBox opisane powyżej.

AutocompleteService udostępnia te metody:

  • getPlacePredictions() zwraca prognozy dotyczące miejsc. Uwaga: „miejsce” może to być podmiot, położenie geograficzne lub widoczne ciekawe miejsce zdefiniowane w interfejsie Places API.
  • getQueryPredictions() zwraca rozszerzoną listę wartości prognozy, które mogą obejmować miejsca (zgodnie z definicją interfejsu Places API); a także sugerowane zapytania. Jeśli na przykład użytkownik wpisz „Nowa pizza”, lista wyboru może zawierać wyrażenie „pizza w Krakowie” a także nazwy różnych pizzerii.

Obie powyższe metody zwracają tablicę prognoza obiekty o takiej postaci:

  • description to pasująca prognoza.
  • distance_meters to odległość w metrach od miejsca do określonego AutocompletionRequest.origin.
  • matched_substrings zawiera w opisie zbiór podciągów, które pasują do elementów podanych przez użytkownika. Jest to przydatne do wyróżniania tych podciągów w aplikacji. W wielu przypadkach zapytanie będzie widoczne jako podciąg w polu opisu.
    • length to długość podłańcucha.
    • offset to przesunięcie znaku liczone od początku ciągu znaków w opisie, w którym występuje dopasowany podciąg znaków.
  • place_id to identyfikator tekstowy, który jednoznacznie identyfikuje danego miejsca. Aby pobrać informacje o miejscu, prześlij ten identyfikator w polu placeId w prośbie o szczegóły miejsca. Dowiedz się więcej o tym, jak odwoływać się do miejsca za pomocą identyfikatora miejsca.
  • terms to tablica zawierająca elementy zapytania. Dla: danego miejsca, każdy element będzie zwykle stanowił część adresu.
    • offset to przesunięcie znaku mierzone od początek ciągu opisu, w którym dopasowany podłańcuch
    • Pasujące hasło to value.

Poniższy przykład uruchamia żądanie prognozy zapytania dla wyrażenia „pizza w pobliżu” i wyświetli wynik w formie 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;
index.ts

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;
index.js

CSS

style.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>
index.html

Wypróbuj próbkę

Zobacz przykład

Tokeny sesji

AutocompleteService.getPlacePredictions() mogą używać tokenów sesji (jeśli są zaimplementowane) do grupowania żądań autouzupełniania na potrzeby rozliczeń w celach informacyjnych. Tokeny sesji grupują fazy zapytania i wyboru użytkownika w odrębnej sesji autouzupełniania w celach rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik rozpoczyna wpisywanie zapytania, i kończy, gdy użytkownik wybierze miejsce. Każda sesja może zawierać kilka zapytań, a następnie wybrać jedno miejsce. Po zakończeniu sesji token traci ważność. Aplikacja musi generować nowy token na każdą sesję. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania. Jeśli parametr sessionToken ma wartość zostanie pominięta lub jeśli użyjesz tokena sesji ponownie, opłata za sesję zostanie naliczona tak, jakby nie była token sesji (każde żądanie jest rozliczane osobno).

Możesz użyć tego samego tokena sesji, aby utworzyć Szczegóły miejsca w miejscu, które wynika z połączenia z numerem AutocompleteService.getPlacePredictions(). W takim przypadku prośba o autouzupełnianie jest połączona z prośbą o szczegóły miejsca, a za wywołanie usługi zostanie naliczona opłata jak za zwykłą prośbę o szczegóły miejsca. Za o autouzupełnianie.

Pamiętaj, aby w przypadku każdej nowej sesji przekazać unikalny token sesji. Używanie tego samego tokena dla więcej niż jedna sesja autouzupełniania unieważnia te sesje, a wszystkie żądania w nieprawidłowych sesjach będzie naliczana pojedynczo za pomocą funkcji Autouzupełnianie Kod SKU na żądanie. Więcej informacji o tokenach sesji

Ten przykład pokazuje utworzenie tokenu sesji, a następnie przekazanie go w funkcji AutocompleteService (funkcja displaySuggestions() została pominięta ze względu na zwiększenie zwiększenie przejrzystości kodu):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Pamiętaj, aby w przypadku każdej nowej sesji przekazać unikalny token sesji. Użycie tego samego tokena w więcej niż 1 sesji spowoduje, że za każde żądanie zostanie naliczona osobna opłata.

Więcej informacji o tokenach sesji

Wybieranie stylu widżetów autouzupełniania i pola wyszukiwania

Domyślnie elementy interfejsu udostępniane przez usługi Autocomplete i Obiekty SearchBox zostały zaprojektowane tak, by można było uwzględnić je na mapie Google. Więcej informacji aby dostosować styl do swojej witryny. Dostępne są te klasy CSS: Wszystkie klasy wymienione poniżej mają zastosowanie zarówno do widżetów Autocomplete, jak i SearchBox.

Ilustracja przedstawiająca klasy CSS widżetów Autouzupełnianie i SearchBox
Klasy CSS dla widżetów Autouzupełnianie i Wyszukiwarka
Klasa CSS Opis
pac-container Element wizualny zawierający listę prognoz zwróconych przez Usługa autouzupełniania miejsca. Ta lista jest wyświetlana jako lista rozwijana pod widżetem Autocomplete lub SearchBox.
pac-icon Ikona wyświetlana po lewej stronie każdego elementu na liście prognoz.
pac-item Element na liście prognoz dostarczanych przez Widżet Autocomplete lub SearchBox.
pac-item:hover Element, gdy użytkownik najedzie na niego kursorem.
pac-item-selected Element, który użytkownik wybierze za pomocą klawiatury. Uwaga: wybrane elementy będzie członkiem tych zajęć oraz tych, które należą do grupy pac-item.
pac-item-query Przedział w pac-item, który jest główną częścią prognozy. W przypadku lokalizacji geograficznych zawiera ona nazwę miejsca, np. „Gdańsk” lub nazwa ulicy i numer, na przykład „ul. Klejńska 10”. Dla: wyszukiwania tekstowe, takie jak „pizza w Krakowie”, zawiera cały tekst danego zapytania. Domyślnie kolor pac-item-query jest kolorowy. czarnych. Jeśli pac-item zawiera dodatkowy tekst, jest on poza pac-item-query i dziedziczy styl z pac-item Domyślnie jest on w kolorze szarym. Dodatkowy tekst jest zwykle adresem.
pac-matched Część zwróconej prognozy, która pasuje do danych wejściowych użytkownika. Domyślnie dopasowany tekst jest wyróżniony pogrubieniem. Zwróć uwagę, że dopasowany tekst może znajdować się w dowolnym miejscu w pac-item. Nie musi ona znajdować się w sekcji pac-item-query, ale może być częściowo w sekcji pac-item-query, a częściowo w pozostałym tekście w sekcji pac-item.

Optymalizacja miejsca autouzupełniania

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

Oto kilka ogólnych wskazówek:

  • Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest wykorzystanie Maps JavaScript API – widżet autouzupełniania, Widżet autouzupełniania Miejsc Google na Androida, lub pakietu SDK Miejsc dla systemu iOS elementów sterujących w interfejsie autouzupełniania
  • Na początku zaznaj się z najważniejszymi polami danych usługi Autouzupełnianie miejsc.
  • Pola promowania lokalizacji i ograniczenia lokalizacji są opcjonalne, ale mogą mają istotny wpływ na działanie autouzupełniania.
  • Użyj obsługi błędów, aby zapewnić płynne działanie aplikacji, jeśli interfejs API zwróci błąd.
  • Upewnij się, że aplikacja obsługuje przypadki, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Optymalizacja kosztów korzystania z autouzupełniania miejsc należy używać masek pól w widżetach Szczegóły miejsca i autouzupełniania, aby zwracać tylko rozmieść pola danych, których potrzebujesz.

Zaawansowana optymalizacja kosztów

Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen na żądanie i wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca zamiast szczegółów miejsca. Model cenowy za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalny niż model cenowy za sesję (na podstawie sesji), jeśli spełnione są oba te warunki:

  • Jeśli interesuje Cię tylko szerokość geograficzna, długość geograficzna lub adres wybranego miejsca przez użytkownika, interfejs Geocoding API dostarczy te informacje w mniejszym stopniu niż wywołanie interfejsu PlaceDetails.
  • Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w zakresie nie więcej niż 4 żądań podpowiedzi autouzupełniania, model cenowy za żądanie może być bardziej opłacalny niż model płatności za sesję.
. Aby uzyskać pomoc przy wyborze implementacji autouzupełniania miejsc, która odpowiada Twoim potrzebom, wybierz kartę odpowiadającą Twojej odpowiedzi na poniższe pytanie.

Czy aplikacja wymaga innych informacji poza adresem i szerokością geograficzną wybranej prognozy?

Tak, potrzebuję więcej informacji

Używaj autouzupełniania miejsc na podstawie sesji z informacjami o miejscach.
Twoja aplikacja wymaga szczegółów miejsca, takich jak nazwa miejsca, stan firmy lub godziny otwarcia, dlatego implementacja autouzupełniania miejsc powinna używać tokenu sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS), za co płacisz 0,017 USD za sesję plus odpowiedni SKU danych miejsc w zależności od tego, których pól danych miejsc używasz.1

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Android i iOS. Obejmuje to zarówno żądania autouzupełniania miejsca, jak i żądanie informacji o wybranym miejscu. Określ parametr fields, aby mieć pewność, że żądania są wysyłane wyłącznie umieścić w odpowiednim miejscu pola danych.

Implementacja automatyczna
W żądaniach autouzupełniania miejsc używaj tokena sesji. W żądaniu Szczegóły miejsca dotyczące wybranej prognozy podaj te parametry:

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

Nie, potrzebny jest tylko adres i lokalizacja

W zależności od skuteczności korzystania z autouzupełniania miejsc interfejs Geocoding API może być dla Twojej aplikacji bardziej opłacalny niż interfejs Place Details. Skuteczność funkcji Autouzupełnianie w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie jest używana aplikacja i czy zostały zastosowane sprawdzone metody optymalizacji skuteczności.

Aby odpowiedzieć na poniższe pytanie, przed wybraniem podpowiedzi autouzupełniania miejsca w aplikacji sprawdź, ile znaków średnio wpisuje użytkownik.

Czy Twoi użytkownicy wybierają prognozę Miejsca w autouzupełnianiu po 4 lub mniej zapytaniach?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołuj interfejs Geocoding API dla prognozy wybranego miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej za 0,005 USD na żądanie. Utworzenie 4 żądań typu Place Autocomplete – Per Request (Autouzupełnianie – według żądania) kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołania Geocoding API dla wybranej prognozy miejsca wynosi 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję, która wynosi 0,017 USD za sesję1.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać prognozę, której szukają, w jeszcze krótszym formacie.

Nie

Korzystaj z autouzupełniania miejsc opartego na sesji, korzystając z szczegółów miejsca.
Średnia liczba spodziewanych żądań, które zostaną wysłane przed wybraniem podpowiedzi autouzupełniania miejsca, przekracza koszt ceny za sesję. Dlatego Twoja implementacja autouzupełniania miejsc powinna korzystać z tokenu sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań informacji o miejscach. Ich łączny koszt to 0,017 USD za sesję1.

Wdrażanie widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko pól Basic Data.

Implementacja automatyczna
W żądaniach autouzupełniania miejsc używaj tokena sesji. W żądaniu Szczegóły miejsca dotyczące wybranej prognozy podaj te parametry:

  1. Identyfikator miejsca z odpowiedzi na żądanie autouzupełniania miejsc
  2. token sesji użyty w żądaniu autouzupełniania miejsc;
  3. parametr fields określający pola Dane podstawowe, takie jak adres i geometria;

Rozważ opóźnienie prośby o autouzupełnianie miejsc
Aby zmniejszyć liczbę żądań, możesz zastosować strategie, takie jak opóźnienie żądania autouzupełniania miejsca do czasu wpisania przez użytkownika pierwszych trzech lub czterech znaków. Na przykład wykonywanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze prognozę, dla której utworzysz jedno żądanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 * 0,00283 Autouzupełniaj na żądanie + 0,005 USD za kodowanie geograficzne)1.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań programowych będzie niższa niż 4, możesz postępować zgodnie ze wskazówkami dotyczącymi efektywnego korzystania z Autocomplete API z użyciem interfejsu Geocoding API. Pamiętaj, że opóźnianie żądań może być odbierane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać wyświetlania prognoz przy każdym nowym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać prognozę, której szukają, przy użyciu mniejszej liczby znaków.

  1. Koszty podane w tym miejscu są podane w USD. Pełne ceny znajdziesz na stronie płatności za Google Maps Platform.

Sprawdzone metody zwiększania skuteczności

Poniższe wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj ograniczenia dotyczące kraju, preferencje dotyczące lokalizacji oraz (w przypadku implementacji programowych) preferencje językowe do implementacji funkcji Autouzupełniania miejsc. Nie musisz wybierać języka dzięki widżetom, które wybierają język z przeglądarki użytkownika lub urządzenia mobilnego.
  • Jeśli wraz z mapą jest wyświetlana mapa, możesz dostosować lokalizację według widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, ponieważ żadne z tych podpowiedzi nie są pożądanym adresem wynikowym, możesz ponownie użyć oryginalnego adresu dane wejściowe użytkownika, aby uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik poda tylko adres, użyj pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
    • Jeśli spodziewasz się, że użytkownicy będą wpisywać zapytania dotyczące konkretnego miejsca po nazwie lub adresie, skorzystaj z prośby o znajdowanie miejsca. Jeśli oczekiwane wyniki dotyczą tylko konkretnego regionu, użyj funkcji promowanie lokalizacji.
    Inne scenariusze, w których warto użyć interfejsu Geocoding API:
    • Użytkownicy wpisujący adresy podrzędne w krajach, w których autouzupełnianie adresów miejsc jest niepełne, np. w Czechach, Estonii i na Litwie. Na przykład parametr Adres czeski „Stroupežnického 3191/17, Praha” daje częściową prognozę w miejscu Autouzupełnianie.
    • Użytkownicy, którzy wpisują adresy z prefiksami fragmentu drogi, np. „23-30 29th St, Warszawa”. cale New York City lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Limity i zasady dotyczące wykorzystania

Limity

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

Zasady

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