Автозаполнение мест

Служба автозаполнения в Places SDK для Android возвращает прогнозы мест в ответ на поисковые запросы пользователя. По мере того, как пользователь печатает, служба автозаполнения возвращает предложения для мест, таких как компании, адреса, коды plus и точки интереса.

Добавить автозаполнение в приложение можно следующими способами:

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

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

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

Вариант 1: Внедрение AutocompleteSupportFragment

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

  1. Добавьте фрагмент в XML-макет вашей активности.
  2. Добавьте прослушиватель к вашей активности или фрагменту.

Добавить AutocompleteSupportFragment к действию

Чтобы добавить AutocompleteSupportFragment в действие, добавьте новый фрагмент в XML-макет. Например:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • По умолчанию фрагмент не имеет границы или фона. Чтобы обеспечить единообразный визуальный вид, вложите фрагмент в другой элемент макета, например CardView .
  • Если вы используете фрагмент Autocomplete и вам необходимо переопределить onActivityResult , вы должны вызвать super.onActivityResult , в противном случае фрагмент не будет работать правильно.

Добавьте PlaceSelectionListener к действию

PlaceSelectionListener обрабатывает возврат места в ответ на выбор пользователя. Следующий код показывает создание ссылки на фрагмент и добавление слушателя к вашему AutocompleteSupportFragment :

Котлин 

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

Ява 

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

Вариант 2: использование намерения для запуска действия автозаполнения

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

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

  1. Используйте Autocomplete.IntentBuilder для создания намерения, передавая желаемый режим Autocomplete .
  2. Определите средство запуска результата действия registerForActivityResult , которое можно использовать для запуска намерения и обработки прогноза выбранного пользователем места в результате.

Создать намерение автозаполнения

В примере ниже Autocomplete.IntentBuilder используется для создания намерения запустить виджет автозаполнения в качестве намерения:

Котлин 

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

Ява 

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

При использовании намерения для запуска виджета автозаполнения вы можете выбрать режим наложения или полноэкранный режим отображения. На следующих снимках экрана показаны каждый режим отображения соответственно:

При отображении в режиме наложения виджет автозаполнения накладывается на вызывающий пользовательский интерфейс.
Рисунок 1 : Виджет автозаполнения в режиме OVERLAY
При отображении в полноэкранном режиме виджет автозаполнения заполняет весь экран.
Рисунок 2 : Виджет автозаполнения в ПОЛНОЭКРАННОМ режиме

Зарегистрируйте обратный вызов для результата намерения

Чтобы получать уведомления, когда пользователь выбрал место, определите лаунчер registerForActivityResult() , который запускает активность, а также обрабатывает результат, как показано в следующем примере. Если пользователь выбрал прогноз, он будет доставлен в намерении, содержащемся в объекте результата. Поскольку намерение было создано Autocomplete.IntentBuilder , метод Autocomplete.getPlaceFromIntent() может извлечь из него объект Place.

Котлин 

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

Ява 

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

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

Вы можете создать пользовательский пользовательский интерфейс поиска в качестве альтернативы пользовательскому интерфейсу, предоставляемому виджетом автозаполнения. Для этого ваше приложение должно получать прогнозы мест программным путем. Ваше приложение может получить список прогнозируемых названий мест и/или адресов из API автозаполнения, вызвав PlacesClient.findAutocompletePredictions() , передав объект FindAutocompletePredictionsRequest со следующими параметрами:

  • Обязательно: строка query , содержащая текст, введенный пользователем.
  • Рекомендуется: AutocompleteSessionToken , который группирует фазы запроса и выбора пользовательского поиска в отдельный сеанс для выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос, и заканчивается, когда он выбирает место.
  • Рекомендуется: объект RectangularBounds , который указывает границы широты и долготы, чтобы ограничить результаты указанным регионом .
  • Необязательно: один или несколько двухбуквенных кодов страны (ISO 3166-1 Alpha-2), указывающих страну или страны, к которым должны быть ограничены результаты.

  • Необязательно: TypeFilter , который можно использовать для ограничения результатов указанным типом места. Поддерживаются следующие типы мест:

    • TypeFilter.GEOCODE – Возвращает только результаты геокодирования, а не предприятия. Используйте этот запрос для устранения неоднозначности результатов, где указанное местоположение может быть неопределенным.
    • TypeFilter.ADDRESS – Возвращает только результаты автозаполнения с точным адресом. Используйте этот тип, когда знаете, что пользователь ищет полностью указанный адрес.
    • TypeFilter.ESTABLISHMENT – Возвращает только те места, которые являются предприятиями.

    • TypeFilter.REGIONS – Возвращает только места, соответствующие одному из следующих типов:

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES – возвращает только результаты, соответствующие LOCALITY или ADMINISTRATIVE_AREA_LEVEL_3 .

  • Необязательно: LatLng , указывающий местоположение источника для запроса. При вызове setOrigin() служба возвращает расстояние в метрах ( distanceMeters ) от указанного источника для каждого автозаполнения в ответе.

