Autouzupełnianie miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Wprowadzenie

Autouzupełnianie to funkcja biblioteki Miejsca w interfejsie Maps JavaScript API. Możesz użyć autouzupełniania, aby umożliwić aplikacjom korzystanie z funkcji wyszukiwania typu „type ahead” w polu wyszukiwania w Mapach Google. Usługa autouzupełniania może dopasowywać całe słowa i podciągi znaków, rozwiązując nazwy miejsc, adresy i kody Plus Code. Aplikacje mogą więc wysyłać zapytania w imionach użytkownika, aby na bieżąco przewidywać nazwy miejsc. 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 interfejsie Maps JavaScript API, upewnij się, że interfejs Places API jest włączony w konsoli Google Cloud w tym samym projekcie, w którym skonfigurowano interfejs Maps JavaScript API.

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

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

Ładowanie biblioteki

Usługa Miejsca to samodzielna biblioteka, oddzielona od głównego kodu Maps JavaScript API. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw ją załadować, używając parametru libraries w adresie URL inicjalizacji interfejsu Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Więcej informacji znajdziesz w artykule Omówienie bibliotek.

Podsumowanie zajęć

Interfejs API udostępnia 2 typy widżetów autouzupełniania, które możesz dodać odpowiednio za pomocą klas Autocomplete i SearchBox. 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 formie listy rozwijanej. Gdy użytkownik wybierze miejsce z listy, informacje o tym miejscu są zwracane do obiektu autouzupełniania i mogą zostać pobrane przez aplikację. Szczegółowe informacje znajdziesz poniżej.
    Pole tekstowe autouzupełniania oraz lista prognoz 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, że na liście do wyboru wyświetlają się wyniki SearchBox udostępnia rozszerzoną listę przewidywań, która może zawierać miejsca (zdefiniowane przez interfejs Places API) oraz sugerowane wyszukiwane hasła. Jeśli na przykład użytkownik wpisze „pizza w nowym”, lista wyboru może zawierać wyrażenie „pizza w Warszawie” oraz nazwy różnych pizzerii.
    • SearchBox ma mniej opcji ograniczania wyszukiwania niż Autocomplete. W pierwszym przypadku możesz skoncentrować wyszukiwanie na określonym LatLngBounds. W tym drugim przypadku możesz ograniczyć wyszukiwanie do konkretnego kraju i konkretnych typów miejsc, a także ustawić granice. Więcej informacji znajdziesz poniżej.
    wypełniony formularz adresowy.
    Ilustracja 3.Pole wyszukiwania z wyszukiwanymi hasłami i podpowiedziami dotyczącymi miejsc
    Szczegółowe informacje znajdziesz poniżej.
  • Możesz utworzyć obiekt AutocompleteService, aby pobierać prognozy programowo. Wywołaj funkcję getPlacePredictions(), aby pobrać pasujące miejsca, lub funkcję getQueryPredictions(), aby pobrać pasujące miejsca oraz sugerowane hasła wyszukiwania. Uwaga: AutocompleteService nie dodaje żadnych elementów interfejsu. Zamiast tego podane wyżej metody zwracają tablicę obiektów prognozy. Każdy obiekt prognozy zawiera tekst prognozy, a także informacje referencyjne i szczegóły dotyczące dopasowania wyniku do danych wejściowych użytkownika. Szczegółowe informacje znajdziesz poniżej.

Dodawanie widżetu autouzupełniania

Widget Autocomplete tworzy pole tekstowe na stronie internetowej, podaje prognozy miejsc w liście wyboru w interfejsie i zwraca szczegóły miejsca w odpowiedzi na żądanie getPlace(). Każdy wpis na liście wyboru odpowiada jednemu miejscu (zdefiniowanemu przez interfejs Places API).

