Новая версия текстового поиска

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

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

Функция текстового поиска (новая) возвращает информацию о наборе мест на основе строки (например, "пицца в Нью-Йорке", "обувные магазины рядом с Оттавой" или "Главная улица, 123"). Сервис отвечает списком мест, соответствующих текстовой строке, с учетом любых заданных параметров местоположения.

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

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

Запросы на поиск текста

Запрос на текстовый поиск имеет следующий формат:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

В этом примере вы:

  • Укажите в списке полей только поля Place.Field.ID и Place.Field.DISPLAY_NAME . Это означает, что объекты Place в ответе, представляющие каждое соответствующее место, содержат только эти два поля.

  • Используйте SearchByTextRequest.Builder для создания объекта SearchByTextRequest , определяющего поиск.

    • Установите текстовый запрос в значение "Острая вегетарианская еда".

    • Установите максимальное количество мест для результатов равным 10. Значение по умолчанию и максимальное значение — 20.

    • Ограничьте область поиска прямоугольником, заданным координатами широты и долготы. Результаты поиска за пределами этой области не будут найдены.

  • Добавьте обработчик OnSuccessListener и получите информацию о совпадающих местах из объекта SearchByTextResponse .

Ответы на текстовый поиск

Класс SearchByTextResponse представляет собой ответ на поисковый запрос. Объект SearchByTextResponse содержит:

  • Список объектов Place , представляющих все соответствующие места, по одному объекту Place на каждое соответствующее место.

  • Каждый объект Place содержит только поля, определенные списком полей, переданным в запросе.

Например, в запросе вы определили список полей следующим образом:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

Этот список полей означает, что каждый объект Place в ответе содержит только идентификатор места и название соответствующего места. Затем вы можете использовать методы Place.getId() и Place.getName() для доступа к этим полям в каждом объекте Place .

Дополнительные примеры доступа к данным в объекте Place см. в разделе «Доступ к полям данных объекта Place».

Пагинация

Класс SearchByTextResponse из библиотеки Text Search предоставляет доступ к постраничной навигации результатов текстового поиска через метод getPagination() , который возвращает объект Pagination.

Используйте метод hasNextPage() объекта Pagination, чтобы определить, доступны ли дополнительные страницы результатов. Этот метод возвращает логическое значение (true или false).

Пока метод hasNextPage() возвращает true, вызовите метод fetchNextPage() для получения следующей страницы результатов.

В следующем примере показано, как проверить наличие следующей страницы и затем загрузить её.

Котлин 

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java 

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

Необходимые параметры

