Место автозаполнения

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Выберите платформу: Android iOS JavaScript Web Service

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

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

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

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

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

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

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

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

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

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

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

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

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

Ява


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

      

Котлин


    // 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")
        }
    })

      

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

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

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

  1. Используйте Autocomplete.IntentBuilder , чтобы создать намерение, передав нужный режим Autocomplete . Намерение должно вызывать startActivityForResult , передавая код запроса, идентифицирующий намерение.
  2. Переопределите обратный вызов onActivityResult , чтобы получить выбранное место.

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

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

Ява


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Котлин


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

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

Переопределить обратный вызов onActivityResult

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

Ява


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Котлин


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

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

Вы можете создать собственный пользовательский интерфейс поиска в качестве альтернативы пользовательскому интерфейсу, предоставляемому виджетом автозаполнения. Для этого ваше приложение должно программно получать прогнозы мест. Ваше приложение может получить список предполагаемых названий мест и/или адресов из 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 в метрах ( 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()).
    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(TypeFilter.ADDRESS.toString()))
        .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());
        }
    });

      

Котлин


    // 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(TypeFilter.ADDRESS.toString()))
            .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)
            }
        }

      

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

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

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

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

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

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

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

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

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

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

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

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

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

Ява


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

      

Котлин


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

      

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

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

Ява


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

      

Котлин


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

      

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

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

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

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

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

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

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

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

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

Ява


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

      

Котлин


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

      

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

Ява


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Котлин


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

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

Ява


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

      

Котлин


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

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

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

Ява


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

      

Котлин


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

      

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

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

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

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

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

Подробнее см. в документации по атрибуциям .

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

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

Вот несколько общих рекомендаций:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Да

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

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

Нет

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

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

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

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

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

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

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


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

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

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

  • Добавьте ограничения по странам, смещение местоположения и (для программных реализаций) языковые предпочтения в свою реализацию автозаполнения мест. Языковые предпочтения не требуются для виджетов, поскольку они выбирают языковые настройки в браузере пользователя или на мобильном устройстве.
  • Если автозаполнение места сопровождается картой, вы можете изменить местоположение по области просмотра карты.
  • В ситуациях, когда пользователь не выбирает один из прогнозов автозаполнения, как правило, потому, что ни один из этих прогнозов не является желаемым адресом результата, вы можете повторно использовать исходный пользовательский ввод, чтобы попытаться получить более релевантные результаты:
    • Если вы ожидаете, что пользователь введет только адресную информацию, повторно используйте исходный пользовательский ввод в вызове API геокодирования .
    • Если вы ожидаете, что пользователь будет вводить запросы для определенного места по имени или адресу, используйте запрос «Найти место ». Если результаты ожидаются только в определенном регионе, используйте смещение местоположения .
    Другие сценарии, когда лучше всего вернуться к API геокодирования, включают:
    • Пользователи, вводящие адреса субпомещений в странах, отличных от Австралии, Новой Зеландии или Канады. Например, адрес в США «123 Bowdoin St # 456, Boston MA, USA» не поддерживается автозаполнением. (Автозаполнение поддерживает адреса помещений только в Австралии, Новой Зеландии и Канаде. Поддерживаемые форматы адресов в этих трех странах включают «9/321 Pitt Street, Sydney, New South Wales, Australia» или «14/19 Langana Avenue, Browns Bay, Auckland». , Новая Зеландия» или «145-112 Renfrew Dr, Markham, Ontario, Canada».)
    • Пользователи, вводящие адреса с префиксами дорожных сегментов, такими как «23-30 29th St, Queens» в Нью-Йорке или «47-380 Kamehameha Hwy, Kaneohe» на острове Кауаи на Гавайях.

Исправление проблем

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

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