Konstruktor Autocomplete przyjmuje 2 argumenty:

  • Element HTML input typu text. To pole 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óre mają być uwzględnione w odpowiedzi Place Details dla wybranego przez użytkownika PlaceResult. Jeśli właściwość nie jest ustawiona lub jeśli przekazana zostanie wartość ['ALL'], zwracane są wszystkie dostępne pola i obliczane (nie zalecamy tego w przypadku wdrożeń produkcyjnych). Listę pól znajdziesz w sekcji PlaceResult.
    • Tablica types, która określa jawny typ lub zbiór typów wymienionych w obsługiwanych typach. Jeśli nie podasz typu, zwrócone zostaną wszystkie typy.
    • bounds to obiekt google.maps.LatLngBounds określający obszar, w którym mają być wyszukiwane miejsca. Wyniki są zorientowane na miejsca znajdujące się w tych granicach, ale nie są do nich ograniczone.
    • strictBounds to booleanokreślający, czy interfejs API musi zwracać tylko te miejsca, które znajdują się w regionie zdefiniowanym przez dany bounds. Interfejs API nie zwraca wyników spoza tego regionu, nawet jeśli pasują one do danych wejściowych użytkownika.
    • componentRestrictions możesz użyć, aby ograniczyć wyniki do konkretnych grup. Obecnie za pomocą componentRestrictions możesz filtrować według maksymalnie 5 krajów. Kraje muszą być przekazywane jako dwuliterowe kody zgodne ze standardem ISO 3166-1 alfa-2. Wiele krajów należy podać jako listę kodów krajów.

      Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i specjalne obszary o zainteresowaniach geograficznych. Informacje o kodach znajdziesz na Wikipedii: liście kodów ISO 3166 lub na platformie ISO do przeglądania online.

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

Ograniczanie podpowiedzi autouzupełniania

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

Ustawianie opcji podczas tworzenia

Konstruktor Autocomplete 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 SKU danych Places, 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 istniejącym obiekcie Autocomplete.

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

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

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

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

Poprzedni przykład pokazuje ustawienie ograniczeń podczas tworzenia. Poniższe przykłady pokazują inne techniki zniekształcania.

Zmiana zakresów dotychczasowego autouzupełniania

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

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 unbind(), aby odłączyć przewidywania autouzupełniania od widoku 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, czy to na podstawie widocznego obszaru mapy, czy prostokątnych granic.

autocomplete.setOptions({ strictBounds: true });
Ograniczanie prognoz do określonego kraju

Aby ograniczyć autouzupełnianie wyszukiwania do konkretnego zestawu do 5 krajów, użyj opcji componentRestrictions lub zadzwoń pod numer setComponentRestrictions().

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

Ograniczanie typów miejsc

Aby ograniczyć prognozy do określonych typów miejsc, użyj opcji types lub wywołania setTypes(). To ograniczenie określa typ lub kolekcję typów wymienionych w sekcji Typy miejsc. Jeśli nie podasz żadnych ograniczeń, zwrócone zostaną wszystkie typy.

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

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

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

    Lub:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Dowolny filtr w tabeli 3 z typów miejsc. Możesz podać tylko jedną wartość z tabeli 3.

Prośba zostanie odrzucona, jeśli:

  • 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.

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

Otwórz wersję demonstracyjną

Pobieranie informacji o miejscu

Gdy użytkownik wybierze miejsce spośród podpowiedzi dołączonych do pola tekstowego autouzupełniania, usługa uruchamia zdarzenie place_changed. Aby uzyskać szczegóły miejsca:

  1. Utwórz moduł obsługi zdarzenia place_changed i wywołaj metodę addListener() obiektu Autocomplete, aby dodać moduł obsługi.
  2. Wywołaj metodę Autocomplete.getPlace() obiektu Autocomplete, aby pobrać obiekt PlaceResult który może posłużyć do uzyskania dodatkowych informacji o wybranym miejscu.

Domyślnie, gdy użytkownik wybierze miejsce, autouzupełnianie zwraca wszystkie dostępne pola danych o wybranym miejscu. Opłaty będą naliczane odpowiednio. Aby określić, które pola danych o miejscach mają być zwracane, użyj parametru Autocomplete.setFields(). Dowiedz się więcej o obiekcie PlaceResult, w tym o liście pól danych o miejscach, o które możesz poprosić. Aby uniknąć płacenia za dane, których nie potrzebujesz, użyj elementu Autocomplete.setFields(), aby określić tylko te dane o miejscach, których będziesz używać.

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

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

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

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 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 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, przeczytaj artykuł Nadawanie stylu widżetom Autouzupełnianie i wyszukiwania.

