Автозаполнение мест

Введение

Автодополнение — это функция библиотеки Places в Maps JavaScript API. Вы можете использовать автодополнение, чтобы реализовать в своих приложениях функцию поиска с опережением ввода, как в поле поиска Google Карт. Служба автодополнения может выполнять поиск по полным словам и подстрокам, определяя названия мест, адреса и плюс-коды . Таким образом, приложения могут отправлять запросы по мере ввода текста пользователем, предоставляя прогнозы местоположений в режиме реального времени. Согласно определению Places API, «местом» может быть учреждение, географическое местоположение или примечательная достопримечательность.

Начиная

Перед использованием библиотеки Places в Maps JavaScript API сначала убедитесь, что Places API включен в консоли Google Cloud в том же проекте, который вы настроили для Maps JavaScript API.

Чтобы просмотреть список включенных API:

1. Перейдите в консоль Google Cloud .
2. Нажмите кнопку Выбрать проект , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите Открыть .
3. В списке API на панели инструментов найдите Places API .
4. Если вы видите API в списке, всё готово. Однако этот проект находится в статусе Legacy. Подробнее о статусе Legacy и о переходе с Legacy на более новые сервисы см. в разделе Legacy products and features . Исключение составляют виджеты Autocomplete и SearchBox , которые пока недоступны в качестве продукта GA в Places API (New).

Загрузить библиотеку

Служба Places — это самостоятельная библиотека, отдельная от основного кода JavaScript API Карт. Чтобы использовать функции этой библиотеки, необходимо сначала загрузить её с помощью параметра libraries в URL-адресе начальной загрузки API Карт:

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

Более подробную информацию см. в Обзоре библиотек .

Краткое содержание занятий

API предлагает два типа виджетов автодополнения, которые можно добавить с помощью классов Autocomplete и SearchBox соответственно. Кроме того, можно использовать класс AutocompleteService для программного получения результатов автодополнения (см. «Справочник по Maps JavaScript API: класс AutocompleteService »).

Ниже приведен краткий обзор доступных классов:

• Autocomplete добавляет поле ввода текста на вашу веб-страницу и отслеживает ввод символов в этом поле. По мере ввода текста пользователем функция автозаполнения выдаёт подсказки мест в виде раскрывающегося списка. Когда пользователь выбирает место из списка, информация о нём возвращается в объект автозаполнения и может быть извлечена вашим приложением. Подробности см. ниже .

  

  

• SearchBox добавляет на вашу веб-страницу поле ввода текста, аналогично функции Autocomplete . Различия заключаются в следующем:
  • Главное отличие заключается в результатах, которые отображаются в списке выбора. SearchBox предоставляет расширенный список подсказок, который может включать места (согласно API Places) и предлагаемые поисковые запросы. Например, если пользователь вводит «пицца в Нью-Йорке», список выбора может включать фразу «пицца в Нью-Йорке», а также названия различных пиццерий.
  • SearchBox предлагает меньше возможностей для ограничения поиска, чем Autocomplete . В первом случае вы можете сузить поиск до заданного значения LatLngBounds . Во втором случае вы можете ограничить поиск конкретной страной и определенными типами мест, а также задать границы. Подробнее см. ниже .

  

  Подробности смотрите ниже .
• Вы можете создать объект AutocompleteService для программного получения подсказок. Вызовите метод getPlacePredictions() для получения соответствующих мест или метод getQueryPredictions() для получения соответствующих мест и предлагаемых поисковых запросов. Примечание: AutocompleteService не добавляет никаких элементов управления пользовательского интерфейса. Вместо этого указанные выше методы возвращают массив объектов подсказок. Каждый объект подсказки содержит текст подсказки, а также справочную информацию и сведения о том, насколько результат соответствует пользовательскому вводу. Подробнее см. ниже .

Добавить виджет автозаполнения

Виджет Autocomplete создаёт поле ввода текста на вашей веб-странице, предоставляет прогнозы мест в списке выбора пользовательского интерфейса и возвращает информацию о месте в ответ на запрос getPlace() . Каждая запись в списке выбора соответствует одному месту (согласно определению API Places).

Конструктор Autocomplete принимает два аргумента:

