Подсказки мест

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

Введение

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

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

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

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

Сервис Places – самодостаточная библиотека, используемая отдельно от основного кода Maps JavaScript API. Для работы с этой библиотекой необходимо сначала загрузить ее с помощью параметра libraries в URL начальной загрузки Maps API:

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

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

Краткий обзор классов

В API имеется два типа виджетов автозаполнения, которые добавляются соответственно с помощью классов Autocomplete и SearchBox. Кроме того, для получения результатов автозаполнения программными средствами предусмотрен класс AutocompleteService. Информацию по классу AutocompleteService можно найти в документации по Maps JavaScript API.

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

  • С помощью класса Autocomplete можно добавить на веб-страницу поле ввода и отслеживать вводимые в него запросы. По мере того как пользователь набирает текст, функция автозаполнения предлагает подсказки адресов в виде раскрывающегося списка. Когда пользователь выбирает вариант из списка, информация об этом месте возвращается объекту автозаполнения и может быть получена приложением. Подробная информация приведена в разделе ниже.
    Текстовое поле и список подсказок, которые отображаются по мере ввода запроса.
    Рисунок 1. Автозаполнение в текстовом поле и список подсказок
    Заполненная форма адреса.
    Рисунок 2. Заполненная форма адреса
  • Класс SearchBox, как и Autocomplete, позволяет добавить на веб-страницу текстовое поле, однако имеет несколько отличий:
    • Главное отличие заключается в том, какие результаты отображаются. Метод SearchBox возвращает расширенный список подсказок, в который могут входить как места (в соответствии с определением Places API), так и предлагаемые фразы для поиска. Например, если пользователь введет запрос "пиццерия нижний", то в списке могут появиться как подсказки типа "пиццерия, Нижний Новгород", так и названия конкретных заведений.
    • Класс SearchBox предлагает меньше параметров ограничения поиска, чем Autocomplete. С помощью первого вы можете указать определенные границы LatLngBounds, а второй помимо этого позволяет ограничить результаты поиска определенной страной или определенным типом мест. Подробная информация приведена в разделе ниже.
    Заполненная форма адреса.
    Рисунок 3. SearchBox показывает поисковый запрос и подсказки мест.
    Подробная информация приведена в разделе ниже.
  • Чтобы получать подсказки программными средствами, создайте объект 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(), чтобы изменить значение параметра для существующего виджета.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

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,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Как указать поля данных

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

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

Как установить предпочтения и границы области поиска для виджета Autocomplete

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

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

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

Как изменить границы существующего объекта Autocomplete

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

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

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);
Как установить границы по размеру окна просмотра карты

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

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

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

TypeScript

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

JavaScript

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

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

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

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

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

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

TypeScript

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

JavaScript

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

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

Как ограничить типы мест

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

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

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

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

    Или:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Любой фильтр из таблицы 3 из статьи Типы мест. Вы можете указать только одно значение из таблицы 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.

В примере ниже адрес добавляется в поля формы.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

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;

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

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

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

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

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

Информацию о настройке внешнего вида виджета можно найти в разделе Как настроить стиль виджетов Autocomplete и 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 можно найти в документации по сведениям об адресах в результатах.

TypeScript

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

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

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

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

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

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

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

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

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

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

Информацию о настройке внешнего вида виджета можно найти в разделе Как настроить стиль виджетов 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" и отображает результаты в виде списка.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

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;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

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

Примеры кода

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

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

Метод 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.

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

Оптимизация 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 Details.
Поскольку для вашего приложения требуется информация о месте, такая как название, статус или часы работы, в вашей реализации Place Autocomplete следует использовать токен сеанса (программный или встроенный в виджет JavaScript, Android или iOS). Стоимость сеанса будет составлять 0,017 $ плюс применимая плата в соответствии с кодами Places Data в зависимости от того, какие поля сведений о месте будут запрошены1.

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

Программная реализация
Используйте токен сеанса с запросами Place Autocomplete. Запрашивая у Place Details информацию о выбранной подсказке, указывайте следующие параметры:

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

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

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

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

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

Да

Реализуйте Place Autocomplete программно без токенов сеансов и вызывайте Geocoding API для выбранной подсказки места.
Geocoding API предоставляет адреса и координаты широты и долготы по цене 0,005 $ за запрос. Четыре запроса Place Autocomplete – Per Request стоят 0,01132 $, так что общая стоимость четырех запросов вместе с вызовом Geocoding API о выбранной подсказке места будет стоить 0,01632 $ – это выгоднее, чем платить 0,017 $ по тарифу Per Session Autocomplete1.

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

Нет

Используйте сервис Place Autocomplete на основе сеансов с виджетом Place Details.
Поскольку среднее ожидаемое количество запросов, которое понадобится, прежде чем пользователь выберет подсказку Place Autocomplete, превышает стоимость по тарифу Per Session, рекомендуем в вашей реализации Place Autocomplete использовать токен сеанса для запросов Place Autocomplete и связанного запроса Place Details. Это будет стоить 0,017 $ за сеанс1.

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как запросы Place Autocomplete, так и запрос Place Details для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только поля Basic Data.

Программная реализация
Используйте токен сеанса с запросами Place Autocomplete. Запрашивая у Place Details информацию о выбранной подсказке, указывайте следующие параметры:

  1. идентификатор места из ответа Place Autocomplete;
  2. токен сеанса, использованный в запросе Place Autocomplete;
  3. Параметр fields, указывающий поля Basic Data, например адрес и геометрические данные.

Рассмотрите возможность откладывать запросы Place Autocomplete
Вы можете попробовать различные стратегии, например откладывать запрос Place Autocomplete, пока пользователь не введет первые три или четыре символа, чтобы ваше приложение совершало меньше запросов. Рассмотрим следующий пример: вы настроили Place Autocomplete так, чтобы запросы совершались для каждого символа после того, как пользователь введет третий символ. Если пользователь введет семь символов, а затем выберет подсказку, для которой будет совершен один запрос Geocoding API, общая стоимость составит 0,01632 $ (четыре запроса Autocomplete Per Request по 0,00283 $ + один запрос Geocoding API стоимостью 0,005 $)1.

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

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


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

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

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

  • Добавьте в свою реализацию Place Autocomplete ограничения по стране, предпочтение местоположений и (для программных реализаций) предпочитаемый язык. Предпочитаемый язык не нужен в случае виджетов, потому что для них язык определяется на основе настроек браузера или мобильного устройства.
  • Если вместе с Place Autocomplete отображается карта, вы можете сделать предпочитаемым местоположением видимую область карты.
  • Если пользователь не выберет ни одну из подсказок Autocomplete – чаще всего такое бывает, если ни одна из них не соответствует искомому адресу, — вы можете повторно использовать изначально введенные пользователем данные, чтобы получить более подходящие результаты:
    • Если вы рассчитываете, что пользователь будет вводить только информацию об адресе, повторно используйте изначально введенные им данные в вызове Geocoding API.
    • Если пользователь скорее всего будет вводить запросы для определенного места по имени ли адресу, используйте запрос Find Place. Если ожидается, что результаты будут из определенного региона, используйте предпочтение местоположений.
    К другим сценариям, при которых лучше вернуться к использованию 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.