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

Введение

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

  

  

• 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. Несколько стран должны быть переданы как список кодов стран.

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

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

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

autocomplete.setBounds(newBounds);
index.js

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

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

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

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

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

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

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

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

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

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

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

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

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

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

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

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

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

  Или:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

window.initAutocomplete = initAutocomplete;
index.js

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

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

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

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

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

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

Добавить виджет SearchBox

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

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

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

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

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

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

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

window.initService = initService;
index.js

style.css

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

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

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

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

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

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

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

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

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

В этом разделе описываются рекомендации, которые помогут вам максимально эффективно использовать услугу 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):

• Добавьте ограничения по странам, смещение местоположения и (для программных реализаций) языковые предпочтения в реализацию Place Autocomplete (Legacy). Языковые предпочтения не нужны для виджетов, поскольку они выбирают языковые предпочтения из браузера или мобильного устройства пользователя.
• Если функция автозаполнения мест (устаревшая) сопровождается картой, вы можете смещать местоположение в зависимости от области просмотра карты.
• В ситуациях, когда пользователь не выбирает ни одно из предсказаний Place Autocomplete (Legacy), как правило, потому, что ни одно из этих предсказаний не является желаемым адресом результата, вы можете повторно использовать исходный пользовательский ввод, чтобы попытаться получить более релевантные результаты:
  • Если вы ожидаете, что пользователь введет только адресную информацию, повторно используйте исходный пользовательский ввод в вызове API геокодирования .
  • Если вы ожидаете, что пользователь введет запросы для определенного места по имени или адресу, используйте запрос Find Place (Legacy) . Если результаты ожидаются только в конкретной области, используйте смещение местоположения .
  Другие сценарии, когда лучше вернуться к геокодированию API, включают:
  • Пользователи вводят адреса подпресс -адресов, такие как адреса для конкретных единиц или квартир в здании. Например, чешский адрес «Stroupežnického 3191/17, Praha» дает частичный прогноз на месте автозаполнения (Legacy).
  • Пользователи вводят адреса с префиксами сегмента дорожного движения, такими как «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 в списке, все готово. Тем не менее, этот проект находится в устаревшем статусе. Для получения дополнительной информации о стадии наследия и о том, как перейти от наследия на новые услуги, см. Унаследованные продукты и функции . Исключение доступно для виджетов автозаполнения и поисковой коробки , которые еще не доступны в качестве продукта GA на API Places (новый).

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

Сервис 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 .

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

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

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

Добавить виджет Searchbox

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 .

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

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

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

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

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

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

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

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

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

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

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

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

The following guidelines describe ways to optimize Place Autocomplete (Legacy) performance:

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

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 .