Эта страница переведена с помощью Cloud Translation API.

Автозаполнение (новое)

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

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

Например, вы вызываете автозаполнение, используя в качестве входных данных строку, содержащую частичный пользовательский ввод «Сицилийская пицца», с областью поиска, ограниченной Сан-Франциско, Калифорния. Затем ответ содержит список подсказок мест, соответствующих строке поиска и области поиска, например ресторан под названием «Sicilian Pizza Kitchen».

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

Автозаполнение (новые) запросы

Ваше приложение может получить список предсказанных названий мест и/или адресов из API автозаполнения, вызвав PlacesClient.findAutocompletePredictions() и передав объект FindAutocompletePredictionsRequest . В примере ниже показан полный вызов PlacesClient.findAutocompletePredictions() .

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Примечание. Дополнительные сведения об инициализации PlacesClient см. в разделе Инициализация клиента Places API .

Автозаполнение (новые) ответы

API возвращает FindAutocompletePredictionsResponse в Task . FindAutocompletePredictionsResponse содержит список из пяти объектов AutocompletePrediction представляющих прогнозируемые места. Список может быть пустым, если не известно место, соответствующее запросу и критериям фильтра.

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

getFullText(CharacterStyle) возвращает полный текст описания места. Это сочетание первичного и вторичного текста. Пример: « Эйфелева башня, авеню Анатоля Франса, Париж, Франция ». Кроме того, этот метод позволяет выделить разделы описания, соответствующие поиску, стилем по вашему выбору, используя CharacterStyle . Параметр CharacterStyle является необязательным. Установите для него значение null, если вам не нужна подсветка.
getPrimaryText(CharacterStyle) возвращает основной текст, описывающий место. Обычно это название места. Примеры: « Эйфелева башня » и « Питт-стрит, 123 ».
getSecondaryText(CharacterStyle) возвращает вспомогательный текст описания места. Это полезно, например, в качестве второй строки при отображении подсказок автозаполнения. Примеры: « Авеню Анатоль Франс, Париж, Франция » и « Сидней, Новый Южный Уэльс ».
getPlaceId() возвращает идентификатор предсказанного места. Идентификатор места — это текстовый идентификатор, однозначно идентифицирующий место, который можно использовать для повторного получения объекта Place позже. Дополнительную информацию об идентификаторах мест в автозаполнении см. в разделе Сведения о месте (новое) . Общую информацию об идентификаторах мест см. в обзоре идентификаторов мест .
getTypes() возвращает список типов мест, связанных с этим местом.
getDistanceMeters() возвращает расстояние по прямой в метрах между этим местом и началом координат, указанным в запросе.

Обязательные параметры

Запрос
Текстовая строка, по которой осуществляется поиск. Укажите полные слова и подстроки, географические названия, адреса и плюсовые коды . Служба автозаполнения (новая) возвращает совпадения кандидатов на основе этой строки и упорядочивает результаты на основе их предполагаемой релевантности.
Чтобы установить параметр запроса, вызовите метод setQuery() при создании объекта FindAutocompletePredictionsRequest .

Дополнительные параметры

