Autouzupełnianie miejsc

Ta strona opisuje bibliotekę po stronie klienta dostępną w Maps JavaScript API. Jeśli chcesz korzystać z interfejsu API Places na swoim serwerze, zapoznaj się z klientami Map Google w Node.js. Na stronie, do której prowadzi ten link, znajdziesz też informacje o kliencie Java, kliencie Python i kliencie Go do usług Map Google.

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ą interfejsu Places API „miejsce” może być obiektem, lokalizacją geograficzną lub ważnym punktem 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 Place 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.

Wczytywanie 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 i sprawdza, czy nie zawiera ono znaków. 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 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 dostępnych opcji wyświetlają się inne 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 geograficzne, które chcesz uwzględnić. Informacje o kodach znajdziesz na Wikipedii: liście kodów ISO 3166 lub na platformie ISO Online Browsing Platform.

    • 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ócony identyfikator miejsca możesz używać w wywołaniach do usług Miejsca, Geokodowania, Wskazówek dojazdu i Matrici 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 przyjmuje 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ą być zwracane.

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

TypeScriptJavaScript
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
 
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, które są przekazywane do konstruktora widgeta, jak w poprzednim przykładzie, lub wywołaj metodę setFields() w istniejącym obiekcie Autocomplete.AutocompleteOptions

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

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

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

index.js

Użyj unbind(), aby odłączyć przewidywania autouzupełniania od widoku mapy.

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

Zobacz przykład

Ogranicz wyszukiwanie do bieżących granic

Aby ograniczyć wyniki do bieżących granic, użyj opcji strictBounds. Możesz to zrobić na podstawie widocznego obszaru mapy lub 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().

TypeScriptJavaScript
autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts
 
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 w typach 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 przypadku 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 z 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 dla wybranego miejsca. 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 miejsc.

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.

TypeScriptJavaScript
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
 
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 lokalizowany 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
});

Zmień obszar wyszukiwania w polu wyszukiwania

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.

TypeScriptJavaScript
// 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
 
// 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 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.

TypeScriptJavaScriptCSSHTML
// 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
 
// 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
 
style.css
 
<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 autouzupełnianiu 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ą obciążone osobno za pomocą SKU autouzupełniania 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

Nadawanie stylu widżetom Autouzupełnianie i Pole wyszukiwania

Domyślnie elementy interfejsu użytkownika udostępniane przez Autocomplete i SearchBox są stylizowane pod kątem wyświetlania na 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 menu pod widżetem Autocomplete lub SearchBox.
pac-icon Ikona wyświetlana po lewej stronie każdego elementu na liście prognoz.
pac-item Element na liście prognoz 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ą przewidywania. 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 kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi autouzupełniania miejsc, użyj masek pól w 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ą prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognozy autouzupełniania, 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 współrzędnych wybranej prognozy?

Tak, potrzebuję więcej informacjiNie, potrzebny jest tylko adres i lokalizacja

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żetach JavaScript, Android lub iOS). Na podstawie sesji oraz odpowiednich 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 adresu, 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, 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 danych o miejscach, których potrzebujesz

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 autouzupełniania Miejsca w aplikacji.

Czy Twoi użytkownicy wybierają prognozę Miejsca w autouzupełnianiu po wykonaniu średnio 4 lub mniej zapytań?

TakNie

Zaimplementuj automatyczne uzupełnianie nazw miejsc za pomocą kodu, bez tokenów sesji, i wywołaj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Interfejs Geocoding API udostępnia adresy oraz współrzędne szerokości i długości geograficznej. Przesyłanie 4 żądań Autouzupełniania miejsc – na żądanie oraz wywołanie interfejsu Geokodowania API dotyczące wybranego miejsca prognozowanego kosztuje mniej niż koszt autouzupełniania na sesję 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.

Używaj autouzupełniania miejsc na podstawie sesji z informacjami o miejscach.
Ponieważ średnia liczba żądań, które użytkownik musi 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 w przypadku żądań autouzupełniania miejsc, jak i powiązanych żądań informacji o miejscach na każdą 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 adresu, jak i żądanie informacji o wybranym miejscu. Pamiętaj, aby określić parametr fields, aby mieć pewność, że wysyłasz żądanie tylko do 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, 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óź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 żądań do Autouzupełniania Miejsca na potrzeby każdego znaku po wpisaniu przez użytkownika trzeciego znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze przewidywany wynik, do którego wysyłasz 1 żądanie interfejsu Geokodowanie API, łączny koszt wyniesie 4 żądania autouzupełniania na żądanie + 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 autouzupełniania miejsc za pomocą 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. Informacje o kosztach znajdziesz w cennikach Google Maps Platform.

Czy te wskazówki były pomocne?

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.
  • Gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, ponieważ żadna z nich nie jest pożądanym adresem, możesz ponownie użyć oryginalnego tekstu wprowadzonego przez 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 miejsc. 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.