Информацию о типах мест см. в руководстве по типам мест .

В примере ниже показан полный вызов PlacesClient.findAutocompletePredictions() .

Котлин 

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

Ява 

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

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

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

  • getFullText(CharacterStyle) возвращает полный текст описания места. Это комбинация основного и дополнительного текста. Пример: " Eiffel Tower, Avenue Anatole France, Paris, France ". Кроме того, этот метод позволяет вам выделять разделы описания, соответствующие поиску, с помощью стиля по вашему выбору, используя CharacterStyle . Параметр CharacterStyle является необязательным. Установите его в null, если вам не нужно выделение.
  • getPrimaryText(CharacterStyle) возвращает основной текст, описывающий место. Обычно это название места. Примеры: " Eiffel Tower " и " 123 Pitt Street ".
  • getSecondaryText(CharacterStyle) возвращает вспомогательный текст описания места. Это полезно, например, в качестве второй строки при показе подсказок автозаполнения. Примеры: " Avenue Anatole France, Paris, France " и " Sydney, New South Wales ".
  • getPlaceId() возвращает идентификатор предсказанного места. Идентификатор места — это текстовый идентификатор, который однозначно идентифицирует место, и который можно использовать для повторного извлечения объекта Place позже. Для получения дополнительной информации об идентификаторах мест в Places SDK для Android см. Place Details . Для получения общей информации об идентификаторах мест см. Place ID Overview .
  • getPlaceTypes() возвращает список типов мест, связанных с данным местом.
  • getDistanceMeters() возвращает расстояние по прямой в метрах между данным местом и точкой отсчета, указанной в запросе.

Сеансовые токены

Токены сеанса группируют фазы запроса и выбора поиска автозаполнения пользователя в отдельный сеанс для выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос, и заканчивается, когда он выбирает место. Каждый сеанс может иметь несколько запросов, за которыми следует один выбор места. После завершения сеанса токен больше недействителен; ваше приложение должно генерировать новый токен для каждого сеанса. Мы рекомендуем использовать токены сеанса для всех сеансов программного автозаполнения (когда вы встраиваете фрагмент или запускаете автозаполнение с помощью намерения, API позаботится об этом автоматически).

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

Узнайте больше о токенах сеанса .

Ограничить результаты автозаполнения

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

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

  • Чтобы отдать предпочтение результатам в пределах определенного региона, вызовите setLocationBias() (некоторые результаты за пределами определенного региона все равно могут быть возвращены).
  • Чтобы отобразить результаты только в пределах определенного региона, вызовите setLocationRestriction() (будут возвращены только результаты в пределах определенного региона).
  • Чтобы вернуть только результаты, соответствующие определенному типу места, вызовите setTypesFilter() (например, указание TypeFilter.ADDRESS вернет только результаты с точным адресом).
  • Чтобы вернуть результаты только в пределах пяти указанных стран, вызовите setCountries() . Страны должны быть переданы как двухсимвольный код страны , совместимый с ISO 3166-1 Alpha-2 .

Смещение результатов в сторону определенного региона

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

Котлин 

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

Ява 

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

Ограничить результаты определенным регионом

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

Котлин 

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

Ява 

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

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

Фильтрация результатов по типам мест или коллекции типов

Вы можете ограничить результаты запроса автозаполнения, чтобы они возвращали только определенный тип места. Укажите фильтр, используя типы мест или коллекцию типов, перечисленных в таблицах 1, 2 и 3 в разделе Типы мест . Если ничего не указано, возвращаются все типы.

Чтобы отфильтровать результаты автозаполнения, вызовите setTypesFilter() , чтобы установить фильтр.

Чтобы указать тип или фильтр коллекции типов:

  • Вызовите setTypesFilter() и укажите до пяти значений типа из Таблицы 1 и Таблицы 2, показанных в Place Types . Значения типа определяются константами в PlaceTypes .

  • Вызовите setTypesFilter() и укажите коллекцию типов из Таблицы 3, показанной в Place Types . Значения коллекции определяются константами в PlaceTypes .

    В запросе допускается только один тип из Таблицы 3. Если указать значение из Таблицы 3, нельзя указать значение из Таблицы 1 или Таблицы 2. Если вы это сделаете, возникнет ошибка.

