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

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

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

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

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

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

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

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

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

Чтобы добавить виджет автозаполнения мест в свое приложение:

(Необязательно) Определите токен сеанса. Если вы не предоставите токен сеанса, виджет создаст его для вас.
Определите 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) возвращает полный текст описания места. Это комбинация основного и дополнительного текста. Пример: " Eiffel Tower, Avenue Anatole France, Paris, France ". Кроме того, этот метод позволяет вам выделять разделы описания, соответствующие поиску, с помощью стиля по вашему выбору, используя CharacterStyle . Параметр CharacterStyle является необязательным. Установите его в null, если вам не нужно выделение.
getPrimaryText(CharacterStyle) возвращает основной текст, описывающий место. Обычно это название места. Примеры: " Eiffel Tower " и " 123 Pitt Street ".
getSecondaryText(CharacterStyle) возвращает вспомогательный текст описания места. Это полезно, например, в качестве второй строки при показе подсказок автозаполнения. Примеры: " Avenue Anatole France, Paris, France " и " Sydney, New South Wales ".
getPlaceId() возвращает идентификатор предсказанного места. Идентификатор места — это текстовый идентификатор, который однозначно определяет место, и который можно использовать для повторного извлечения объекта Place позже. Для получения дополнительной информации об идентификаторах мест в Autocomplete см. Place Details (New) . Для получения общей информации об идентификаторах мест см. Place ID Overview .
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 (New).
  - Если 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 .
Токен сеанса
Токены сеанса — это созданные пользователем строки, которые отслеживают вызовы автозаполнения (новые) — как вызовы, выполненные через виджет, так и программные вызовы — как «сеансы». Автозаполнение использует токены сеанса для группировки фаз запроса и выбора поиска автозаполнения пользователя в отдельный сеанс для выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос, и заканчивается, когда он выбирает место. Каждый сеанс может иметь несколько запросов, за которыми следует выбор одного места. После завершения сеанса токен больше не действителен; ваше приложение должно генерировать новый токен для каждого сеанса. Мы рекомендуем использовать токены сеанса для всех сеансов программного автозаполнения (когда вы встраиваете фрагмент или запускаете автозаполнение с помощью намерения, API позаботится об этом автоматически).
Autocomplete использует AutocompleteSessionToken для идентификации каждого сеанса. Ваше приложение должно передавать новый токен сеанса при начале каждого нового сеанса, а затем передавать этот же токен вместе с идентификатором места в последующем вызове fetchPlace() для получения сведений о месте, выбранном пользователем.
Чтобы задать параметр токена сеанса, вызовите метод setSessionToken() при построении объекта FindAutocompletePredictionsRequest .
Более подробную информацию см. в разделе Токены сеанса .

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

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

Autocomplete (New) использует IP biasing по умолчанию для управления областью поиска. При IP biasing 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());
        })
    );

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

Используйте параметр primary types , чтобы ограничить результаты запроса определенным типом, как указано в таблице 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());
        })
    );

Атрибуции

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

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

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

Котлин

Ява

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

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

Требуемые параметры

Запрос

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

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

Страны

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

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

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

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

Источник

Код региона

Токен сеанса

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

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

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

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

Атрибуции

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