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

Введение

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

Начиная

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

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

1. Перейдите в облачную консоль Google .
2. Нажмите кнопку «Выбрать проект» , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите «Открыть» .
3. В списке API на информационной панели найдите Places API .
4. Если вы видите API в списке, все готово. Если API нет в списке, включите его:
   1. В верхней части страницы выберите ВКЛЮЧИТЬ API , чтобы отобразить вкладку «Библиотека» . Либо в меню слева выберите «Библиотека» .
   2. Найдите Places API , затем выберите его из списка результатов.
   3. Выберите ВКЛЮЧИТЬ . По завершении процесса Places API появится в списке API на информационной панели .

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

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

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

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

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

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

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

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

  

  

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

  

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

autocomplete.setBounds(newBounds);
index.ts

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

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

Добавление виджета SearchBox

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// 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, виджет Places SDK для автозаполнения Android или элемент управления автозаполнением Places SDK для iOS.
• С самого начала выработайте понимание основных полей данных автозаполнения места.
• Поля смещения местоположения и ограничения местоположения не являются обязательными, но могут оказать существенное влияние на производительность автозаполнения.
• Используйте обработку ошибок, чтобы обеспечить корректное ухудшение качества вашего приложения, если API возвращает ошибку.
• Убедитесь, что ваше приложение обрабатывает ситуации, когда выбор отсутствует, и предлагает пользователям возможность продолжить.

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

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

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

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

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

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

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

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

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

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

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

Квоты

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

Политика

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

Введение

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

Начиная

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

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

1. Перейдите в Cloud Console Google .
2. Нажмите кнопку «Выберите проект» , затем выберите тот же проект, который вы настроили для API Maps JavaScript, и нажмите «Открыть» .
3. Из списка API на приборной панели ищите места API .
4. Если вы видите API в списке, все готово. Если API не указан, включите его:
   1. В верхней части страницы выберите «Включить API», чтобы отобразить вкладку библиотеки . В качестве альтернативы, в левой стороне меню выберите библиотеку .
   2. Поиск по местам API , затем выберите его из списка результатов.
   3. Выберите Enable . Когда процесс заканчивается, места API появляется в списке API на приборной панели .

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

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

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

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

  

  

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

  

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

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

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

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

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

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

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

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

По умолчанию 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

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

Укажите поля данных, чтобы избежать выставления счетов за данные, которые вам не нужны. Включите свойство fields в AutocompleteOptions , которые передаются в конструктор виджетов, как показано в предыдущем примере, или Call 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 или Call 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 AutoCoplete Prodictions. Вы можете прочитать больше об description в The Plays Autocomplete Documentation .

Для форм адреса полезно получить адрес в структурированном формате. To return the structured address for the selected place, call Autocomplete.setFields() and specify the address_components field.

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

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!">

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

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

Добавление виджета поисковой коробки

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

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

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

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

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

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 , вызовите 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.
• getQueryPredictions() возвращает расширенный список прогнозов, который может включать места (как определено The Place API), а также предлагаемые поисковые термины. Например, если пользователь входит в «Пиццу в новой», список выбора может включать фразу «Пицца в Нью -Йорке, штат Нью -Йорк», а также имена различных торговых точек пиццы.

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

• description - это соответствующий прогноз.
• distance_meters - это расстояние в метрах места от указанного AutocompletionRequest.origin .
• matched_substrings содержит набор подстроков в описании, которые соответствуют элементам при вводе пользователя. Это полезно для выделения этих подстроков в вашем приложении. Во многих случаях запрос появится как подстроение поля описания.
  • length - это длина подстроения.
  • offset - это смещение символов, измеренное с начала строки описания, при которой появляется соответствующая подстроение.
• place_id - это текстовый идентификатор, который уникально идентифицирует место. Чтобы получить информацию о месте, передайте этот идентификатор в поле placeId о запросе деталей места . Узнайте больше о том, как ссылаться на место с идентификатором места .
• 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 .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Usage limits and policies

Квоты

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

Политика

Use of the Places Library, Maps JavaScript API must be in accordance with the policies described for the Places API .

Введение