Основные типы
Список, содержащий до пяти значений типа из типов Таблица A или Таблица B, используемый для фильтрации мест, возвращаемых в ответе. Для включения в ответ место должно соответствовать одному из указанных значений основного типа.
Место может иметь только один основной тип из связанных с ним типов Таблица A или Таблица B. Например, основным типом может быть "mexican_restaurant" или "steak_house" .
Запрос отклоняется с ошибкой INVALID_REQUEST , если:
- Указано более пяти типов.
- Указываются любые нераспознанные типы.
Чтобы установить параметр основных типов, вызовите метод setTypesFilter() при построении объекта FindAutocompletePredictionsRequest .
Страны
Включайте только результаты из списка указанных стран, заданного в виде списка, содержащего до 15 двухсимвольных значений ccTLD («домен верхнего уровня») . Если этот параметр опущен, к ответу не применяются никакие ограничения. Например, чтобы ограничить регионы Германией и Францией:
Если вы укажете и locationRestriction , и includedRegionCodes , результаты будут расположены в области пересечения двух настроек.
Чтобы установить параметр стран, вызовите метод setCountries() при создании объекта FindAutocompletePredictionsRequest .
Входное смещение
Смещение символов Юникода, отсчитываемое от нуля, указывающее позицию курсора в запросе. Положение курсора может влиять на то, какие прогнозы возвращаются. Если оно пусто, по умолчанию используется длина запроса.
Чтобы установить параметр входного смещения, вызовите метод setInputOffset() при построении объекта FindAutocompletePredictionsRequest .
Предвзятость или ограничение местоположения
Чтобы определить область поиска, вы можете указать смещение местоположения или ограничение местоположения, но не то и другое. Подумайте об ограничении местоположения как об указании региона, в котором должны находиться результаты, а о смещении местоположения как об указании региона, рядом с которым должны находиться результаты. Ключевое отличие состоит в том, что при смещении местоположения результаты за пределами указанного региона все равно могут быть возвращены.
- Предвзятость местоположения
  Указывает область для поиска. Это местоположение служит отклонением, а не ограничением, поэтому результаты за пределами указанной области все равно могут быть возвращены.
  Чтобы установить параметр смещения местоположения, вызовите метод setLocationBias() при построении объекта FindAutocompletePredictionsRequest .
- Ограничение местоположения
  Указывает область для поиска. Результаты за пределами указанной области не возвращаются.
  Чтобы установить параметр ограничения местоположения, вызовите метод setLocationRestriction() при построении объекта FindAutocompletePredictionsRequest .
Укажите смещение местоположения или область ограничения местоположения в виде прямоугольного видового экрана или круга.
- Круг определяется центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от 0,0 до 50000,0 включительно. Значение по умолчанию — 0,0. Для ограничения местоположения необходимо установить радиус больше 0,0. В противном случае запрос не возвращает результатов.
- Прямоугольник — это окно просмотра широты и долготы, представленное в виде двух диагонально противоположных low и high точек. Область просмотра считается закрытой областью, то есть включает в себя ее границу. Границы широты должны находиться в диапазоне от -90 до 90 градусов включительно, а границы долготы должны находиться в диапазоне от -180 до 180 градусов включительно:
  Примечание. Поддерживаемые типы смещения различаются в зависимости от используемой версии SDK. CircularBounds доступен только в режиме автозаполнения (новое).
  - Если low = high , область просмотра состоит из этой единственной точки.
  - Если low.longitude > high.longitude , диапазон долготы инвертируется (окно просмотра пересекает линию долготы в 180 градусов).
  - Если low.longitude = -180 градусов и high.longitude = 180 градусов, область просмотра включает все значения долготы.
  - Если low.longitude = 180 градусов и high.longitude = -180 градусов, диапазон долготы пуст.
  И low , и high должны быть заполнены, а представленное поле не может быть пустым. Пустое окно просмотра приводит к ошибке.