В следующем примере кода вызывается setTypesFilter() для AutocompleteSupportFragment и указывается несколько значений типа.

Котлин 

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

Ява 

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

В следующем примере кода показан вызов setTypesFilter() для AutocompleteSupportFragment для установки фильтра, возвращающего только результаты с точным адресом, путем указания коллекции типов.

Котлин 

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Ява 

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

В следующем примере кода показан вызов setTypesFilter() в IntentBuilder для установки фильтра, возвращающего только результаты с точным адресом, путем указания коллекции типов.

Котлин 

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

Ява 

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

Фильтровать результаты по стране

Чтобы отфильтровать результаты автозаполнения по пяти странам, вызовите setCountries() для установки кода страны . Затем передайте фильтр фрагменту или намерению. Страны должны быть переданы как двухсимвольный код страны , совместимый с ISO 3166-1 Alpha-2.

В следующем примере кода показан вызов setCountries() для AutocompleteSupportFragment для установки фильтра, возвращающего результаты только в указанных странах.

Котлин 

    autocompleteFragment.setCountries("AU", "NZ")

Ява 

    autocompleteFragment.setCountries("AU", "NZ");

Ограничения по использованию

Ваше использование API Places, включая Places SDK для Android, больше не ограничено максимальным количеством запросов в день (QPD). Однако следующие ограничения по использованию по-прежнему действуют:

  • Ограничение скорости составляет 6000 QPM (запросов в минуту). Рассчитывается как сумма клиентских и серверных запросов для всех приложений, использующих учетные данные одного и того же проекта.

Отображение атрибуции в вашем приложении

  • Если ваше приложение использует службу автозаполнения программно, ваш пользовательский интерфейс должен либо отображать атрибуцию «Powered by Google», либо отображаться на карте с логотипом Google.
  • Если ваше приложение использует виджет автозаполнения, никаких дополнительных действий не требуется (требуемая атрибуция отображается по умолчанию).
  • Если вы извлекаете и отображаете дополнительную информацию о месте после получения места по идентификатору , вы также должны отображать сторонние атрибуции.

Более подробную информацию см. в документации по атрибуции .

Оптимизация автозаполнения (устаревшая версия)

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

Вот некоторые общие рекомендации:

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

Лучшие практики оптимизации затрат

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

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

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

Рассмотрите программную реализацию Place Autocomplete (Legacy) для доступа к ценам Per Request и запроса результатов Geocoding API о выбранном месте вместо Place Details (Legacy). Цены Per Request в сочетании с Geocoding API более рентабельны, чем цены Per Session (на основе сеанса), если выполняются оба следующих условия:

  • Если вам нужны только широта/долгота или адрес выбранного пользователем места, API геокодирования предоставит эту информацию менее чем за один вызов Place Details (Legacy).
  • Если пользователи выбирают прогноз автозаполнения в среднем в течение четырех запросов прогнозов Place Autocomplete (Legacy) или менее, цена за запрос может быть более рентабельной, чем цена за сеанс.
Для получения помощи в выборе реализации Place Autocomplete (Legacy), которая соответствует вашим потребностям, выберите вкладку, соответствующую вашему ответу на следующий вопрос.

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

Да, нужно больше подробностей

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

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

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

  1. Идентификатор места из ответа Place Autocomplete (Legacy)
  2. Токен сеанса, используемый в запросе Place Autocomplete (Legacy)
  3. Параметр fields указывающий место расположения необходимых вам полей данных

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

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

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

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

Да

Реализуйте функцию автозаполнения мест (устаревшую) программно без токенов сеанса и вызовите API геокодирования для выбранного прогноза места.
Geocoding API предоставляет адреса и координаты широты/долготы. Выполнение четырех запросов Place Autocomplete (Legacy) - Per Request плюс вызов Geocoding API о выбранном прогнозе места стоит меньше, чем стоимость Per Session Place Autocomplete (Legacy) за сеанс. 1

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

Нет

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

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

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

  1. Идентификатор места из ответа Place Autocomplete (Legacy)
  2. Токен сеанса, используемый в запросе Place Autocomplete (Legacy)
  3. Параметр fields , указывающий поля основных данных , такие как адрес и геометрия.

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

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

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

  1. Стоимость можно узнать в прайс-листах платформы Google Карт .

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

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

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

Поиск неисправностей

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

Ошибки, возникающие при использовании элементов управления автозаполнением, возвращаются в обратном вызове onActivityResult() . Вызовите Autocomplete.getStatus() , чтобы получить сообщение о состоянии для результата.