Для функции SearchByTextRequest необходимы следующие параметры:

  • Список полей

    Укажите, какие поля данных о местах следует вернуть. Передайте список значений Place.Field , указывающих на поля данных, которые необходимо вернуть. В ответе нет списка полей по умолчанию.

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

    Укажите одно или несколько из следующих полей:

    • Следующие поля активируют функцию Text Search Essentials ID Only SKU :

      Place.Field.DISPLAY_NAME *
      * Используйте вместо Place.Field.NAME (устарело в версии 4.0).
      Place.Field.ID
      Place.Field.RESOURCE_NAME *
      * Содержит название ресурса места в формате: places/PLACE_ID .
      Используйте DISPLAY_NAME для доступа к текстовому названию места.

    • Следующие поля активируют артикул Text Search Pro :

      Place.Field.ACCESSIBILITY_OPTIONS *
      Используйте вместо Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (устарело).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS *
      Используйте вместо Place.Field.ADDRESS (устарело).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
      Используйте вместо Place.Field.ICON_URL (устарело).
      Place.Field.LOCATION *
      Используйте вместо Place.Field.LAT_LNG (устарело).
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.SUB_DESTINATIONS
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT

    • Следующие поля запускают функцию текстового поиска Enterprise SKU :

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER *
      * Используйте вместо Place.Field.PHONE_NUMBER , который устарел.
      Place.Field.NATIONAL_PHONE_NUMBER
      Place.Field.OPENING_HOURS
      Place.Field.PRICE_LEVEL
      Place.Field.RATING
      Place.Field.SECONDARY_OPENING_HOURS
      Place.Field.USER_RATING_COUNT *
      * Используйте вместо Place.Field.USER_RATINGS_TOTAL , который устарел.
      Place.Field.WEBSITE_URI

    • Следующие поля запускают функцию текстового поиска Enterprise Plus :

      Place.Field.ALLOWS_DOGS
      Place.Field.CURBSIDE_PICKUP
      Place.Field.DELIVERY
      Place.Field.DINE_IN
      Place.Field.EDITORIAL_SUMMARY
      Place.Field.EV_CHARGE_OPTIONS
      Place.Field.FUEL_OPTIONS
      Place.Field.GOOD_FOR_CHILDREN
      Place.Field.GOOD_FOR_GROUPS
      Place.Field.GOOD_FOR_WATCHING_SPORTS
      Place.Field.LIVE_MUSIC
      Place.Field.MENU_FOR_CHILDREN
      Place.Field.OUTDOOR_SEATING
      Place.Field.PARKING_OPTIONS
      Place.Field.PAYMENT_OPTIONS
      Place.Field.RESERVABLE
      Place.Field.RESTROOM
      Place.Field.REVIEWS
      Place.Field.SERVES_BEER
      Place.Field.SERVES_BREAKFAST
      Place.Field.SERVES_BRUNCH
      Place.Field.SERVES_COCKTAILS
      Place.Field.SERVES_COFFEE
      Place.Field.SERVES_DESSERT
      Place.Field.SERVES_DINNER
      Place.Field.SERVES_LUNCH
      Place.Field.SERVES_VEGETARIAN_FOOD
      Place.Field.SERVES_WINE
      Place.Field.TAKEOUT

    Чтобы задать параметр списка полей, вызовите метод setPlaceFields() при создании объекта SearchByTextRequest .

  • Текстовый запрос

    Текстовая строка, по которой осуществляется поиск, например: "ресторан", "123 Main Street" или "лучшее место для посещения в Сан-Франциско". API возвращает подходящие варианты на основе этой строки и упорядочивает результаты в зависимости от их предполагаемой релевантности.

    Чтобы задать параметр текстового запроса, вызовите метод setTextQuery() при создании объекта SearchByTextRequest .

Дополнительные параметры