Autocomplete is a feature of the Places library in the Maps JavaScript API. You can use autocomplete to give your applications the type-ahead-search behavior of the Google Maps search field. The autocomplete service can match on full words and substrings, resolving place names, addresses, and plus codes . Applications can therefore send queries as the user types, to provide on-the-fly place predictions. As defined by the Places API, a 'place' can be an establishment, a geographic location, or a prominent point of interest.

Начиная

Before using the Places library in the Maps JavaScript API, first ensure that the Places API is enabled in the Google Cloud Console, in the same project you set up for the Maps JavaScript API.

To view your list of enabled APIs:

1. Go to the Google Cloud Console .
2. Click the Select a project button, then select the same project you set up for the Maps JavaScript API and click Open .
3. From the list of APIs on the Dashboard , look for Places API .
4. If you see the API in the list, you're all set. If the API is not listed, enable it:
   1. At the top of the page, select ENABLE API to display the Library tab. Alternatively, from the left side menu, select Library .
   2. Search for Places API , then select it from the results list.
   3. Select ENABLE . When the process finishes, Places API appears in the list of APIs on the Dashboard .

Loading the library

The Places service is a self-contained library, separate from the main Maps JavaScript API code. To use the functionality contained within this library, you must first load it using the libraries parameter in the Maps API bootstrap URL:

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

See the Libraries Overview for more information.

Summary of classes

The API offers two types of autocomplete widgets, which you can add via the Autocomplete and SearchBox classes respectively. In addition, you can use the AutocompleteService class to retrieve autocomplete results programmatically (see the Maps JavaScript API Reference: AutocompleteService class ).

Below is a summary of the classes available:

• Autocomplete adds a text input field to your web page, and monitors that field for character entries. As the user enters text, autocomplete returns place predictions in the form of a dropdown pick list. When the user selects a place from the list, information about the place is returned to the autocomplete object, and can be retrieved by your application. See the details below .

  

  

• SearchBox adds a text input field to your web page, in much the same way as Autocomplete . The differences are as follows:
  • The main difference lies in the results that appear in the pick list. SearchBox supplies an extended list of predictions, which can include places (as defined by the Places API) plus suggested search terms. For example, if the user enters 'pizza in new', the pick list may include the phrase 'pizza in New York, NY' as well as the names of various pizza outlets.
  • SearchBox offers fewer options than Autocomplete for restricting the search. In the former, you can bias the search towards a given LatLngBounds . In the latter, you can restrict the search to a particular country and particular place types, as well as setting the bounds. For more information, see below .

  

  See the details below .
• You can create an AutocompleteService object to retrieve predictions programmatically. Call getPlacePredictions() to retrieve matching places, or call getQueryPredictions() to retrieve matching places plus suggested search terms. Note: AutocompleteService does not add any UI controls. Instead, the above methods return an array of prediction objects. Each prediction object contains the text of the prediction, as well as reference information and details of how the result matches the user input. See the details below .

Adding an Autocomplete widget

The Autocomplete widget creates a text input field on your web page, supplies predictions of places in a UI pick list, and returns place details in response to a getPlace() request. Each entry in the pick list corresponds to a single place (as defined by the Places API).

The Autocomplete constructor takes two arguments:

• An HTML input element of type text . This is the input field that the autocomplete service will monitor and attach its results to.
• An optional AutocompleteOptions argument, which can contain the following properties:
  • An array of data fields to be included in the Place Details response for the user's selected PlaceResult . If the property is not set or if ['ALL'] is passed in, all available fields are returned and billed for (this is not recommended for production deployments). For a list of fields, see PlaceResult .
  • An array of types that specifies an explicit type or a type collection, as listed in the supported types . If no type is specified, all types are returned.
  • bounds is a google.maps.LatLngBounds object specifying the area in which to search for places. The results are biased towards, but not restricted to, places contained within these bounds.
  • strictBounds is a boolean specifying whether the API must return only those places that are strictly within the region defined by the given bounds . The API does not return results outside this region even if they match the user input.
  • componentRestrictions can be used to restrict results to specific groups. Currently, you can use componentRestrictions to filter by up to 5 countries. Countries must be passed as as a two-character, ISO 3166-1 Alpha-2 compatible country code. Multiple countries must be passed as a list of country codes.

    Note: If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at Wikipedia: List of ISO 3166 country codes or the ISO Online Browsing Platform .

  • placeIdOnly can be used to instruct the Autocomplete widget to retrieve only Place IDs. On calling getPlace() on the Autocomplete object, the PlaceResult made available will only have the place id , types and name properties set. You can use the returned place ID with calls to the Places, Geocoding, Directions or Distance Matrix services.

