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

Текстовый поиск (новое) возвращает информацию о наборе мест на основе строки — например, «пицца в Нью-Йорке», «обувные магазины недалеко от Оттавы» или «Мейн-стрит, 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.

Обязательные параметры

Обязательные параметры для SearchByTextRequest :

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

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

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

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

  • Следующие поля активируют SKU текстового поиска (только идентификатор) :

    Place.Field.DISPLAY_NAME , Place.Field.ID , Place.Field.RESOURCE_NAME
    

  • Следующие поля активируют SKU текстового поиска (базовый) :

    Place.Field.ACCESSIBILITY_OPTIONS , Place.Field.ADDRESS_COMPONENTS , Place.Field.ADR_FORMAT_ADDRESS , Place.Field.BUSINESS_STATUS , Place.Field.FORMATTED_ADDRESS , Place.Field.GOOGLE_MAPS_URI , Place.Field.ICON_BACKGROUND_COLOR , Place.Field.ICON_MASK_URL , Place.Field.LOCATION , 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
    

  • Следующие поля активируют SKU текстового поиска (расширенный) :

    Place.Field.CURRENT_OPENING_HOURS , Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_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.WEBSITE_URI
    

  • Следующие поля активируют SKU текстового поиска (предпочтительный) :

    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 , чтобы указать необязательные параметры вашего запроса.

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

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

  • 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 , диапазон широт пуст.

    Оба значения low и high должны быть заполнены, а представленное поле не может быть пустым. Пустое окно просмотра приводит к ошибке.

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

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

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

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

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

  Чтобы установить параметр ограничения местоположения, вызовите метод 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 , вернуть все предприятия независимо от их открытого статуса. Места, для которых не указаны часы работы в базе данных Google Адресов, возвращаются, если для этого параметра установлено значение false .

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

• Уровни цен

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

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

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

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

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

  • Для категориального запроса, такого как «Рестораны в Нью-Йорке», по умолчанию используется SearchByTextRequest.RankPreference.RELEVANCE (ранжирование результатов по релевантности поиска). Вы можете установить предпочтение ранга SearchByTextRequest.RankPreference.RELEVANCE или SearchByTextRequest.RankPreference.DISTANCE (ранжировать результаты по расстоянию).
  • Для некатегорийного запроса, такого как «Маунтин-Вью, Калифорния», мы рекомендуем оставить параметр предпочтения ранга неустановленным.

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

• Код региона

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

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

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

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

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

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

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