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

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

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

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

• Добавьте виджет автозаполнения , чтобы сэкономить время разработки и обеспечить единообразие взаимодействия с пользователем.
• Получайте прогнозы мест программно , чтобы создать индивидуальный пользовательский интерфейс.

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

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

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

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

Вариант 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 .
• Если вы используете фрагмент автозаполнения и вам необходимо переопределить 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. Используйте намерение для запуска действия автозаполнения.

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

Примечание. Эти шаги не нужны, если вы встраиваете фрагмент .

Внимание: НЕ запускайте AutcompleteActivity напрямую. Вместо этого используйте намерение запустить Autocomplete ( PlaceAutocomplete в библиотеке совместимости).

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

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. Виджет автозаполнения в режиме НАЛОЖЕНИЕ.

Рис. 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) возвращает полный текст описания места. Это сочетание первичного и вторичного текста. Пример: « Эйфелева башня, авеню Анатоля Франса, Париж, Франция ». Кроме того, этот метод позволяет выделить разделы описания, соответствующие поиску, стилем по вашему выбору, используя CharacterStyle . Параметр CharacterStyle является необязательным. Установите для него значение null, если вам не нужна подсветка.
• getPrimaryText(CharacterStyle) возвращает основной текст, описывающий место. Обычно это название места. Примеры: « Эйфелева башня » и « Питт-стрит, 123 ».
• getSecondaryText(CharacterStyle) возвращает вспомогательный текст описания места. Это полезно, например, в качестве второй строки при отображении подсказок автозаполнения. Примеры: « Авеню Анатоль Франс, Париж, Франция » и « Сидней, Новый Южный Уэльс ».
• getPlaceId() возвращает идентификатор предсказанного места. Идентификатор места — это текстовый идентификатор, однозначно идентифицирующий место, который можно использовать для повторного получения объекта Place позже. Дополнительную информацию об идентификаторах мест в Places SDK для Android см. в разделе «Сведения о месте» . Общую информацию об идентификаторах мест см. в обзоре идентификаторов мест .
• getPlaceTypes() возвращает список типов мест, связанных с этим местом.
• getDistanceMeters() возвращает расстояние по прямой в метрах между этим местом и началом координат, указанным в запросе.

Вы можете использовать CancellationToken , чтобы попытаться отменить запрос к любому из классов запросов (например, FetchPlaceRequest ). Отмена производится в максимальном порядке. После подачи запроса на отмену ответ не будет получен. Выдача токена отмены НЕ гарантирует, что конкретный запрос будет отменен, и с вас все равно может взиматься плата за запрос, даже если ответ не будет получен .

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

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

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

Оптимизация автозаполнения мест

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Да

Реализуйте автозаполнение мест программно без токенов сеанса и вызовите API геокодирования для прогнозирования выбранного места.
API геокодирования предоставляет адреса и координаты широты и долготы за 0,005 доллара США за запрос. Выполнение четырех запросов автозаполнения места — по запросу стоит 0,01132 доллара США, поэтому общая стоимость четырех запросов плюс вызов API геокодирования для прогнозирования выбранного места составит 0,01632 доллара США, что меньше, чем цена автозаполнения за сеанс, составляющая 0,017 доллара США за сеанс. ¹

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

Нет

Используйте автозаполнение мест на основе сеанса с подробными сведениями о месте.
Поскольку среднее количество запросов, которые вы ожидаете сделать до того, как пользователь выберет прогноз автозаполнения места, превышает стоимость цены за сеанс, ваша реализация автозаполнения места должна использовать токен сеанса как для запросов автозаполнения места, так и для соответствующего запроса сведений о месте для Общая стоимость 0,017 доллара США за сеанс . ¹

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

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

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

Рассмотрите возможность задержки запросов автозаполнения мест.
Вы можете использовать такие стратегии, как задержка запроса Place Autocomplete до тех пор, пока пользователь не введет первые три или четыре символа, чтобы ваше приложение делало меньше запросов. Например, выполнение запросов автозаполнения места для каждого символа после того, как пользователь ввел третий символ, означает, что если пользователь вводит семь символов, а затем выбирает прогноз, для которого вы делаете один запрос API геокодирования, общая стоимость составит 0,01632 доллара США (4 * 0,00283 доллара США). За запрос + 0,005 доллара США за геокодирование). ¹

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

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

---

1. Стоимость указана здесь в долларах США. Полную информацию о ценах можно найти на странице оплаты платформы Google Maps .

Рекомендации по повышению производительности

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

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

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

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

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