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

Выберите платформу: Android iOS Веб-служба JavaScript

Введение

Автозаполнение — это функция библиотеки Places в Maps JavaScript API. Вы можете использовать автозаполнение, чтобы придать вашим приложениям функцию поиска с опережением ввода, как в поле поиска Google Maps. Служба автозаполнения может сопоставлять полные слова и подстроки, разрешая названия мест, адреса и коды плюсов . Таким образом, приложения могут отправлять запросы по мере ввода пользователем текста, чтобы оперативно прогнозировать места. Согласно определению 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 в списке, все готово. Если API нет в списке, включите его:
    1. В верхней части страницы выберите ВКЛЮЧИТЬ API , чтобы отобразить вкладку «Библиотека» . Либо в меню слева выберите «Библиотека» .
    2. Найдите Places API , затем выберите его из списка результатов.
    3. Выберите ВКЛЮЧИТЬ . По завершении процесса Places API появится в списке API на информационной панели .

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

Служба Places — это автономная библиотека, отдельная от основного кода API JavaScript Карт. Чтобы использовать функциональные возможности, содержащиеся в этой библиотеке, необходимо сначала загрузить ее с помощью параметра 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 для программного получения результатов автозаполнения (см. Справочник по API JavaScript Карт: класс AutocompleteService ).

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

  • Autocomplete добавляет поле ввода текста на вашу веб-страницу и отслеживает в этом поле ввод символов. Когда пользователь вводит текст, автозаполнение возвращает подсказки мест в виде раскрывающегося списка выбора. Когда пользователь выбирает место из списка, информация об этом месте возвращается объекту автозаполнения и может быть получена вашим приложением. Подробности смотрите ниже .
    Текстовое поле автозаполнения и список выбора места. прогнозы, предоставляемые при вводе пользователем поискового запроса.
    Рисунок 1. Текстовое поле автозаполнения и список выбора.
    Заполненная адресная форма.
    Рисунок 2. Заполненная адресная форма.
  • SearchBox добавляет поле ввода текста на вашу веб-страницу почти так же, как Autocomplete . Различия заключаются в следующем:
    • Основное отличие заключается в результатах, которые появляются в списке выбора. SearchBox предоставляет расширенный список подсказок, который может включать места (согласно API-интерфейсу Places) и предлагаемые условия поиска. Например, если пользователь вводит «пицца в Нью-Йорке», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных пиццерий.
    • SearchBox предлагает меньше возможностей, чем Autocomplete для ограничения поиска. В первом случае вы можете сместить поиск в сторону заданного LatLngBounds . В последнем вы можете ограничить поиск определенной страной и определенными типами мест, а также установить границы. Дополнительную информацию см. ниже .
    Заполненная адресная форма.
    Рисунок 3. Поле поиска отображает условия поиска и подсказки мест.
    Подробности смотрите ниже .
  • Вы можете создать объект AutocompleteService для программного получения прогнозов. Вызовите getPlacePredictions() , чтобы получить совпадающие места, или вызовите getQueryPredictions() чтобы получить совпадающие места и предлагаемые условия поиска. Примечание. AutocompleteService не добавляет никаких элементов управления пользовательского интерфейса. Вместо этого вышеуказанные методы возвращают массив объектов прогнозирования. Каждый объект прогнозирования содержит текст прогноза, а также справочную информацию и сведения о том, как результат соответствует вводу пользователя. Подробности смотрите ниже .

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

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

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

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

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

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

Укажите поля данных, чтобы избежать выставления счетов за ненужные вам артикулы данных Places . Включите свойство 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

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
Установите границы области просмотра карты

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

Машинопись 

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

JavaScript 

autocomplete.bindTo("bounds", map);

index.js

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

Машинопись 

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

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

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

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

autocomplete.setOptions({ strictBounds: true });
Ограничить прогнозы определенной страной

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

Машинопись 

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

JavaScript 

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 из подсказок автозаполнения мест. Подробнее об 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

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

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

Настройка текста заполнителя

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

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

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

См. раздел «Стилизация виджетов «Автозаполнение» и «Поле поиска», чтобы настроить внешний вид виджета.

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

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

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

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

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

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

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

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

См. раздел «Стилизация виджетов «Автозаполнение» и «Поле поиска», чтобы настроить внешний вид виджета.

Программное получение подсказок службы автозаполнения мест

Чтобы получить прогнозы программным способом, используйте класс 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

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

Попробуйте образец

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

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

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

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

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

В следующем примере показано создание токена сеанса и его последующая передача в 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);

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

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

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

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

Графическая иллюстрация классов CSS для автозаполнения и Виджеты SearchBox
Классы CSS для виджетов автозаполнения и SearchBox
CSS-класс Описание
pac-container Визуальный элемент, содержащий список подсказок, возвращаемых службой автозаполнения мест. Этот список отображается в виде раскрывающегося списка под виджетом Autocomplete или SearchBox .
pac-icon Значок отображается слева от каждого элемента в списке прогнозов.
pac-item Элемент в списке подсказок, предоставляемый виджетом Autocomplete или « SearchBox .
pac-item:hover Элемент, когда пользователь наводит на него указатель мыши.
pac-item-selected Элемент, когда пользователь выбирает его с помощью клавиатуры. Примечание. Выбранные предметы будут членами этого класса и класса pac-item .
pac-item-query Промежуток внутри pac-item , который является основной частью прогноза. Для географических местоположений оно содержит название места, например «Сидней», или название и номер улицы, например «10 King Street». Для текстового поиска, например «пицца в Нью-Йорке», он содержит полный текст запроса. По умолчанию pac-item-query окрашен в черный цвет. Если в pac-item есть какой-либо дополнительный текст, он находится за пределами pac-item-query и наследует свой стиль от pac-item . По умолчанию он окрашен в серый цвет. Дополнительный текст обычно представляет собой адрес.
pac-matched Часть возвращенного прогноза, соответствующая вводу пользователя. По умолчанию этот совпадающий текст выделяется жирным шрифтом. Обратите внимание, что совпадающий текст может находиться где угодно внутри pac-item . Это не обязательно является частью pac-item-query и может быть частично внутри pac-item-query а также частично в оставшемся тексте pac-item .

