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

Autocomplete (New)

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

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

Новая версия Autocomplete возвращает подсказки мест в ответ на запрос, содержащий строку текстового поиска и географические границы, определяющие область поиска. Автозаполнение может обрабатывать полные слова и их части, предлагая подходящие названия мест, адреса и коды Plus Code. Пока пользователь вводит текст, приложение может передавать запросы и сразу же предлагать похожие варианты.

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

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

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

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

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

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

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

В примерах ниже показано, как добавить виджет автозаполнения мест на Kotlin и Java.

Kotlin

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

Как настроить тему

При создании экземпляра Autocomplete можно указать тему, которая переопределит все атрибуты стиля по умолчанию. Вы можете настроить цвета, типографику, интервалы, границы и углы компонента автозаполнения мест. Значение по умолчанию – 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.

Ответы Autocomplete (New)

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() – расстояние по прямой в метрах между этим местом и пунктом отправления, указанным в запросе.

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

Запрос

Текстовая строка, по которой выполняется поиск. Укажите полные слова и их части, названия мест, адреса и коды Plus Code. На основе этой строки сервис Autocomplete (New) возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.

Чтобы задать параметр запроса, вызовите метод setQuery() при создании объекта FindAutocompletePredictionsRequest.

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

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

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

С местом может быть связан только один основной тип из таблицы A или таблицы B. Например, основным типом может быть "mexican_restaurant" или "steak_house".

Запрос отклоняется с ошибкой INVALID_REQUEST, если:

Указано более пяти типов.
указать неизвестный тип;

Чтобы задать параметр основных типов, вызовите метод setTypesFilter() при создании объекта FindAutocompletePredictionsRequest.

Страны

Включать в результаты только данные из указанных стран. Можно указать до 15 национальных доменов верхнего уровня в виде двухсимвольных значений. Если этот параметр не указан, к ответу не применяются никакие ограничения. Например, чтобы ограничить регионы Германией и Францией:

Если вы укажете и locationRestriction, и includedRegionCodes, то результаты будут находиться в области пересечения двух настроек.

Чтобы задать параметр countries, вызовите метод setCountries() при создании объекта FindAutocompletePredictionsRequest.

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

Смещение символа Юникода, начинающееся с нуля и указывающее на позицию курсора в запросе. Положение курсора может влиять на возвращаемые подсказки. Если значение не указано, по умолчанию используется длина запроса.

Чтобы задать параметр смещения входных данных, вызовите метод setInputOffset() при создании объекта FindAutocompletePredictionsRequest.

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

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

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

Определяет область поиска. Это местоположение служит ориентиром, а не ограничением, поэтому результаты за пределами указанной области все равно могут быть возвращены.

Чтобы задать параметр предпочтительного местоположения, вызовите метод setLocationBias() при создании объекта FindAutocompletePredictionsRequest.
Ограничение местоположений

Определяет область поиска. Результаты за пределами указанной области не возвращаются.

Чтобы задать параметр ограничения местоположения, вызовите метод setLocationRestriction() при создании объекта FindAutocompletePredictionsRequest.

Укажите регион для смещения или ограничения местоположения в виде прямоугольной области просмотра или круга.

Круг определяется центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50 000,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()). Если это значение не указано, расстояние по прямой не возвращается. Указывается в виде координат широты и долготы:

Чтобы задать параметр origin, вызовите метод setOrigin() при создании объекта FindAutocompletePredictionsRequest.

Код области

Код региона, используемый для форматирования ответа, включая форматирование адреса, указанный в виде двухсимвольного значения ccTLD ("домен верхнего уровня"). Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для Соединенного Королевства Великобритании и Северной Ирландии).

Если вы укажете неверный код региона, API вернет ошибку INVALID_ARGUMENT. Параметр может влиять на результаты в соответствии с действующим законодательством.

Чтобы задать параметр кода региона, вызовите метод setRegionCode() при создании объекта FindAutocompletePredictionsRequest.

Токен сеанса

Токены сеансов – это создаваемые пользователем строки, которые отслеживают вызовы Autocomplete (New) (как через виджет, так и программные) в качестве сеансов. Функция автозаполнения использует токены сеансов, чтобы сгруппировать этапы запроса и выбора выполняемого пользователем поиска с функцией автозаполнения в отдельный сеанс для выставления счетов. Сеанс начинается в тот момент, когда пользователь начинает вводить запрос, а завершается тогда, когда он выбирает место. В каждом сеансе может быть несколько запросов, после которых следует выбор одного места. Когда сеанс завершается, токен перестает быть действительным. Ваше приложение должно создавать новый токен для каждого сеанса. Рекомендуем использовать токены сеансов для всех сеансов автозаполнения, выполняемых программно. Если вы встраиваете фрагмент или запускаете автозаполнение с помощью намерения, API делает это автоматически.

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

Чтобы задать параметр токена сеанса, вызовите метод setSessionToken() при создании объекта FindAutocompletePredictionsRequest.

