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

Разработчики Европейской экономической зоны (ЕЭЗ)
Примечание: Серверные библиотеки

На этой странице описывается клиентская библиотека, доступная с Maps JavaScript API. Если вы хотите работать с веб-сервисом Places API на своем сервере, взгляните на Node.js Client for Google Maps Services . На странице по этой ссылке также представлены Java Client, Python Client и Go Client for Google Maps Services.

Введение

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

Начиная

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

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

  1. Перейдите в консоль Google Cloud .
  2. Нажмите кнопку Выбрать проект , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите Открыть .
  3. В списке API на панели инструментов найдите API мест .
  4. Если вы видите API в списке, все готово. Однако этот проект находится в статусе Legacy. Для получения дополнительной информации о стадии Legacy и о том, как перейти с Legacy на более новые сервисы, см. раздел Legacy products and features . Исключение доступно для виджетов Autocomplete и SearchBox , которые пока не доступны как продукт GA в API Places (New).

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

Служба 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 Reference: AutocompleteService class ).

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

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

      Примечание: Если вы получаете неожиданные результаты с кодом страны, убедитесь, что вы используете код, который включает страны, зависимые территории и особые географические области, которые вы подразумеваете. Информацию о коде можно найти в Wikipedia: List of ISO 3166 country codes или на платформе ISO Online Browsing Platform .

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

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

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

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

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

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

Машинопись 

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

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

JavaScript 

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

index.js

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

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

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

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

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

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

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

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

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

Машинопись 

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

autocomplete.setBounds(newBounds);
index.ts

JavaScript 

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

autocomplete.setBounds(newBounds);

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

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

Машинопись 

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

JavaScript 

autocomplete.bindTo("bounds", map);

index.js

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

Машинопись 

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

JavaScript 

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

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

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

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

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

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

Машинопись 

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

JavaScript 

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

index.js

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

Ограничить типы мест

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

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

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

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

    Или: 

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

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

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

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

Посетить демо

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

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

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

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

Свойство name содержит description из подсказок 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

JavaScript 

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

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

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

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

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

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

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

window.initAutocomplete = initAutocomplete;

index.js

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

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

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

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

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

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

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

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

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

  • Элемент input HTML типа 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

JavaScript 

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

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

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

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

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

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

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

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

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

Программное получение прогнозов Place Autocomplete Service

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

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

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

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

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

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

Машинопись 

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

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

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

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

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

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

JavaScript 

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

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

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

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

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

window.initService = initService;
index.js

CSS 

style.css

HTML 

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

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

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

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

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

Сеансовые токены

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

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

Обязательно передайте уникальный токен сеанса для каждого нового сеанса. Использование одного и того же токена для нескольких сеансов Autocomplete сделает эти сеансы Autocomplete недействительными, и все запросы Autocomplete в недействительных сеансах будут оплачиваться индивидуально с использованием Autocomplete Per Request 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);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Да

Реализуйте функцию автозаполнения мест (устаревшую) программно без токенов сеанса и вызовите API геокодирования для выбранного прогноза места.
Geocoding API предоставляет адреса и координаты широты/долготы. Выполнение четырех запросов Place Autocomplete (Legacy) - Per Request плюс вызов Geocoding API о выбранном прогнозе места стоит меньше, чем стоимость Per Session Place Autocomplete (Legacy) за сеанс. 1

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

Нет

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

Реализация виджета
Управление сеансом автоматически встроено в виджеты JavaScript , Android или iOS . Это включает в себя как запросы Place Autocomplete (Legacy), так и запросы Place Details (Legacy) для выбранного прогноза. Обязательно укажите параметр fields , чтобы убедиться, что вы запрашиваете только поля Basic Data .

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

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

Рассмотрите возможность отсрочки запросов Place Autocomplete (Legacy)
Вы можете использовать такие стратегии, как задержка запроса Place Autocomplete (Legacy) до тех пор, пока пользователь не введет первые три или четыре символа, чтобы ваше приложение делало меньше запросов. Например, выполнение запросов Place Autocomplete (Legacy) для каждого символа после того, как пользователь ввел третий символ, означает, что если пользователь введет семь символов, а затем выберет прогноз, для которого вы сделаете один запрос Geocoding API, общая стоимость составит 4 Place Autocomplete (Legacy) Per Request + Geocoding. 1

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

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

  1. Стоимость можно узнать в прайс-листах платформы Google Карт .

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

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

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

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

Квоты

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