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

Введение

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

Начиная

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

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

1. Перейдите в консоль Google Cloud .
2. Нажмите кнопку «Выбрать проект» , затем выберите тот же проект, который вы настроили для API JavaScript карт, и нажмите «Открыть» .
3. В списке API на панели управления найдите Places API .
4. Если вы видите API в списке, значит, все в порядке. Однако этот проект находится в статусе «Устаревший». Для получения дополнительной информации об устаревшем статусе и о том, как перейти с устаревших сервисов на более новые, см. раздел «Устаревшие продукты и функции» . Исключение составляют виджеты «Автозаполнение» и «Поисковое поле» , которые пока недоступны в качестве общедоступного продукта в Places API (новый).

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

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

<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 добавляет на вашу веб-страницу текстовое поле ввода и отслеживает ввод символов в это поле. По мере ввода текста пользователем функция автозаполнения возвращает варианты мест в виде выпадающего списка. Когда пользователь выбирает место из списка, информация о месте возвращается объекту автозаполнения и может быть получена вашим приложением. Подробнее см. ниже .

  

  

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

  

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

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

Виджет 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 можно фильтровать результаты по 5 странам. Страны должны передаваться в виде двухсимвольного кода страны, совместимого со стандартом ISO 3166-1 Alpha-2. Несколько стран должны передаваться в виде списка кодов стран.

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

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

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

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

Выбор параметров на этапе строительства

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

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

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

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

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

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

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

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

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

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

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

В предыдущем примере показано, как задаются границы при создании. В следующих примерах демонстрируются другие методы смещения.

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

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

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

autocomplete.setBounds(newBounds);
index.ts

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

autocomplete.setBounds(newBounds);
index.js

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

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

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

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

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

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

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

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

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

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

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

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

Ограничение типов мест

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

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

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

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

  Или:

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

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

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

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

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

Посмотреть демоверсию

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

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

window.initAutocomplete = initAutocomplete;
index.js

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

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

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

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

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

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

Добавьте виджет «Поисковое поле».

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

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

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

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

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

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
index.js

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

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

Программное получение прогнозов сервиса автозаполнения мест

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

window.initService = initService;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

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

Токены сессии

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

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

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

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

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

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

Передовые методы оптимизации затрат

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

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

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

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

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

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

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

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

• Add country restrictions, location biasing , and (for programmatic implementations) language preference to your Place Autocomplete (Legacy) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
• If Place Autocomplete (Legacy) is accompanied by a map, you can bias location by map viewport.
• In situations when a user does not choose one of the Place Autocomplete (Legacy) predictions, generally because none of those predictions are the result-address wanted, you can reuse the original user input to attempt to get more relevant results:
  • If you expect the user to enter only address information, reuse the original user input in a call to the Geocoding API .
  • If you expect the user to enter queries for a specific place by name or address, use a Place Details (Legacy) request . If results are only expected in a specific region, use location biasing .
  Other scenarios when it's best to fall back to the Geocoding API include:
  • Users inputting subpremise addresses, such as addresses for specific units or apartments within a building. For example, the Czech address "Stroupežnického 3191/17, Praha" yields a partial prediction in Place Autocomplete (Legacy).
  • Users inputting addresses with road-segment prefixes like "23-30 29th St, Queens" in New York City or "47-380 Kamehameha Hwy, Kaneohe" on the island of Kauai in Hawai'i.

Location biasing

Bias results to a specified area by passing a location parameter and a radius parameter. This instructs Place Autocomplete (Legacy) to prefer showing results within the defined area. Results outside of the defined area may still be displayed. You can use the components parameter to filter results to show only those places within a specified country.

Location restricting

Restrict results to a specified area by passing a locationRestriction parameter.

You may also restrict results to the region defined by location and a radius parameter, by adding the strictbounds parameter. This instructs Place Autocomplete (Legacy) to return only results within that region.

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

Квоты

For quota and pricing information, see the Usage and Billing documentation for the Places API.