Constraining Autocomplete predictions

By default, Place Autocomplete presents all place types, biased for predictions near the user's location, and fetches all available data fields for the user's selected place. Set Place Autocomplete options to present more relevant predictions based on your use case.

Set options at construction

The Autocomplete constructor accepts an AutocompleteOptions parameter to set constraints at widget creation. The following example sets the bounds , componentRestrictions , and types options to request establishment type places, favoring those within the specified geographic area and restricting predictions to only places within the United States. Setting the fields option specifies what information to return about the user's selected place.

Call setOptions() to change an option's value for an existing widget.

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

Specify data fields

Specify data fields to avoid being billed for Places Data SKUs you don't need. Include the fields property in the AutocompleteOptions that are passed to the widget constructor, as demonstrated in the previous example, or call setFields() on an existing Autocomplete object.

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

Define biases and search-area boundaries for Autocomplete

You can bias the autocomplete results to favor an approximate location or area, in the following ways:

• Set the bounds on creation of the Autocomplete object.
• Change the bounds on an existing Autocomplete .
• Set the bounds to the map's viewport.
• Restrict the search to the bounds.
• Restrict the search to a specific country.

The previous example demonstrates setting bounds at creation. The following examples demonstrate the other biasing techniques.

Change the bounds of an existing Autocomplete

Call setBounds() to change the search area on an existing Autocomplete to rectangular bounds.

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

Set the bounds to the map's viewport

Use bindTo() to bias the results to the map's viewport, even while that viewport changes.

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

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

Use unbind() to unbind the Autocomplete predictions from the map's viewport.

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

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

Restrict the search to the current bounds

Set the strictBounds option to restrict the results to the current bounds, whether based on map viewport or rectangular bounds.

autocomplete.setOptions({ strictBounds: true });

Restrict predictions to a specific country

Use the componentRestrictions option or call setComponentRestrictions() to restrict the autocomplete search to a specific set of up to five countries.

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

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

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

Constrain place types

Use the types option or call setTypes() to constrain predictions to certain place types. This constraint specifies a type or a type collection, as listed in Place Types . If no constraint is specified, all types are returned.

For the value of the types option or the value passed to setTypes() , you can specify either:

• An array containing up to five values from Table 1 or Table 2 from Place Types . Например:

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

  Или:

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

• Any one filter in Table 3 from Place Types . You can only specify a single value from Table 3.

The request will be rejected if:

• You specify more than five types.
• You specify any unrecognized types.
• You mix any types from Table 1 or Table 2 with any filter from Table 3 .

The Places Autocomplete demo demonstrates the differences in predictions between different place types.

Visit demo

Getting place information

When a user selects a place from the predictions attached to the autocomplete text field, the service fires a place_changed event. To get place details:

1. Create an event handler for the place_changed event, and call addListener() on the Autocomplete object to add the handler.
2. Call Autocomplete.getPlace() on the Autocomplete object, to retrieve a PlaceResult object, which you can then use to get more information about the selected place.

By default, when a user selects a place, autocomplete returns all of the available data fields for the selected place, and you will be billed accordingly . Use Autocomplete.setFields() to specify which place data fields to return. Read more about the PlaceResult object, including a list of place data fields that you can request. To avoid paying for data that you don't need, be sure to use Autocomplete.setFields() to specify only the place data that you will use.

The name property contains the description from Places Autocomplete predictions. You can read more about the description in the Places Autocomplete documentation .

For address forms, it is useful to get the address in structured format. To return the structured address for the selected place, call Autocomplete.setFields() and specify the address_components field.

The following example uses autocomplete to fill the fields in an address form.

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