SearchBox umożliwia użytkownikom wyszukiwanie tekstowe na podstawie lokalizacji, np. „pizza w Warszawie” lub „sklepy obuwnicze w pobliżu ulicy Robson”. Możesz dołączyć 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 np. użytkownik wpisze „pizza w nowym”, lista wyboru może zawierać wyrażenie „pizza w Warszawie” oraz 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 wejściowe, które usługa SearchBox będzie monitorować i do którego dołączać wyniki.
  • Argument options, który może zawierać właściwość bounds: bounds to obiekt google.maps.LatLngBounds określający obszar, w którym mają być wyszukiwane miejsca. Wyniki są przybliżone do miejsc znajdujących się w tych granicach, ale nie są do nich ograniczone.

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 dla istniejącego obiektu SearchBox, wywołaj funkcję setBounds() obiektu SearchBox i przekaż odpowiedni obiekt LatLngBounds.

Zobacz przykład

Pobieranie informacji o miejscu

Gdy użytkownik wybierze element z podpowiedzi dołączonych do pola wyszukiwania, usługa uruchamia zdarzenie places_changed. Możesz wywołać funkcję getPlaces() obiektu SearchBox, aby pobrać tablicę zawierającą kilka prognoz, z których każda jest obiektem PlaceResult.

Więcej informacji o obiekcie PlaceResult znajdziesz w dokumentacji dotyczącej wyników szczegółowych miejsc.

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, przeczytaj artykuł Nadawanie stylu widżetom Autouzupełnianie i wyszukiwania.

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

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

AutocompleteService udostępnia te metody:

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

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

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

W przykładzie poniżej wykonujemy żądanie prognozy zapytania dotyczące wyrażenia „pizza near” i wyświetlamy wynik na liście.

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()może używać tokenów sesji (jeśli są zaimplementowane) do grupowania żądań autouzupełniania na potrzeby rozliczeń. Na potrzeby rozliczeń tokeny sesji łączą fazy zapytania i wyboru w wyszukiwaniu autouzupełniania w jedną sesję. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi generować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania. Jeśli parametr sessionToken zostanie pominięty lub jeśli token sesji zostanie użyty ponownie, sesja zostanie obciążona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane osobno).

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

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

Ten przykład pokazuje utworzenie tokenu sesji i 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

Nadawanie stylu widżetom Autouzupełnianie i SearchBox

Domyślnie elementy interfejsu użytkownika udostępniane przez Autocomplete i SearchBox są stylizowane pod kątem umieszczenia w mapie Google. Możesz 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 SearchBox
Klasa CSS Opis
pac-container Element wizualny zawierający listę prognoz zwróconych przez usługę 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 dostarczonych 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 wybiera za pomocą klawiatury. Uwaga: wybrane elementy będą należeć do tej klasy i klasy pac-item.
pac-item-query Przedział w pac-item, który jest główną częścią prognozy. W przypadku lokalizacji geograficznej zawiera nazwę miejsca, np. „Sydney”, lub nazwę i numer ulicy, np. „10 ul. Kinga”. W przypadku wyszukiwania tekstowego, np. „pizza w Nowym Jorku”, zawiera on pełny tekst zapytania. Domyślnie pac-item-query jest czarny. Jeśli w elementach pac-item znajduje się dodatkowy tekst, jest on umieszczony poza elementem pac-item-query i dziedziczy styl od elementu pac-item. Domyślnie jest ono zabarwione na szaro. 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 autouzupełniania miejsc

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

Oto kilka ogólnych wskazówek:

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

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi autouzupełniania miejsc, użyj masek pól w widżetach Szczegóły miejsca i Autouzupełnianie miejsc, aby zwracać tylko potrzebne pola z danymi o miejscach.

Zaawansowana optymalizacja kosztów

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

  • Jeśli interesuje Cię tylko szerokość geograficzna, długość geograficzna lub adres wybranego miejsca przez użytkownika, interfejs Geocoding API dostarczy te informacje w mniejszym stopniu niż wywołanie interfejsu PlaceDetails.
  • Jeśli użytkownicy wybierają podpowiedzi autouzupełniania w ramach średnio 4 lub mniej żądań, cena za żądanie może być bardziej opłacalna niż cena za sesję.
Aby wybrać implementację Autouzupełniania miejsc dopasowaną do Twoich potrzeb, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.

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

Tak, potrzebuję więcej informacji

Używanie 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

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 dotyczące miejsc, jak i żądanie informacji o wybranym miejscu. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko pol danych o miejscach, których potrzebujesz.