• HTML-элемент input типа text . Это поле ввода, которое служба автозаполнения будет отслеживать и прикреплять к нему результаты.
• Необязательный аргумент AutocompleteOptions , который может содержать следующие свойства:
  • Массив fields данных, которые будут включены в ответ Place Details для выбранного пользователем PlaceResult . Если свойство не задано или передано ['ALL'] , возвращаются все доступные поля и выставляется счет за них (это не рекомендуется для производственных развёртываний). Список полей см. в PlaceResult .
  • Массив types , который задаёт явный тип или коллекцию типов, как указано в поддерживаемых типах . Если тип не указан, возвращаются все типы.
  • bounds — это объект google.maps.LatLngBounds , задающий область поиска. Результаты поиска смещены в сторону мест, находящихся в этих границах, но не ограничиваются ими.
  • strictBounds — это boolean , указывающее, должен ли API возвращать только те места, которые строго находятся в пределах области, определяемой заданными bounds . API не возвращает результаты за пределами этой области, даже если они соответствуют пользовательскому вводу.
  • С помощью componentRestrictions можно ограничить результаты определёнными группами. С помощью componentRestrictions можно фильтровать результаты по максимум пяти странам. Страны необходимо передавать в виде двухсимвольного кода, совместимого со стандартом ISO 3166-1 Alpha-2. Коды нескольких стран необходимо передавать в виде списка.

    Примечание: Если вы получили неожиданные результаты с кодом страны, убедитесь, что вы используете код, включающий нужные вам страны, зависимые территории и особые географические зоны. Информацию о кодах можно найти в Википедии: Список кодов стран по стандарту ISO 3166 или на платформе онлайн-обзора ISO .

  • С помощью placeIdOnly можно указать виджету Autocomplete получать только идентификаторы мест. При вызове метода getPlace() объекта Autocomplete , доступный PlaceResult будет содержать только place id , types и name . Возвращаемый идентификатор места можно использовать при вызовах служб Places, Geocoding, Directions или Distance Matrix.

Ограничить прогнозы автозаполнения

По умолчанию автозаполнение мест отображает все типы мест, отдавая предпочтение прогнозам, близким к местоположению пользователя, и извлекает все доступные поля данных для выбранного пользователем места. Настройте параметры автозаполнения мест, чтобы отображать более релевантные прогнозы с учетом вашего варианта использования.

Установить параметры при строительстве

Конструктор Autocomplete принимает параметр AutocompleteOptions для установки ограничений при создании виджета. В следующем примере задаются параметры bounds , componentRestrictions и types для запроса мест типа establishment , отдавая предпочтение тем, которые находятся в указанной географической области, и ограничивая подсказки только местами в пределах США. Параметр fields определяет, какую информацию нужно возвращать о выбранном пользователем месте.

Вызовите setOptions() , чтобы изменить значение параметра для существующего виджета.

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

Укажите поля данных

Укажите поля данных, чтобы избежать выставления счетов за ненужные вам артикулы Places Data . Включите свойство fields в AutocompleteOptions , передаваемые конструктору виджета, как показано в предыдущем примере, или вызовите setFields() для существующего объекта Autocomplete .

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

Определите смещения и границы области поиска для автозаполнения

Вы можете изменить результаты автозаполнения, отдав предпочтение приблизительному местоположению или району, следующими способами:

• Установите границы создания объекта Autocomplete .
• Измените границы существующего Autocomplete .
• Установите границы области просмотра карты.
• Ограничить поиск границами.
• Ограничить поиск определенной страной.

Предыдущий пример демонстрирует установку границ при создании. Следующие примеры демонстрируют другие методы смещения.

Изменить границы существующего автозаполнения

Вызовите setBounds() , чтобы изменить область поиска в существующем Autocomplete на прямоугольные границы.

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

Установите границы области просмотра карты

Используйте bindTo() чтобы сместить результаты в соответствии с областью просмотра карты, даже если эта область просмотра изменяется.

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

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

Используйте unbind() для отвязки прогнозов автозаполнения от области просмотра карты.

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

Посмотреть пример

Ограничить поиск текущими границами

Установите параметр strictBounds , чтобы ограничить результаты текущими границами, основанными как на области просмотра карты, так и на прямоугольных границах.

autocomplete.setOptions({ strictBounds: true });

Ограничить прогнозы определенной страной

Используйте параметр componentRestrictions или вызовите setComponentRestrictions() , чтобы ограничить поиск автозаполнения определенным набором из максимум пяти стран.

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

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

Посмотреть пример

Ограничить типы мест