Оптимизация автозаполнения мест

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

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

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

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

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

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

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

Рассмотрите возможность программной реализации автозаполнения мест, чтобы получить доступ к ценам за запрос и запросить результаты API геокодирования о выбранном месте вместо сведений о месте. Цена за запрос в сочетании с API геокодирования является более рентабельной, чем цена за сеанс (на основе сеанса), если выполняются оба следующих условия:

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

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

Да, нужно больше подробностей

Используйте автозаполнение мест на основе сеанса с подробными сведениями о месте.
Поскольку вашему приложению требуются сведения о месте, такие как название места, статус компании или часы работы, ваша реализация автозаполнения места должна использовать токен сеанса ( программно или встроенный в виджеты JavaScript , Android или iOS ) общей стоимостью 0,017 доллара США за штуку. сеанс плюс соответствующие SKU данных о местах в зависимости от того, какие поля данных о местах вы запрашиваете. 1

Реализация виджета
Управление сеансами автоматически встроено в виджеты JavaScript , Android или iOS . Сюда входят как запросы автозаполнения места, так и запрос сведений о месте для выбранного прогноза. Обязательно укажите параметр fields , чтобы гарантировать, что вы запрашиваете только те поля данных о месте, которые вам нужны.

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

  1. Идентификатор места из ответа автозаполнения места.
  2. Токен сеанса, используемый в запросе автозаполнения места.
  3. Параметр fields , определяющий нужные вам поля данных о месте.

Нет, нужен только адрес и местоположение

API геокодирования может быть более экономичным вариантом, чем сведения о месте для вашего приложения, в зависимости от производительности использования автозаполнения мест. Эффективность автозаполнения каждого приложения зависит от того, что вводят пользователи, где используется приложение и реализованы ли передовые методы оптимизации производительности .

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

Выбирают ли ваши пользователи подсказку автозаполнения места в среднем за четыре или меньше запросов?

Да

Реализуйте автозаполнение мест программно без токенов сеанса и вызовите API геокодирования для прогнозирования выбранного места.
API геокодирования предоставляет адреса и координаты широты и долготы за 0,005 доллара США за запрос. Выполнение четырех запросов автозаполнения места по запросу стоит 0,01132 доллара США, поэтому общая стоимость четырех запросов плюс вызов API геокодирования для прогнозирования выбранного места составит 0,01632 доллара США, что меньше, чем цена автозаполнения за сеанс, составляющая 0,017 доллара США за сеанс. 1

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

Нет

Используйте автозаполнение мест на основе сеанса с подробными сведениями о месте.
Поскольку среднее количество запросов, которые вы ожидаете сделать до того, как пользователь выберет прогноз автозаполнения места, превышает стоимость сеанса, ваша реализация автозаполнения места должна использовать токен сеанса как для запросов автозаполнения места, так и для соответствующего запроса сведений о месте для Общая стоимость 0,017 доллара США за сеанс . 1

Реализация виджета
Управление сеансами автоматически встроено в виджеты JavaScript , Android или iOS . Сюда входят как запросы автозаполнения места, так и запрос сведений о месте для выбранного прогноза. Обязательно укажите параметр fields , чтобы гарантировать, что вы запрашиваете только поля базовых данных .

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

  1. Идентификатор места из ответа автозаполнения места.
  2. Токен сеанса, используемый в запросе автозаполнения места.
  3. Параметр fields , определяющий поля базовых данных , такие как адрес и геометрия.

Рассмотрите возможность задержки запросов автозаполнения мест.
Вы можете использовать такие стратегии, как задержка запроса автозаполнения места до тех пор, пока пользователь не введет первые три или четыре символа, чтобы ваше приложение делало меньше запросов. Например, выполнение запросов автозаполнения места для каждого символа после того, как пользователь ввел третий символ, означает, что если пользователь вводит семь символов, а затем выбирает прогноз, для которого вы делаете один запрос API геокодирования, общая стоимость составит 0,01632 доллара США (4 * 0,00283 доллара США). За запрос + 0,005 доллара США за геокодирование). 1

Если из-за задержки запросов ваш средний программный запрос может стать ниже четырех, вы можете следовать рекомендациям по эффективной реализации автозаполнения мест с использованием API геокодирования . Обратите внимание, что задержка запросов может восприниматься пользователем как задержка, который ожидает увидеть прогнозы при каждом новом нажатии клавиши.

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

  1. Стоимость указана здесь в долларах США. Полную информацию о ценах можно найти на странице оплаты платформы Google Maps .

Рекомендации по повышению производительности

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

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

Пределы использования и политики

Квоты

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

Политика

Использование библиотеки мест, карты JavaScript API должны соответствовать политикам, описанным для API Place .