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

Выберите платформу: 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 текстового поиска предоставляет доступ к разбивке результатов поиска на страницы с помощью метода getPagination(), который возвращает объект Pagination.

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

Если функция 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:

      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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Чтобы задать параметр включенного типа, вызовите метод 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 (ранжирование результатов по расстоянию).
    • Для запросов, не относящихся к категориям, например "Москва", рекомендуем не задавать параметр rankPreference.

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

  • Код области

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

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

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

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

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

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

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