Wdrażanie automatyczne
Używaj tokenu sesji w żądaniach autouzupełniania miejsc. Gdy żądasz szczegółów miejsca dotyczących wybranej prognozy, uwzględnij te parametry:

  1. Identyfikator miejsca z odpowiedzi na autouzupełnianie miejsc
  2. token sesji użyty w żądaniu autouzupełniania miejsc.
  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 wydajności 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 to pytanie, sprawdź, ile znaków użytkownik wpisze średnio przed wybraniem prognozy Miejsca w aplikacji.

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

Tak

Zaimplementuj automatyczne uzupełnianie nazw miejsc za pomocą kodu, bez tokenów sesji, i wywołaj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Geocoding API dostarcza adresy i współrzędne szerokości i długości geograficznej za 0,005 USD za każde zapytanie. Przesyłanie 4 żądań Place Autocomplete – Per Request kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołania interfejsu Geocoding API dotyczącego wybranego miejsca to 0,01632 USD, co jest niższe niż cena autouzupełniania na sesję, która wynosi 0,017 USD na sesję.1

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

Nie

Używaj autouzupełniania miejsc na podstawie sesji z informacjami o miejscach.
Ponieważ średnia liczba żądań, które według Ciebie użytkownik wykona, zanim wybierze przewidywane wyniki autouzupełniania miejsc, przekracza koszt ustalany na podstawie sesji, implementacja autouzupełniania miejsc powinna używać tokenu sesji zarówno do żądań autouzupełniania miejsc, jak i powiązanych żądań szczegółów miejsca.Oznacza to łączny koszt 0,017 USD na 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 dotyczące szczegółów wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko pól Dane podstawowe.

Wdrażanie automatyczne
Używaj tokenu sesji w żądaniach autouzupełniania miejsc. Gdy żądasz szczegółów miejsca dotyczących wybranej prognozy, uwzględnij te parametry:

  1. Identyfikator miejsca z odpowiedzi na autouzupełnianie 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óźnianie wysyłania żądań do usługi Autocomplete miejsc
Możesz stosować strategie takie jak opóźnianie wysyłania żądań do usługi Autocomplete miejsc do momentu, gdy użytkownik wpisze pierwsze 3 lub 4 znaki, aby Twoja aplikacja wysyłała mniej żądań. Na przykład wysyłanie zapytań do Autocomplete w usłudze Places po wpisaniu przez użytkownika 3 znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze podpowiedź, dla której wysyłasz 1 zapytanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 × 0,00283 USD za każde zapytanie do Autocomplete + 0,005 USD za geokodowanie).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 z instrukcjami dotyczącymi skutecznego korzystania z interfejsu Place Autocomplete API z użyciem interfejsu Geocoding API. Pamiętaj, że opóźnianie żądań może być odbierane przez użytkownika jako opóźnienie przewidywania, ponieważ może on oczekiwać przewidywania 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ą, w mniejszej liczbie znaków.

  1. Koszty podane w tym miejscu są podane w USD. Pełne informacje o cenach znajdziesz na stronie Płatności za korzystanie z Google Maps Platform.

Sprawdzone metody dotyczące wydajności

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

  • Dodaj ograniczenia dotyczące kraju, preferencje dotyczące lokalizacji oraz (w przypadku implementacji programowych) preferencje językowe do implementacji funkcji Autouzupełniania miejsc. W przypadku widżetów nie trzeba podawać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
  • Jeśli autouzupełnianie miejsc jest wyświetlane z mapą, możesz dostosować lokalizację do widoku mapy.
  • Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, ponieważ żadna z nich nie jest pożądanym adresem, możesz ponownie użyć oryginalnego danych wejściowych użytkownika, aby uzyskać bardziej trafne wyniki:
    • Jeśli oczekujesz, że użytkownik poda tylko informacje o adresie, ponownie użyj pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
    • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania znajdowania miejsca. Jeśli wyniki mają być uzyskiwane tylko w konkretnym regionie, użyj ustawienia lokalizacji.
    Inne scenariusze, w których warto użyć interfejsu Geocoding API:
    • Użytkownicy wpisują adresy pomieszczeń w budynku, np. adresy konkretnych lokali lub apartamentów. Na przykład czeski adres „Stroupežnického 3191/17, Praha” daje częściową podpowiedź w autouzupełnianiu adresów.
    • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Limity i zasady dotyczące wykorzystania

Limity

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

Zasady

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