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

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

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

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

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

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

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

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

// 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(), чтобы получить следующую страницу результатов.

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

Kotlin

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.

      Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).

    • Следующие поля активируют SKU текстового поиска 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

      Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).

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

      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

      Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).

    • Код Text Search 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

      Полный список полей и связанных с ними кодов SKU приведен в разделе Поля данных о местах (новые).

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

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

    Строка для текстового поиска, например "ресторан", "улица Центральная, 123" или "лучшие места в Санкт-Петербурге". На основе этой строки API возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.

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

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

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

  • Тип данных для скачивания

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Уровни цен

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

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

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

  • Предпочтительная позиция

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

    • Для запросов по категориям, например "рестораны в Москве", по умолчанию используется значение SearchByTextRequest.RankPreference.RELEVANCE (результаты ранжируются по релевантности). Вы можете задать предпочтительный порядок ранжирования: SearchByTextRequest.RankPreference.RELEVANCE или SearchByTextRequest.RankPreference.DISTANCE (ранжирование результатов по расстоянию).
    • Для запросов, не относящихся к категориям, например "Mountain View, CA", рекомендуем не задавать параметр rank preference.

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

  • Код области

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

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

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

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

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

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

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