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

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

Выберите платформу: Android iOS JavaScript Web Service

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

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

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

Интегрировать функцию автозаполнения (новая) в свое приложение можно двумя основными способами:

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

Чтобы упростить обеспечение единообразного автодополнения мест, вы можете добавить в приложение виджет «Автодополнение мест». Виджет предоставляет специальный полноэкранный интерфейс, который обрабатывает пользовательский ввод и отображает подсказки мест, одновременно возвращая приложению объекты AutocompletePrediction . Затем вы можете выполнить запрос « Сведения о месте (новый)» , чтобы получить дополнительную информацию о любом из подсказок.

Как и при программном получении прогнозов мест , виджет автозаполнения мест позволяет использовать токены сеанса для группировки запросов автозаполнения в сеанс для выставления счетов. Вы можете передать токен сеанса при создании намерения для виджета, вызвав setAutocompleteSessionToken() . Если вы не предоставите токен сеанса, виджет создаст его автоматически, и вы сможете получить к нему доступ, вызвав getSessionTokenFromIntent() . Подробнее об использовании токенов сеанса см. в разделе «О токенах сеанса» .

Чтобы добавить виджет Place Autocomplete в свое приложение:

(Необязательно) Задайте токен сеанса. Если вы не укажете токен сеанса, виджет создаст его автоматически.
Определите autocompleteIntent с желаемыми параметрами и токеном сеанса.
Определите ActivityResultLauncher для StartActivityForResult . Этот лаунчер будет обрабатывать результат, возвращаемый действием автозаполнения.
Обработайте результат в обратном вызове ActivityResultLauncher . Это включает в себя извлечение AutocompletePrediction и AutocompleteSessionToken (если вы не указали свои), обработку ошибок и, при необходимости, выполнение запроса fetchPlace() для получения дополнительных сведений о месте.
Запустите намерение с помощью placeAutocompleteActivityResultLauncher

В следующих примерах показано, как добавить виджет Place Autocomplete с использованием Kotlin и Java:

Котлин

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

Ява

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Получайте прогнозы мест программно

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

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

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

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

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

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

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

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

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

Автозаполнение (новое) Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Котлин

Ява

Получайте прогнозы мест программно

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

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

Запрос

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

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

Страны

Смещение ввода

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

Смещение местоположения

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

Источник

Код региона

Токен сеанса

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

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

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

Использовать источник

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