Подробнее о токенах сеансов…

Примеры использования новой версии Autocomplete

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

По умолчанию в Autocomplete (New) для управления областью поиска используется смещение по 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. Вы можете указать массив, содержащий до пяти значений. Если его не указать, будут возвращены все типы.

В примере ниже указана строка запроса "Soccer" и используется параметр 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());
        })
    );

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

Оптимизация Autocomplete (New)

В этом разделе приведены рекомендации по эффективному использованию сервиса Autocomplete (New).

Рассмотрим некоторые общие рекомендации.

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

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

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

Дополнительная оптимизация затрат

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

Если вам нужны только широта и долгота или адрес выбранного пользователем места, получить эту информацию с помощью Geocoding API дешевле, чем вызывать Place Details (New).
Если пользователи выбирают подсказку функции автозаполнения в среднем из первых четырех запросов подсказок Autocomplete (New) или из меньшего числа, тариф Per Request может быть выгоднее, чем Per Session.

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

Что нужно для подачи заявки	Среднее количество запросов Autocomplete (New), прежде чем пользователь выберет подсказку	Рекомендуемые решения
Информация о месте, кроме адреса и местоположения, например название, статус компании или часы работы.	Не ограничено	Автозаполнение на основе сеансов (новое) с информацией о местах (новое)
Только адрес и широта и долгота выбранной подсказки	Четыре или меньше	Автозаполнение (новая версия) с оплатой за запрос и Geocoding API
Только адрес и широта и долгота выбранной подсказки	Больше четырех	Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

Возможно, для вашего приложения Geocoding API будет более выгодным вариантом, чем информация о местах (New). Это зависит от того, насколько эффективно вы используете Autocomplete (New). Эффективность функции автозаполнения (новый вариант) в каждом приложении зависит от того, какие запросы вводят пользователи, где используется приложение и реализованы ли рекомендации по оптимизации производительности.

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

Автозаполнение (Новое) на основе сеансов с информацией о местах (Новое)

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

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

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

идентификатор места из ответа Autocomplete (New);
токен сеанса, использованный в запросе Autocomplete (New);
Параметр fields, указывающий нужные поля данных Autocomplete (New).

Оплата за запрос Autocomplete (New) с Geocoding API

Реализуйте Autocomplete (New) программно без токенов сеансов и вызывайте Geocoding API для выбранной подсказки места.
Geocoding API предоставляет адреса и координаты широты и долготы. Четыре запроса Autocomplete вместе с вызовом Geocoding API о выбранной подсказке места стоят меньше, чем один сеанс Autocomplete (New)¹.

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные подсказки, вводя минимальное количество символов.

Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

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

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

идентификатор места из ответа Autocomplete (New);
токен сеанса, использованный в запросе Autocomplete (New);
Параметр fields, указывающий поля, например адрес и геометрические данные.

Рассмотрите возможность откладывать запросы Autocomplete (New)
Вы можете попробовать различные стратегии, например откладывать запрос Autocomplete (New), пока пользователь не введет первые три или четыре символа, чтобы ваше приложение совершало меньше запросов. Например, если вы отправляете запросы Autocomplete (New) для каждого символа после того, как пользователь ввел третий символ, то, если пользователь введет семь символов, а затем выберет подсказку, для которой вы отправите один запрос Geocoding API, общая стоимость будет равна стоимости четырех запросов Autocomplete (New) Per Request и одного запроса Geocoding API¹.

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

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные подсказки, вводя меньше символов.

Цены указаны в прейскурантах платформы Google Карт.

Приоритет местоположения

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

Внимание! Если параметр radius не указан, параметр location игнорируется.

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

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

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

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

Autocomplete (New)

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

Kotlin

Java

Как настроить тему

Как программно получить подсказки мест

Ответы Autocomplete (New)

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

Запрос

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

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

Страны

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

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

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

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

Происхождение

Код области

Токен сеанса

Примеры использования новой версии Autocomplete

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

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

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

Оптимизация Autocomplete (New)

Рекомендации по оптимизации затрат

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

Дополнительная оптимизация затрат

Автозаполнение (Новое) на основе сеансов с информацией о местах (Новое)

Оплата за запрос Autocomplete (New) с Geocoding API

Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

Рекомендации по повышению эффективности

Приоритет местоположения

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

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

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

Kotlin

Java

Как настроить тему

Как программно получить подсказки мест

Ответы Autocomplete (New)

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

Запрос

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

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

Страны

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

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

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

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

Происхождение

Код области

Токен сеанса

Примеры использования новой версии Autocomplete

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

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

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

Оптимизация Autocomplete (New)

Рекомендации по оптимизации затрат

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

Дополнительная оптимизация затрат

Автозаполнение (Новое) на основе сеансов с информацией о местах (Новое)

Оплата за запрос Autocomplete (New) с Geocoding API

Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

Рекомендации по повышению эффективности

Приоритет местоположения

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

Autocomplete (New)