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

Autocomplete (New)

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

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

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

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

Интегрировать функцию Autocomplete (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);

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

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

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

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

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

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

У места может быть только один основной тип из таблицы А или таблицы Б. Например, основным типом может быть "mexican_restaurant" или "steak_house".

Запрос будет отклонен с ошибкой INVALID_REQUEST, если:
- Указано более пяти типов.
- указать неизвестный тип;
Чтобы задать параметр основных типов, вызовите метод setTypesFilter() при создании объекта FindAutocompletePredictionsRequest.
Страны

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

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

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

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

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

В следующем примере указана строка запроса "Футбол" и параметр primarytypes, чтобы ограничить результаты заведениями типа "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());
        })
    );

Оптимизация 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) должен использоваться токен сеанса (программно или встроенный в виджеты JavaScript, Android или iOS) для каждого сеанса, а также соответствующие коды Places в зависимости от того, какие поля данных о местах вы запрашиваете.¹

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

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

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

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

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

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

Выбирают ли пользователи подсказку Autocomplete (New) в среднем из числа первых четырех запросов?

Да

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

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

Нет

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

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

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

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

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

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

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

Информацию о стоимости можно найти в списках цен на платформу Google Карт.

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

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

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

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

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

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

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

Autocomplete (New)

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

Kotlin

Java

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

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

Ответы Autocomplete (New)

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

Запрос

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

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

Страны

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

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

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

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

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

Код области

Токен сеанса

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

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

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

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

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

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

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

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

Да, нужно больше сведений

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

Да

Нет

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

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

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

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

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

Kotlin

Java

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

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

Ответы Autocomplete (New)

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

Запрос

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

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

Страны

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

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

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

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

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

Код области

Токен сеанса

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

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

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

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

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

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

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

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

Да, нужно больше сведений

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

Да

Нет

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

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

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

Autocomplete (New)