Источник
Исходная точка, от которой рассчитывается расстояние по прямой до пункта назначения (доступ к которому осуществляется с помощью getDistanceMeters() ). Если это значение опущено, расстояние по прямой не будет возвращено. Необходимо указать координаты широты и долготы:
Чтобы установить параметр происхождения, вызовите метод setOrigin() при создании объекта FindAutocompletePredictionsRequest .
Код региона
Код региона, используемый для форматирования ответа, включая форматирование адреса, указанный в виде двухсимвольного значения ccTLD («домен верхнего уровня») . Большинство кодов ccTLD идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «uk» (.co.uk), а код ISO 3166-1 — «gb» (технически для организации «Соединенное Королевство Великобритании и Северной Ирландии»).
Примечание. Код региона предназначен для обозначения региона, из которого исходит запрос, а не обязательно целевого региона для запроса.
Если вы укажете неверный код региона, API вернет ошибку INVALID_ARGUMENT . Параметр может повлиять на результаты в соответствии с действующим законодательством.
Чтобы задать параметр кода региона, вызовите метод setRegionCode() при построении объекта FindAutocompletePredictionsRequest .
Токен сеанса
Токены сеанса — это созданные пользователем строки, которые отслеживают вызовы автозаполнения (новые) как «сеансы». Автозаполнение использует токены сеанса для группировки этапов запроса и выбора пользовательского поиска с автозаполнением в отдельный сеанс для целей выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос, и завершается, когда он выбирает место. В каждом сеансе может быть несколько запросов, за которыми следует выбор одного места. После завершения сеанса токен больше не действителен; ваше приложение должно генерировать новый токен для каждого сеанса. Мы рекомендуем использовать токены сеанса для всех сеансов программного автозаполнения (когда вы встраиваете фрагмент или запускаете автозаполнение с использованием намерения, API позаботится об этом автоматически).
Автозаполнение использует AutocompleteSessionToken для идентификации каждого сеанса. Ваше приложение должно передавать новый токен сеанса при начале каждого нового сеанса, а затем передавать этот же токен вместе с идентификатором места при последующем вызове fetchPlace() для получения сведений о месте для места, выбранного пользователем.
Чтобы установить параметр токена сеанса, вызовите метод setSessionToken() при создании объекта FindAutocompletePredictionsRequest .
Дополнительные сведения см. в разделе Токены сеанса .

Примеры автозаполнения (новые)

Используйте ограничение местоположения и предвзятость местоположения

Автозаполнение (новое) по умолчанию использует смещение IP-адресов для управления областью поиска. При смещении IP API использует IP-адрес устройства для смещения результатов. При желании вы можете использовать ограничение местоположения или смещение местоположения , но не оба, чтобы указать область для поиска.

Ограничение местоположения определяет область поиска. Результаты за пределами указанной области не возвращаются. В следующем примере используется ограничение местоположения, чтобы ограничить запрос круговым ограничением местоположения радиусом 5000 метров с центром в Сан-Франциско:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Используйте основные типы

Используйте параметр основных типов , чтобы ограничить результаты запроса определенным типом, указанным в таблице A и таблице B. Вы можете указать массив, содержащий до пяти значений. Если этот параметр опущен, возвращаются все типы.

В следующем примере указывается строка запроса «Футбол» и используется параметр основных типов, чтобы ограничить результаты заведениями типа "sporting_goods_store" :

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Если вы опустите параметр основных типов, результаты могут включать заведения нежелательного типа, например "athletic_field" .

Использовать происхождение

Когда вы включаете в запрос параметр источника , указанный как координаты широты и долготы, API включает в ответ расстояние по прямой от источника до пункта назначения (доступ к которому осуществляется с помощью getDistanceMeters() ). В этом примере начало координат устанавливается в центр Сан-Франциско:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Атрибуции

Вы можете использовать автозаполнение (новое) даже без карты. Если вы показываете карту, это должна быть карта Google. Когда вы отображаете подсказки от службы автозаполнения (новая) без карты, вы должны включить логотип Google, отображаемый в поле поиска/результатах. Дополнительную информацию см. в разделе «Отображение логотипа Google и сведений об авторстве» .

Автозаполнение (новое)

Автозаполнение (новые) запросы

Автозаполнение (новые) ответы

Обязательные параметры

Запрос

Дополнительные параметры

Основные типы

Страны

Входное смещение

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

Предвзятость местоположения

Ограничение местоположения

Источник

Код региона

Токен сеанса

Примеры автозаполнения (новые)

Используйте ограничение местоположения и предвзятость местоположения

Используйте основные типы

Использовать происхождение

Атрибуции