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

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

Если ваш платежный адрес находится в Европейской экономической зоне, с 8 июля 2025 г. на использование вами Сервисов будут распространяться Условия использования платформы Google Карт в ЕЭЗ. Функциональность зависит от региона. Подробнее…

Автозаполнение мест (устаревшая версия) возвращает подсказки мест в ответ на поисковые запросы пользователей. По мере ввода текста сервис автозаполнения предлагает варианты мест, например компаний, адресов, кодов Plus Code и объектов инфраструктуры.

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

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

Устарело. Виджет автозаполнения Places API (устаревшей версии) больше не поддерживается. Перейдите на новую версию Autocomplete, чтобы использовать новый виджет Autocomplete или получать подсказки мест программно. Чтобы использовать новый виджет автозаполнения, необходимо включить Places API (New) для ключа API в консоли Google Cloud.

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

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

Для добавления виджета службы подсказки мест в ваше приложение предусмотрены два следующих варианта.

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

Вариант 1. Встроить AutocompleteSupportFragment

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

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

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

Чтобы добавить AutocompleteSupportFragment в объект activity, добавьте новый фрагмент в шаблон 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:

Kotlin

    // 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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Java

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

    // Specify the types of place data to return.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

      

Вариант 2. Запуск автозаполнения с помощью намерения

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

Примечание. Эти действия не требуются, если вы встраиваете фрагмент.

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

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

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

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

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

Kotlin

    // 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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

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

    startAutocomplete.launch(intent)

      

Java

    // 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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

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

      

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

Рисунок 1. Виджет Autocomplete в режиме OVERLAY

Рисунок 2. Виджет автозаполнения в полноэкранном режиме

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

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

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java

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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                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().

Kotlin

    // 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.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

      

Java

    // 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(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

      

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

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

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

Примечание. Подробную информацию об инициализации PlacesClient можно найти в статье Инициализация клиента Places API.

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

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

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

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

Совет. Если в вашем приложении используется виджет Autocomplete, вам не обязательно реализовывать сеансы, поскольку он обрабатывает их автоматически в фоновом режиме.

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

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

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

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

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

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

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

Kotlin

        autocompleteFragment.setLocationBias(bounds)

      

Java

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

      

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

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

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

      

Java

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

      

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

Как фильтровать результаты по типу места или коллекции типов

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

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

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

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

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

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

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

Kotlin

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

      

Java

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

      

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

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

      

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

Kotlin

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

      

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

      

Как фильтровать результаты по стране

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

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

Kotlin

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

      

Java

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

      

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

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

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

Указание авторства в приложении

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

Подробную информацию можно найти в документации по атрибуции.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Да

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

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

Нет

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

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

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

Устранение неполадок

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

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