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

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

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

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

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

«10 High Street, Великобритания» или «123 Main Street, США».	Несколько «Хай-стрит» в Великобритании; несколько «Мейн-стрит» в США. Запрос не возвращает желаемых результатов, если не установлено ограничение местоположения.
«Сеть ресторанов Нью-Йорк»	Несколько ресторанов ChainRestaurant в Нью-Йорке; ни адреса, ни даже названия улицы.
«10 High Street, Escher UK» или «123 Main Street, Pleasanton US»	Единственная «Хай-стрит» в британском городе Эшер; только одна «Мейн-стрит» в американском городе Плезантон, Калифорния.
«UniqueRestaurantName Нью-Йорк»	В Нью-Йорке только одно заведение с таким названием; никакой адрес не нужен для различения.
"пиццерии в Нью-Йорке"	Этот запрос содержит ограничение по местоположению, а «рестораны-пиццерии» – это четко определенный тип места. Он возвращает несколько результатов.
"[phone]"	Этот запрос содержит номер телефона. Он возвращает несколько результатов для мест, связанных с этим номером телефона. Примечание. Для достижения наилучших результатов при поиске по номеру телефона укажите код страны, а затем пробел, и установите параметр region code в соответствии с кодом страны.

Примечание. Текстовый поиск (новинка) доступен в Places SDK для Android версии 3.3.0 и более поздних версий. Дополнительную информацию см. в разделе Выбор версии SDK . Дополнительные сведения об использовании API Kotlin, добавленных в версии 4.0.0, см. в обзоре ссылок .

Запросы текстового поиска

Примечание. Текстовый поиск является частью Places SDK для Android (новинка) и недоступен в Places SDK для Android .

Запрос текстового поиска имеет форму:

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

Примечание. Дополнительные сведения об инициализации PlacesClient см. в разделе Инициализация клиента Places API .

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

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

Класс 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
    
    Примечания:

    • Поле Place.Field.NAME устарело в версии 4.0 Places SDK для Android. Вместо этого используйте Place.Field.DISPLAY_NAME .
    • Поле RESOURCE_NAME содержит имя ресурса места в форме places/PLACE_ID . Используйте DISPLAY_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
    
    Примечание. Поля Place.Field.ADDRESS , Place.Field.ICON_URL , Place.Field.LAT_LNG и Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE устарели в версии 4.0 Places SDK для Android. Вместо этого используйте Place.Field.FORMATTED_ADDRESS , Place.Field.ICON_MASK_URL , Place.Field.LOCATION и Place.ACCESSIBILITY_OPTIONS соответственно. Place.Field.ACCESSIBILITY_OPTIONS доступен только для сведений о месте (новое).

  • Следующие поля активируют 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
    
    Примечание. Поля Place.Field.PHONE_NUMBER и Place.Field.USER_RATINGS_TOTAL устарели в версии 4.0 Places SDK для Android. Вместо этого используйте Place.Field.INTERNATIONAL_PHONE_NUMBER и Place.USER_RATING_COUNT соответственно.

  • Следующие поля активируют 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
  Примечание. В версии 4.0 Places SDK для Android некоторые поля данных о местах устарели и были добавлены новые поля. Дополнительную информацию см. в разделе «Миграция на новые поля данных о местах» в Places SDK для Android 4.0 .

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

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

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

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

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

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

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

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

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Примечание. Значения в таблице B возвращаются только в ответе. Значения из таблицы B нельзя использовать в качестве фильтра.

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

• Предвзятость местоположения

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

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

  Примечание. Если вы опустите как смещение местоположения, так и ограничение местоположения, API будет использовать смещение IP-адреса по умолчанию. При смещении IP API использует IP-адрес устройства для смещения результатов.
  Примечание. Параметр locationBias можно переопределить, если textQuery содержит явное местоположение, например Market in Barcelona . В этом случае locationBias игнорируется.

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

  • Круг определяется центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от 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 .

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

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

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

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

  Чтобы установить параметр ограничения местоположения, вызовите метод 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 – Место предоставляет очень дорогие услуги.
  Примечание. Целочисленное значение 0 , указывающее, что место предоставляет бесплатные услуги, может быть включено в ответ, но не может использоваться в качестве значения фильтра в запросе.

  Чтобы установить параметр уровней цен, вызовите метод 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 .