Используйте параметр types или вызовите setTypes() , чтобы ограничить прогнозы определёнными типами мест. Это ограничение задаёт тип или коллекцию типов, как указано в разделе «Типы мест» . Если ограничение не указано, возвращаются все типы.

Для значения параметра types или значения, переданного в setTypes() , вы можете указать одно из следующих значений:

• Массив, содержащий до пяти значений из Таблицы 1 или Таблицы 2 из раздела «Типы мест» . Например:

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

  Или:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• Любой фильтр из Таблицы 3 из Типов мест . Вы можете указать только одно значение из Таблицы 3.

Запрос будет отклонен, если:

• Вы указываете более пяти типов.
• Вы указываете любые нераспознанные типы.
• Вы смешиваете любые типы из Таблицы 1 или Таблицы 2 с любым фильтром из Таблицы 3 .

Демонстрация автозаполнения мест демонстрирует различия в прогнозах для разных типов мест.

Посетите демо

Получение информации о месте

Когда пользователь выбирает место из подсказок, прикреплённых к полю автозаполнения, сервис генерирует событие place_changed . Чтобы получить информацию о месте:

1. Создайте обработчик событий для события place_changed и вызовите addListener() для объекта Autocomplete , чтобы добавить обработчик.
2. Вызовите Autocomplete.getPlace() для объекта Autocomplete , чтобы получить объект PlaceResult , который затем можно использовать для получения дополнительной информации о выбранном месте.

По умолчанию, когда пользователь выбирает место, функция автозаполнения возвращает все доступные поля данных для выбранного места, и с вас будет списана соответствующая сумма . Используйте Autocomplete.setFields() чтобы указать, какие поля данных о месте нужно вернуть. Узнайте больше об объекте PlaceResult , включая список полей данных о месте, которые можно запросить. Чтобы избежать оплаты за ненужные данные, обязательно используйте Autocomplete.setFields() чтобы указать только те данные о месте, которые вы будете использовать.

Свойство name содержит description из подсказок Places Autocomplete. Подробнее об description можно узнать в документации Places Autocomplete .

Для форм адреса полезно получать адрес в структурированном формате. Чтобы получить структурированный адрес выбранного места, вызовите Autocomplete.setFields() и укажите поле address_components .

В следующем примере автозаполнение используется для заполнения полей в форме адреса.

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

Посмотреть пример

Настроить текст-заполнитель

По умолчанию текстовое поле, создаваемое службой автодополнения, содержит стандартный текст-заполнитель. Чтобы изменить текст, установите атрибут placeholder для элемента input :

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

Примечание: текст-заполнитель по умолчанию локализуется автоматически. Если вы указываете собственное значение-заполнитель, вам необходимо настроить локализацию этого значения в вашем приложении. Сведения о том, как JavaScript API Google Карт выбирает используемый язык, см. в документации по локализации .

Информацию о настройке внешнего вида виджета см. в разделе Стилизация виджетов «Автозаполнение» и «SearchBox» .

Добавить виджет SearchBox

SearchBox позволяет пользователям выполнять текстовый географический поиск, например, «пицца в Нью-Йорке» или «обувные магазины рядом с Робсон-стрит». Вы можете прикрепить SearchBox к текстовому полю, и по мере ввода текста сервис будет выдавать подсказки в виде раскрывающегося списка.

SearchBox предоставляет расширенный список подсказок, который может включать места (согласно API Places) и предлагаемые поисковые запросы. Например, если пользователь вводит «пицца в Нью-Йорке», список может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных пиццерий. Когда пользователь выбирает место из списка, информация об этом месте возвращается в объект SearchBox и может быть извлечена вашим приложением.

Конструктор SearchBox принимает два аргумента:

• HTML-элемент input типа text . Это поле ввода, которое служба SearchBox будет отслеживать и прикреплять к нему результаты.
• Аргумент options , который может содержать свойство bounds : bounds — это объект google.maps.LatLngBounds , определяющий область поиска. Результаты смещены в сторону мест, находящихся в этих границах, но не ограничиваются ими.

Следующий код использует параметр bounds для смещения результатов в сторону мест в пределах определенной географической области, указанной с помощью координат широты и долготы.

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

Измените область поиска для SearchBox

Чтобы изменить область поиска для существующего SearchBox , вызовите setBounds() для объекта SearchBox и передайте соответствующий объект LatLngBounds .

Посмотреть пример

Получение информации о месте

