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

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

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

• Добавьте виджет автозаполнения , чтобы сэкономить время разработки и обеспечить единообразие взаимодействия с пользователем.
• Get place predictions programmatically to create a customized user experience.

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

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

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

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

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

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

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

Add AutocompleteSupportFragment to an activity

To add AutocompleteSupportFragment to an activity, add a new fragment to an XML layout. For example:

<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 .
• Если вы используете фрагмент автозаполнения и вам необходимо переопределить 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. Use Autocomplete.IntentBuilder to create an intent, passing the desired Autocomplete mode.
2. Определите средство запуска результатов активности registerForActivityResult , которое можно использовать для запуска намерения и обработки прогноза выбранного пользователем места в результате.

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

The example below uses Autocomplete.IntentBuilder to create an intent to launch the autocomplete widget as an intent:

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

      

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

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

To receive a notification when the user has selected a place, define a registerForActivityResult() launcher, which launches the activity and also handles the result as shown in the following example. If the user selected a prediction, it will be delivered in the intent contained in the result object. Since the intent was built by Autocomplete.IntentBuilder , the method Autocomplete.getPlaceFromIntent() can extract the Place object from it.

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 , содержащая текст, введенный пользователем.
• Recommended: A AutocompleteSessionToken , which groups the query and selection phases of a user search into a discrete session for billing purposes. The session begins when the user starts typing a query, and concludes when they select a place.
• Recommended: A RectangularBounds object, which specifies latitude and longitude bounds to constrain results to the specified region .
• Необязательно: один или несколько двухбуквенных кодов страны (ISO 3166-1 Alpha-2), указывающих страну или страны, результаты которых должны быть ограничены.

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

  • TypeFilter.GEOCODE – возвращает только результаты геокодирования, а не компании. Используйте этот запрос, чтобы устранить неоднозначность результатов, в которых указанное местоположение может быть неопределенным.
  • TypeFilter.ADDRESS – Returns only autocomplete results with a precise address. Use this type when you know the user is looking for a fully specified 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) returns the full text of a place description. This is a combination of the primary and secondary text. Example: " Eiffel Tower, Avenue Anatole France, Paris, France ". In addition, this method lets you highlight the sections of the description that match the search with a style of your choice, using CharacterStyle . The CharacterStyle parameter is optional. Set it to null if you don't need any highlighting.
• getPrimaryText(CharacterStyle) возвращает основной текст, описывающий место. Обычно это название места. Примеры: « Эйфелева башня » и « Питт-стрит, 123 ».
• getSecondaryText(CharacterStyle) возвращает дополнительный текст описания места. Это полезно, например, в качестве второй строки при показе подсказок автодополнения. Примеры: « Авеню Анатоля Франса, Париж, Франция » и « Сидней, Новый Южный Уэльс ».
• getPlaceId() возвращает идентификатор предсказанного места. Идентификатор места — это текстовый идентификатор, который уникально идентифицирует место и может быть использован для последующего получения объекта Place . Подробнее об идентификаторах мест в Places SDK для Android см. в разделе «Подробности места» . Общую информацию об идентификаторах мест см. в разделе «Обзор идентификаторов места» .
• getPlaceTypes() returns the list of place types associated with this place.
• getDistanceMeters() returns the straight-line distance in meters between this place and the origin specified in the request.

Токены сеанса

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

The Places SDK for Android uses a AutocompleteSessionToken to identify each session. Your app should pass a new session token upon beginning each new session, then pass that same token, along with a Place ID, in the subsequent call to fetchPlace() to retrieve Place Details for the place that was selected by the user.

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

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

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

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

• To prefer results within the defined region, call setLocationBias() (some results from outside the defined region may still be returned).
• Чтобы отображать результаты только в пределах определенного региона, вызовите 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() , чтобы установить фильтр.

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

• Call setTypesFilter() and specify up to five type values from Table 1 and Table 2 shown on Place Types . Значения типа определяются константами в PlaceTypes .

• Call setTypesFilter() and specify a type collection from Table 3 shown on Place Types . The collection values are defined by the constants in PlaceTypes .

  Only a single type from Table 3 is allowed in the request. Если вы укажете значение из таблицы 3, вы не сможете указать значение из таблицы 1 или таблицы 2. Если вы это сделаете, то произойдет ошибка.

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

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

      

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

      

The following code example shows calling setTypesFilter() on an AutocompleteSupportFragment to set a filter returning only results with a precise address by specifying a type collection.

    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.

The following code example shows calling setCountries() on an AutocompleteSupportFragment , to set a filter returning only results within the specified countries.

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

      

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

      

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

Your usage of the Places API, including the Places SDK for Android, is no longer limited to a maximum number of requests per day (QPD). Однако по-прежнему применяются следующие ограничения на использование:

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

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

• Если ваше приложение использует службу автозаполнения программно, ваш пользовательский интерфейс должен либо отображать атрибут «Powered by Google», либо отображаться на карте под брендом Google.
• If your app uses the autocomplete widget no additional action is required (the required attribution is displayed by default).
• If you retrieve and display additional place information after getting a place by ID , you must display third-party attributions too.

For more details, see the documentation on attributions .

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

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

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

• The quickest way to develop a working user interface is to use the Maps JavaScript API Place Autocomplete (Legacy) widget , Places SDK for Android Place Autocomplete (Legacy) widget , or Places SDK for iOS Place Autocomplete (Legacy) UI control
• Develop an understanding of essential Place Autocomplete (Legacy) data fields from the start.
• Location biasing and location restriction fields are optional but can have a significant impact on autocomplete performance.
• Используйте обработку ошибок, чтобы обеспечить корректное ухудшение качества вашего приложения, если API возвращает ошибку.
• Убедитесь, что ваше приложение обрабатывает ситуации, когда выбор отсутствует, и предлагает пользователям возможность продолжить.

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

Basic cost optimization

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

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

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

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

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

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

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

• Add country restrictions, location biasing , and (for programmatic implementations) language preference to your Place Autocomplete (Legacy) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
• Если автозаполнение места (устаревшая версия) сопровождается картой, вы можете смещать местоположение в зависимости от области просмотра карты.
• В ситуациях, когда пользователь не выбирает одно из предсказаний Place Autocomplete (устаревшее), как правило, потому, что ни одно из этих предсказаний не является желаемым адресом результата, вы можете повторно использовать исходный пользовательский ввод, чтобы попытаться получить более релевантные результаты:
  • If you expect the user to enter only address information, reuse the original user input in a call to the Geocoding API .
  • Если вы ожидаете, что пользователь будет вводить запросы для определенного места по имени или адресу, используйте запрос Find Place (Legacy) . Если результаты ожидаются только в определенном регионе, используйте смещение местоположения .
  Другие сценарии, когда лучше всего вернуться к API геокодирования, включают:
  • Пользователи, вводящие адреса помещений, например адреса конкретных квартир или квартир в здании. Например, чешский адрес «Stroupežnického 3191/17, Praha» дает частичный прогноз в Place Autocomplete (Legacy).
  • Пользователи вводят адреса с префиксами сегментов дорог, например «23-30 29th St, Queens» в Нью-Йорке или «47-380 Kamehameha Hwy, Kaneohe» на острове Кауаи на Гавайях.

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

Although a wide variety of errors can occur, the majority of the errors your app is likely to experience are usually caused by configuration errors (for example, the wrong API key was used, or the API key was configured incorrectly), or quota errors (your app has exceeded its quota). See Usage Limits for more information about quotas.

Errors that occur in the use of the autocomplete controls are returned in the onActivityResult() callback. Call Autocomplete.getStatus() to get the status message for the result.