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

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

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

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

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

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

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

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

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

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

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

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

В следующих примерах показано, как добавить виджет автозаполнения, используя 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)

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
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);

Настройте тему

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

Вы можете определить параметры переопределения темы в файле …/res/values/themes.xml . Например:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Затем вы можете сослаться на переопределенные стили, вызвав setAutocompleteUiCustomization :

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

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

Ваше приложение может получить список предполагаемых названий мест и/или адресов из 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) возвращает дополнительный текст описания места. Это полезно, например, в качестве второй строки при отображении подсказок автозаполнения. Примеры: " Avenue Anatole France, Paris, France " и " Sydney, New South Wales ".
getPlaceId() возвращает идентификатор места, которое было предсказано. Идентификатор места — это текстовый идентификатор, который однозначно определяет место и может быть использован для повторного получения объекта Place позже. Дополнительную информацию об идентификаторах мест в автозаполнении см. в разделе « Подробная информация о местах (новое)» . Общую информацию об идентификаторах мест см. в разделе « Обзор идентификаторов мест» .
getTypes() возвращает список типов мест, связанных с данным местом.
getDistanceMeters() возвращает расстояние по прямой в метрах между этим местом и начальной точкой, указанной в запросе.

Необходимые параметры

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

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

Основные типы
Список, содержащий до пяти значений типов из таблицы типов A или B, используется для фильтрации мест, возвращаемых в ответе. Место должно соответствовать одному из указанных основных значений типа, чтобы быть включенным в ответ.
Для каждого заведения может быть связан только один основной тип из таблиц типов A или B. Например, основным типом может быть "mexican_restaurant" или "steak_house" .
Запрос отклоняется с ошибкой INVALID_REQUEST , если:
- Указано более пяти типов.
- Все нераспознанные типы указаны.
Чтобы задать основной параметр типов, вызовите метод setTypesFilter() при создании объекта FindAutocompletePredictionsRequest .
Страны
Включать только результаты из указанного списка стран, представленного в виде списка, содержащего до 15 двухсимвольных значений ccTLD («домен верхнего уровня») . Если этот список опущен, ограничения на ответ не применяются. Например, чтобы ограничить регионы Германией и Францией:
Если указать одновременно locationRestriction и includedRegionCodes , результаты будут расположены в области пересечения этих двух настроек.
Чтобы задать параметр countries, вызовите метод 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 доступен только в автозаполнении (новый режим).
  - Если low = high , то область просмотра состоит из этой единственной точки.
  - Если low.longitude > high.longitude , диапазон долготы инвертируется (область просмотра пересекает линию долготы в 180 градусов).
  - Если low.longitude = -180 градусов и high.longitude = 180 градусов, то область просмотра будет включать все долготы.
  - Если low.longitude = 180 градусов и high.longitude = -180 градусов, то диапазон долготы пуст.
  Необходимо заполнить поля low и high , при этом отображаемый прямоугольник не может быть пустым. Пустой экран приводит к ошибке.
Источник
Начальная точка, от которой рассчитывается расстояние по прямой до пункта назначения (доступна с помощью getDistanceMeters() ). Если это значение опущено, расстояние по прямой не будет возвращено. Должно быть указано в виде координат широты и долготы:
Чтобы задать параметр origin, вызовите метод setOrigin() при создании объекта FindAutocompletePredictionsRequest .
код региона
Региональный код, используемый для форматирования ответа, включая форматирование адреса, указывается в виде двухсимвольного значения ccTLD («домен верхнего уровня») . Большинство кодов ccTLD идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, ccTLD Соединенного Королевства — «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());
        })
    );

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

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

В следующем примере задается строка запроса "Футбол", а параметр primary types используется для ограничения результатов только заведениями типа "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" .

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

Если в запросе указан параметр origin в виде координат широты и долготы, 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());
        })
    );

Оптимизация автозаполнения (новая функция)

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

Вот несколько общих рекомендаций:

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

Передовые методы оптимизации затрат

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

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

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

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

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

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

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

Да, требуется более подробная информация.

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

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

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

Идентификатор места из ответа автозаполнения (нового).
Токен сессии, используемый в запросе автозаполнения (нового запроса).
Параметр fields указывает необходимые поля данных для автозаполнения (нового файла).

Нет, достаточно указать адрес и местоположение.

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

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

В среднем, пользователи выбирают вариант автозаполнения (новый) в четырех или менее запросах?

Да

Реализуйте автозаполнение (новое) программным способом без использования токенов сессии и вызывайте API геокодирования для прогнозирования выбранного места.
API геокодирования предоставляет адреса и координаты широты/долготы. Выполнение четырех запросов автозаполнения плюс вызов API геокодирования для прогнозирования выбранного места обходится дешевле, чем стоимость автозаполнения (нового) за сессию. ¹

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

Нет

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

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

Идентификатор места из ответа автозаполнения (нового).
Токен сессии, используемый в запросе автозаполнения (нового запроса).
Параметр fields задает такие поля, как адрес и геометрия.

Рассмотрите возможность отложить запросы автозаполнения (новые).
Вы можете использовать такие стратегии, как задержка запроса автозаполнения (нового варианта) до тех пор, пока пользователь не введёт первые три или четыре символа, чтобы ваше приложение выполняло меньше запросов. Например, если запросы автозаполнения (нового варианта) выполняются для каждого символа после того, как пользователь введёт третий символ, это означает, что если пользователь введёт семь символов, а затем выберет предсказание, для которого вы выполните один запрос к API геокодирования, общая стоимость составит 4 запроса автозаполнения (нового варианта) + геокодирование. ¹

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

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

Информацию о стоимости можно найти в прайс-листах платформы Google Maps .

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

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

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

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

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

Предупреждение: Если radius не указан, параметр location игнорируется.

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

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

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

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

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

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

Котлин

Java

Настройте тему

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

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

Необходимые параметры

Запрос

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

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

Страны

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

Смещение в сторону местоположения или ограничение местоположения

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

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

Источник

код региона

токен сессии

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

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

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

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

Оптимизация автозаполнения (новая функция)

Передовые методы оптимизации затрат

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

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

Да, требуется более подробная информация.

Нет, достаточно указать адрес и местоположение.

Да

Нет

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

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

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

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