Когда пользователь выбирает элемент из подсказок, прикреплённых к полю поиска, сервис генерирует событие places_changed . Вы можете вызвать метод getPlaces() для объекта SearchBox , чтобы получить массив, содержащий несколько подсказок, каждая из которых является объектом PlaceResult .

Дополнительную информацию об объекте PlaceResult см. в документации по результатам описания места .

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
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

Посмотреть пример

Информацию о настройке внешнего вида виджета см. в разделе Стилизация виджетов «Автозаполнение» и «SearchBox» .

Программное получение прогнозов Place Autocomplete Service

Для программного получения подсказок используйте класс AutocompleteService . AutocompleteService не добавляет никаких элементов управления пользовательского интерфейса. Вместо этого он возвращает массив объектов подсказок, каждый из которых содержит текст подсказки, справочную информацию и сведения о соответствии результата пользовательскому вводу. Это полезно, если вам требуется больше контроля над пользовательским интерфейсом, чем предлагают Autocomplete и SearchBox описанные выше.

AutocompleteService предоставляет следующие методы:

• getPlacePredictions() возвращает прогнозы мест. Примечание: «Место» может быть учреждением, географическим объектом или достопримечательностью, как определено в API Places.
• getQueryPredictions() возвращает расширенный список подсказок, который может включать места (согласно API Places) и предлагаемые поисковые запросы. Например, если пользователь вводит «пицца в Нью-Йорке», список может включать фразу «пицца в Нью-Йорке», а также названия различных пиццерий.

Оба вышеприведенных метода возвращают массив объектов прогнозирования следующего вида:

• description — это совпавшее предсказание.
• distance_meters — расстояние в метрах от указанного в AutocompletionRequest.origin места.
• matched_substrings содержит набор подстрок в описании, соответствующих элементам во вводе пользователя. Это полезно для выделения этих подстрок в вашем приложении. Во многих случаях запрос будет отображаться как подстрока поля описания.
  • length — длина подстроки.
  • offset — смещение символа, измеренное от начала строки описания, на котором появляется совпадающая подстрока.
• place_id — это текстовый идентификатор, однозначно определяющий место. Чтобы получить информацию о месте, передайте этот идентификатор в поле placeId запроса Place Details . Узнайте больше о том, как сослаться на место с помощью идентификатора места .
• terms — это массив, содержащий элементы запроса. Для места каждый элемент обычно составляет часть адреса.
  • offset — смещение символа, измеренное от начала строки описания, на котором появляется совпадающая подстрока.
  • value — это соответствующий термин.

В примере ниже выполняется запрос прогнозирования для фразы «пицца рядом» и отображается результат в виде списка.

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

Посмотреть пример

Токены сеанса

AutocompleteService.getPlacePredictions() может использовать токены сеанса (если реализован) для группировки запросов автодополнения для выставления счетов. Токены сеанса объединяют фазы запроса и выбора в отдельный сеанс для выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос, и заканчивается, когда он выбирает место. Каждый сеанс может включать несколько запросов, за которыми следует один выбор места. После завершения сеанса токен становится недействительным. Ваше приложение должно генерировать новый токен для каждого сеанса. Мы рекомендуем использовать токены сеанса для всех сеансов автодополнения. Если параметр sessionToken пропущен или вы повторно используете токен сеанса, сеанс тарифицируется так, как если бы токен сеанса не был предоставлен (каждый запрос тарифицируется отдельно).

Вы можете использовать один и тот же токен сеанса для выполнения одного запроса Place Details для места, полученного в результате вызова AutocompleteService.getPlacePredictions() . В этом случае запрос автодополнения объединяется с запросом Place Details, и вызов тарифицируется как обычный запрос Place Details. Запрос автодополнения бесплатен.

Обязательно передавайте уникальный токен сеанса для каждого нового сеанса. Использование одного и того же токена для нескольких сеансов Autocomplete сделает их недействительными, и все запросы Autocomplete в недействительных сеансах будут оплачиваться индивидуально с использованием кода Autocomplete Per Request . Подробнее о токенах сеансов читайте здесь .

В следующем примере показано создание токена сеанса и его последующая передача в AutocompleteService (функция displaySuggestions() опущена для краткости):

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

Обязательно передавайте уникальный токен сеанса для каждого нового сеанса. Использование одного и того же токена для нескольких сеансов приведёт к тому, что каждый запрос будет оплачиваться отдельно.

Подробнее о токенах сеанса читайте здесь .

Стилизация виджетов «Автозаполнение» и «SearchBox»

