Все готово!

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

Активация Google Places API for Android

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Places API for Android
  3. Создание соответствующих ключей

Подсказки мест

Служба подсказки мест в Google Places API for Android возвращает список подсказок мест в ответ на пользовательские поисковые запросы. Когда пользователь набирает текст, служба подсказки мест выдает предполагаемые варианты для различных мест, таких как организации, адреса и достопримечательности.

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

Добавление виджета службы подсказки мест

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

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

Вариант 1: встраивание PlaceAutocompleteFragment или SupportPlaceAutocompleteFragment

Чтобы добавить PlaceAutocompleteFragment в приложение, выполните следующие шаги.

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

Добавление PlaceAutocompleteFragment в операцию

Чтобы добавить PlaceAutocompleteFragment в операцию, добавьте новый фрагмент с именем com.google.android.gms.location.places.ui.PlaceAutocompleteFragment в макет XML. Например:

<fragment
  android:id="@+id/place_autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.gms.location.places.ui.PlaceAutocompleteFragment"
  />

Примечание. По умолчанию у фрагмента нет границы или фона. Чтобы обеспечить соответствующий внешний вид, разместите фрагмент внутри другого элемента макета, такого как CardView.

Добавление PlaceSelectionListener в операцию

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

PlaceAutocompleteFragment autocompleteFragment = (PlaceAutocompleteFragment)
getFragmentManager().findFragmentById(R.id.place_autocomplete_fragment);

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

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

Использование SupportPlaceAutocompleteFragment (старые платформы)

Для поддержки объектов PlaceAutocompleteFragment для Google Places API требуется уровень API 12 или выше. Если вы разрабатываете приложение для уровня ниже API 12, то для доступа к этим же функциональным возможностям можно использовать класс SupportPlaceAutocompleteFragment. Вам также необходимо включить вспомогательную библиотеку Android v4. Чтобы обеспечить поддержку версий Android, выпущенных раннее уровня API 12, выполните следующие действия.

  • Наследуйте объект FragmentActivity или AppCompatActivity в основной операции.
  • Используйте объект SupportPlaceAutocompleteFragment вместо PlaceAutocompleteFragment.
  • Используйте метод getSupportFragmentManager() вместо getFragmentManager().

Вариант 2: использование объекта Intent для запуска службы подсказки мест

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

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

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

  1. Используйте PlaceAutocomplete.IntentBuilder, чтобы создать объект Intent, передав необходимый режим PlaceAutocomplete. Этот объект Intent должен вызывать startActivityForResult, передавая код запроса, который определяет ваше намерение.
  2. Переопределите обратный вызов onActivityResult для получения выбранного места.

Создание объекта Intent для подсказки мест

В следующем примере показано, как использовать PlaceAutocomplete.IntentBuilder, чтобы создать объект Intent для запуска виджета службы подсказки мест в виде намерения:

int PLACE_AUTOCOMPLETE_REQUEST_CODE = 1;
...
try {
    Intent intent =
            new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                    .build(this);
    startActivityForResult(intent, PLACE_AUTOCOMPLETE_REQUEST_CODE);
} catch (GooglePlayServicesRepairableException e) {
    // TODO: Handle the error.
} catch (GooglePlayServicesNotAvailableException e) {
    // TODO: Handle the error.
}

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

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
Рисунок 1: виджет службы подсказки мест в режиме наложения (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
Рисунок 2: виджет службы подсказки мест в полноэкранном режиме (MODE_FULLSCREEN)

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

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

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == PLACE_AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = PlaceAutocomplete.getPlace(this, data);
            Log.i(TAG, "Place: " + place.getName());
        } else if (resultCode == PlaceAutocomplete.RESULT_ERROR) {
            Status status = PlaceAutocomplete.getStatus(this, data);
            // TODO: Handle the error.
            Log.i(TAG, status.getStatusMessage());

        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
    }
}

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

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

Выбор предпочтительных результатов из определенного региона

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

  • Вызовите метод setBoundsBias() для экземпляра PlaceAutocompleteFragment вашего приложения или экземпляра IntentBuilder, передав в него объектLatLngBounds. В следующем примере кода показано, как вызывать метод setBoundsBias() для экземпляра фрагмента, чтобы отдать предпочтение его подсказкам для г. Сидней, Австралия.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

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

Чтобы выполнить фильтрацию результатов подсказки мест по определенному типу места, вызовите AutocompleteFilter.Builder для создания нового фильтра AutocompleteFilter, вызывая для его настройки метод setTypeFilter(). Затем передайте фильтр в фрагмент или объект Intent.

В следующем примере кода показано, как устанавливать фильтр AutocompleteFilter для фрагмента PlaceAutocompleteFragment, чтобы указать фильтр, возвращающий результаты только с точным адресом.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

autocompleteFragment.setFilter(typeFilter);

В следующем примере кода показано, как устанавливать фильтр AutocompleteFilter для объекта Intent, настроив его для возвращения результатов только с точным адресом.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

Intent intent =
        new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                .setFilter(typeFilter)
                .build(this);

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

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

Вы можете создать собственный пользовательский интерфейс поиска в дополнение к тому, который предоставляется виджетом службы подсказки мест. Для этого ваше приложение должно получать подсказки мест программным способом. Приложение может получить список предполагаемых мест или адресов из службы подсказки мест вызовом метода GeoDataApi.getAutocompletePredictions(), и передавая ему следующие параметры.

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

    • TYPE_FILTER_NONE – пустой фильтр; возвращаются все результаты.
    • TYPE_FILTER_GEOCODE – возвращает в результатах поиска только геокоды, а не организации. Этот запрос следует использовать, когда существуют места с похожими адресами и требуется уточнить результаты.
    • TYPE_FILTER_ADDRESS – ограничивает результаты подсказки мест точными адресами. Этот тип следует использовать, когда известно, что пользователь выполняет поиск полностью указанного адреса.
    • TYPE_FILTER_ESTABLISHMENT – возвращает только организации.
    • TYPE_FILTER_REGIONS – возвращает только адреса, которые соответствуют одному из следующих типов:

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES – возвращает только результаты, соответствующие locality или administrative_area_level_3.

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

В примере ниже показан упрощенный вызов метода GeoDataApi.getAutocompletePredictions(). Полноценные примеры см. в документе о примерах приложений(/places/android-api/code-samples).

PendingResult<AutocompletePredictionBuffer> result =
    Places.GeoDataApi.getAutocompletePredictions(mGoogleApiClient, query,
        bounds, autocompleteFilter);

API возвращает AutocompletePredictionBuffer в PendingResult. Буфер AutocompletePredictionBuffer содержит список объектов AutocompletePrediction, представляющих предполагаемые места. Если места, соответствующие запросу или критериям отбора, отсутствуют, буфер может быть пустым.

Примечание. Для предотвращения утечки памяти необходимо освободить объект AutocompletePredictionBuffer, если он больше не требуется приложению. См. дополнительную информацию по обработке буферов.

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

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

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

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

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

Дополнительную информацию см. в документации по указанию авторства.

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

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

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

Оставить отзыв о...

Текущей странице
location_on
Google Places API for Android