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

Введение

Автозаполнение (Autocomplete) – это функция библиотеки Places в Maps JavaScript API, которую можно добавить в приложение, чтобы оно предлагало варианты названий мест при вводе текста в поле поиска Google Карт. Сервис автозаполнения может обрабатывать полные слова и их части, предлагая подходящие названия мест, адреса и коды Plus Code. Приложения могут передавать запросы по мере их ввода и сразу же предлагать похожие варианты. Согласно определению Places API, местом может быть организация, географическое местоположение или объект инфраструктуры.

Начало работы

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

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

1. Войдите в Google Cloud Console.
2. Нажмите кнопку Select a project (Выбрать проект), затем выберите тот же проект, который вы используете для Maps JavaScript API, и нажмите Open (Открыть).
3. В списке API на панели управления поищите Places API.
4. Если этот API есть в списке – все готово к работе. Если API в списке нет, включите его:
   1. Вверху страницы нажмите Enable API (Включить API), чтобы перейти на вкладку Library (Библиотека). Вы также можете выбрать в меню слева пункт Library (Библиотека).
   2. Введите поисковый запрос Places API, а затем выберите API из списка результатов.
   3. Нажмите Enable (Включить). Когда процесс завершится, Places API появится в списке API на странице Dashboard (Панель управления).

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

Сервис Places – это автономная библиотека, отделенная от основного кода Maps JavaScript API. Для работы с этой библиотекой необходимо сначала загрузить ее с помощью параметра libraries в URL начальной загрузки Maps 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. Информацию по классу AutocompleteService можно найти в документации по Maps JavaScript API.

Ниже приведена сводная информация по доступным классам:

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

  

  

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

  

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

Как добавить виджет Autocomplete

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

Конструктор 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.

Как ограничить подсказки автозаполнения

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

Как настроить параметры при создании

Конструктор 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;
• задать границы с учетом области просмотра карты;
• ограничить поиск определенными границами;
• ограничить поиск определенной страной.

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

Как изменить границы существующего объекта 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.

В демонстрации Places Autocomplete показаны отличия в подсказках для разных типов мест.

Перейти к демонстрации

Как получить информацию о месте

Когда пользователь выбирает один из вариантов, предложенных под текстовым полем, сервис запускает событие 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

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

Как настроить текст плейсхолдера

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

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

Обратите внимание на то, что текст по умолчанию автоматически переводится на другие языки, но если вы указываете собственное значение-плейсхолдер, вы должны обеспечить его локализацию в своем приложении. Чтобы узнать, на основе чего Google Maps JavaScript API выбирает язык, ознакомьтесь с документацией по локализации.

Информацию о настройке внешнего вида виджета можно найти в разделе Как настроить стиль виджетов Autocomplete и SearchBox.

Как добавить виджет SearchBox

Виджет SearchBox позволяет пользователям выполнять поиск, ограниченный географическим регионом (например, "пиццерии в Нижнем Новгороде" или "обувной магазин на проспекте Свободы"). Если добавить к текстовому полю объект SearchBox, то по мере ввода текста служба будет возвращать подсказки в виде раскрывающегося списка.

Виджет SearchBox возвращает расширенный список подсказок, в который могут входить как места (в соответствии с определением Places API), так и предлагаемые фразы для поиска. Например, если пользователь введет запрос "пиццерия нижний", то в списке могут появиться как подсказки типа "пиццерия, Нижний Новгород", так и названия конкретных заведений. Когда пользователь выбирает место из списка, информация о нем возвращается объекту 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, вызовите для SearchBox метод setBounds() и передайте соответствующий объект 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

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

Информацию о настройке внешнего вида виджета можно найти в разделе Как настроить стиль виджетов Autocomplete и SearchBox.

Как программно получить подсказки сервиса Place Autocomplete

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

AutocompleteService дает возможность использовать следующие методы:

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

Оба метода возвращают массив из пяти объектов подсказок, который содержит следующие поля:

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

Показанный ниже код получает набор подсказок для поискового запроса "pizza near" и отображает результаты в виде списка.

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

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

Подробнее о токенах сеансов…

Как применять стили к виджетам Autocomplete и SearchBox

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

Как использовать компонент выбора мест

Примечание. В этом примере используется библиотека ПО с открытым исходным кодом. Сведения о поддержке и обратной связи для этой библиотеки вы найдете в файле README.

Попробуйте использовать веб-компоненты. Используйте веб-компонент выбора мест, чтобы включить ввод текста. Это позволит конечным пользователям искать определенные адреса или места, используя автозаполнение.

Оптимизация Place Autocomplete

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

Рассмотрим некоторые общие рекомендации.

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

Рекомендации по оптимизации затрат

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

Для оптимизации затрат на сервис Place Autocomplete используйте маски полей в виджетах Place Details и Place Autocomplete, чтобы они возвращали только нужные вам поля данных о месте.

Дополнительная оптимизация затрат

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

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

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

Рекомендации по повышению эффективности

В рекомендациях ниже описаны способы оптимизации производительности Place Autocomplete:

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

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

Квоты

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

Правила

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