По умолчанию элементы пользовательского интерфейса, предоставляемые Autocomplete и SearchBox , стилизованы для отображения на карте Google. Вы можете настроить стили в соответствии с требованиями вашего сайта. Доступны следующие CSS-классы. Все перечисленные ниже классы применимы как к виджетам Autocomplete , так и к SearchBox .

Оптимизация автозаполнения (устаревшая версия)

В этом разделе описываются рекомендации, которые помогут вам максимально эффективно использовать услугу Place Autocomplete (устаревшая версия).

Вот некоторые общие рекомендации:

• Самый быстрый способ разработать рабочий пользовательский интерфейс — использовать виджет Maps JavaScript API Place Autocomplete (Legacy) , виджет Place Autocomplete (Legacy) Places SDK for Android или элемент управления пользовательского интерфейса Place Autocomplete (Legacy) Place SDK for iOS
• С самого начала изучите основные поля данных Place Autocomplete (Legacy).
• Поля смещения местоположения и ограничения местоположения являются необязательными, но могут оказать существенное влияние на производительность автозаполнения.
• Используйте обработку ошибок, чтобы гарантировать корректную работу приложения в случае, если API возвращает ошибку.
• Убедитесь, что ваше приложение обрабатывает ситуацию, когда выбора нет, и предлагает пользователям возможность продолжить.

Лучшие практики оптимизации затрат

Базовая оптимизация затрат

Чтобы оптимизировать стоимость использования сервиса автозаполнения мест (устаревшая версия), используйте маски полей в виджетах «Сведения о месте (устаревшая версия)» и «Автозаполнение мест (устаревшая версия)», чтобы возвращать только необходимые вам поля данных о местах .

Расширенная оптимизация затрат

Рассмотрите возможность программной реализации автозаполнения мест (Place Autocomplete, устаревшая версия) для доступа к ценам Per Request и запроса результатов Geocoding API о выбранном месте вместо Place Details (устаревшая версия). Стоимость Per Request в сочетании с Geocoding API более экономична, чем Per Session (на основе сеансов), если выполняются оба следующих условия:

• Если вам нужны только широта/долгота или адрес выбранного пользователем места, API геокодирования предоставит эту информацию менее чем за один вызов Place Details (Legacy).
• Если пользователи выбирают прогноз автозаполнения в среднем в течение четырех запросов прогнозов Place Autocomplete (Legacy) или менее, цена за запрос может быть более экономически эффективной, чем цена за сеанс.

Требуется ли для вашего приложения какая-либо информация, помимо адреса и широты/долготы выбранного прогноза?

Лучшие практики производительности

В следующих рекомендациях описаны способы оптимизации производительности автозаполнения мест (устаревшая версия):

• Добавьте ограничения по странам, смещение местоположения и (для программных реализаций) языковые предпочтения в реализацию автозаполнения мест (устаревшая версия). Языковые настройки не требуются для виджетов, поскольку они выбирают языковые настройки из браузера или мобильного устройства пользователя.
• Если автозаполнение места (устаревшая версия) сопровождается картой, вы можете смещать местоположение в зависимости от области просмотра карты.
• В ситуациях, когда пользователь не выбирает один из прогнозов автозаполнения места (устаревший), как правило, потому, что ни один из этих прогнозов не является желаемым адресом результата, вы можете повторно использовать исходный пользовательский ввод, чтобы попытаться получить более релевантные результаты:
  • Если вы ожидаете, что пользователь введет только информацию об адресе, повторно используйте исходный пользовательский ввод при вызове API геокодирования .
  • Если вы ожидаете, что пользователь будет вводить запросы для определенного места по имени или адресу, используйте запрос Find Place (Legacy) . Если результаты ожидаются только в определенном регионе, используйте смещение местоположения .
  Другие сценарии, когда лучше всего вернуться к API геокодирования, включают:
  • Пользователи, вводящие адреса помещений, например адреса конкретных квартир или квартир в здании. Например, чешский адрес «Stroupežnického 3191/17, Praha» дает частичный прогноз в Place Autocomplete (Legacy).
  • Пользователи вводят адреса с префиксами сегментов дорог, например «23-30 29th St, Queens» в Нью-Йорке или «47-380 Kamehameha Hwy, Kaneohe» на острове Кауаи на Гавайях.

Ограничения по использованию

Квоты

Информацию о квотах и ​​ценах см. в документации по использованию и выставлению счетов для Places API.