Используйте объект SearchByTextRequest для указания необязательных параметров вашего запроса.

  • Включенный тип

    Ограничивает результаты местами, соответствующими указанному типу, определенному в таблице А. Можно указать только один тип. Например:

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

    Чтобы задать параметр типа, необходимого для включения данных, вызовите метод setIncludedType() при создании объекта SearchByTextRequest .

  • Смещение в сторону местоположения

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

    Вы можете указать ограничение по местоположению или смещение по местоположению, но не то и другое одновременно. Ограничение по местоположению следует рассматривать как указание региона, в пределах которого должны находиться результаты, а смещение по местоположению — как указание региона, в пределах которого результаты, вероятно, будут находиться или вблизи которого будут находиться — при этом следует помнить, что при использовании смещения по местоположению результаты могут по-прежнему выходить за пределы указанной области.

    Укажите область в виде прямоугольника или круга.

    • Окружность определяется центром и радиусом в метрах. Радиус должен находиться в диапазоне от 0,0 до 50000,0 включительно. Например:

      // Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

    • Прямоугольник — это область просмотра, отображаемая по широте и долготе, в виде двух расположенных по диагонали нижней и верхней точек. Нижняя точка обозначает юго-западный угол прямоугольника, а верхняя — северо-восточный угол.

      Область просмотра считается замкнутой областью, то есть включает в себя свои границы. Границы широты должны находиться в диапазоне от -90 до 90 градусов включительно, а границы долготы — в диапазоне от -180 до 180 градусов включительно.

      • Если low = high , то область просмотра состоит из этой единственной точки.
      • Если low.longitude > high.longitude , диапазон долготы инвертируется (область просмотра пересекает линию долготы в 180 градусов).
      • Если low.longitude = -180 градусов и high.longitude = 180 градусов, то область просмотра будет включать все долготы.
      • Если low.longitude = 180 градусов и high.longitude = -180 градусов, то диапазон долготы пуст.
      • Если low.latitude > high.latitude , диапазон широт пуст.

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

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

      Чтобы задать параметр смещения местоположения, вызовите метод setLocationBias() при создании объекта SearchByTextRequest .

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

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

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

    Чтобы задать параметр ограничения местоположения, вызовите метод setLocationRestriction() при создании объекта SearchByTextRequest .

  • Максимальное количество результатов

    Указывает максимальное количество результатов поиска мест, которые необходимо вернуть. Должно быть от 1 до 20 (по умолчанию) включительно.

    Чтобы задать параметр максимального количества результатов, вызовите метод setMaxResultCount() при создании объекта SearchByTextRequest .

  • Минимальный рейтинг

    Отображает только те результаты, средний пользовательский рейтинг которых больше или равен этому пределу. Значения должны быть в диапазоне от 0,0 до 5,0 (включительно) с шагом 0,5. Например: 0, 0,5, 1,0, ..., 5,0 включительно. Значения округляются до ближайшего 0,5. Например, значение 0,6 исключает все результаты с рейтингом ниже 1,0.

    Чтобы установить параметр минимального рейтинга, вызовите метод setMinRating() при создании объекта SearchByTextRequest .

  • Открыто сейчас

    Если true , возвращаются только те заведения, которые открыты на момент отправки запроса. Если false , возвращаются все заведения независимо от их статуса. Если вы установите для этого параметра значение false , будут возвращены заведения, у которых не указаны часы работы в базе данных Google Places.

    Чтобы задать параметр "Открыть сейчас", вызовите метод setOpenNow() при создании объекта SearchByTextRequest .

  • Уровень цен

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

    • 1 Место предоставляет недорогие услуги.
    • 2 Место предоставляет услуги по умеренным ценам.
    • 3 Место предоставляет дорогостоящие услуги.
    • 4 Это место предоставляет очень дорогие услуги.

    Чтобы задать параметр уровней цен, вызовите метод setPriceLevels() при создании объекта SearchByTextRequest .

  • Предпочтение ранга

    Указывает, как результаты ранжируются в ответе в зависимости от типа запроса:

    • Для категориального запроса, например, "Рестораны в Нью-Йорке", по умолчанию используется параметр SearchByTextRequest.RankPreference.RELEVANCE (ранжирование результатов по релевантности поиска). Вы можете установить приоритет ранжирования на SearchByTextRequest.RankPreference.RELEVANCE или SearchByTextRequest.RankPreference.DISTANCE (ранжирование результатов по расстоянию).
    • Для некатегориальных запросов, таких как "Mountain View, CA", мы рекомендуем не задавать параметр предпочтения ранжирования.

    Чтобы задать параметр предпочтения ранжирования, вызовите метод setRankPreference() при создании объекта SearchByTextRequest .

  • код региона

    Региональный код, используемый для форматирования ответа, указывается в виде двухсимвольного кода CLDR . Этот параметр также может влиять на результаты поиска. Значение по умолчанию отсутствует.

    Если название страны в адресном поле ответа совпадает с кодом региона, то код страны опускается в адресе.

    Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, национальный домен верхнего уровня Соединенного Королевства — «uk» (.co.uk), а его код ISO 3166-1 — «gb» (технически обозначающий «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может влиять на результаты в зависимости от применимого законодательства.

    Чтобы задать параметр кода региона, вызовите метод setRegionCode() при создании объекта SearchByTextRequest .

  • Строгая фильтрация по типу

    Используется с параметром include type. Если установлено значение true , возвращаются только места, соответствующие указанным типам. Если false (по умолчанию), ответ может содержать места, не соответствующие указанным типам.

    Чтобы задать параметр строгой фильтрации по типу, вызовите метод setStrictTypeFiltering() при создании объекта SearchByTextRequest .