Поиск поблизости (новинка)

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

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

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

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

Запросы поиска поблизости (новые)

Сделайте запрос поиска поблизости (новый), вызвав PlacesClient.searchNearby и передав объект SearchNearbyRequest , который определяет параметры запроса.

Объект SearchNearbyRequest указывает все обязательные и необязательные параметры запроса. К обязательным параметрам относятся:

• Список полей, возвращаемых в объекте Place , который также называется маской поля. Если вы не укажете хотя бы одно поле в списке полей или опустите список полей, вызов вернет ошибку.
• Ограничение местоположения для области поиска, определяемое как пара широты/долготы и значение радиуса, в метрах.

В этом примере запроса поиска поблизости указывается, что ответные объекты Place содержат поля места Place.Field.ID и Place.Field.NAME для каждого объекта Place в результатах поиска. Он также фильтрует ответ, чтобы возвращать только места типа «ресторан» и «кафе», но исключать места типа «пицца_ресторан» и «американский_ресторан».

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

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

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

Поиск поблизости (новые) ответы

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

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

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

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

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

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

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

Используйте объект SearchNearbyRequest , чтобы указать необходимые параметры поиска.

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

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

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

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

    Place.Field.ADDRESS_COMPONENTS , Place.Field.BUSINESS_STATUS , Place.Field.ADDRESS , Place.Field.ICON_BACKGROUND_COLOR , Place.Field.ICON_URL , Place.Field.LAT_LNG , Place.Field.PHOTO_METADATAS , Place.Field.PLUS_CODE , Place.Field.ID , Place.Field.NAME , Place.Field.TYPES , Place.Field.UTC_OFFSET , Place.Field.VIEWPORT , Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS , Place.Field.SECONDARY_OPENING_HOURS , Place.Field.PHONE_NUMBER , Place.Field.PRICE_LEVEL , Place.Field.RATING , Place.Field.OPENING_HOURS , Place.Field.USER_RATINGS_TOTAL , Place.Field.WEBSITE_URI

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

    Place.Field.CURBSIDE_PICKUP , Place.Field.DELIVERY , Place.Field.DINE_IN , Place.Field.EDITORIAL_SUMMARY , Place.Field.RESERVABLE , Place.Field.REVIEWS , Place.Field.SERVES_BEER , Place.Field.SERVES_BREAKFAST , Place.Field.SERVES_BRUNCH , Place.Field.SERVES_DINNER , Place.Field.SERVES_LUNCH , Place.Field.SERVES_VEGETARIAN_FOOD , Place.Field.SERVES_WINE , Place.Field.TAKEOUT

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

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

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

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

  Объект LocationRestriction , определяющий область поиска, заданную в виде круга, определяемого центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от более 0,0 до менее или равного 50000,0, учитывая, что указание слишком маленького радиуса вернет в качестве ответа ZERO_RESULTS .

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

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

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

• Виды и основные типы

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

  Примечание. Значения в таблице B возвращаются только в ответе. Значения из таблицы B нельзя использовать в качестве фильтра.

  Место может иметь только один основной тип из таблицы типов, связанных с ним. Например, основным типом может быть "mexican_restaurant" или "steak_house" . Используйте includedPrimaryTypes и excludedPrimaryTypes чтобы фильтровать результаты по основному типу места.

  Место также может иметь несколько значений типов из таблицы типов, связанных с ним. Например, ресторан может иметь следующие типы: "seafood_restaurant" , "restaurant" , "food" , "point_of_interest" , "establishment" . Используйте includedTypes и excludedTypes , чтобы фильтровать результаты в списке типов, связанных с местом.

  Если для поиска заданы ограничения нескольких типов, возвращаются только места, удовлетворяющие всем ограничениям. Например, если вы укажете includedTypes = Arrays.asList("restaurant") и excludedPrimaryTypes = Arrays.asList("steak_house") , возвращаемые места предоставляют услуги, связанные с "restaurant" , но не работают в основном как "steak_house" .

  Если вы опустите includedTypes , excludedTypes , includedPrimaryTypes и excludedPrimaryTypes из запроса, поиск вернет места для всех типов в пределах границ ограничения местоположения.

  Пример использования includedTypes и excludedTypes см. в разделе Запросы поиска поблизости (новые) .

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

  Список типов мест из таблицы А для поиска. Если этот параметр опущен, возвращаются места всех типов.

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

  Исключенные типы

  Список типов мест из таблицы А , которые следует исключить из поиска.

  Если вы укажете в запросе как includedTypes (например, "school" ), так и excludedTypes (например, "primary_school" ), то в ответ будут включены места, которые относятся к категории "school" , но не к категории "primary_school" . Ответ включает места, соответствующие хотя бы одному из includedTypes и ни одному из excludedTypes .

  Если есть какие-либо конфликтующие типы, например тип, присутствующий как в includedTypes , так и excludedTypes , возвращается ошибка INVALID_REQUEST .

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

  Включенные основные типы

  Список основных типов мест из таблицы А для включения в поиск.

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

  Исключенные основные типы

  Список основных типов мест из таблицы А , которые следует исключить из поиска.

  Если есть какие-либо конфликтующие первичные типы, например тип, встречающийся как в includedPrimaryTypes , так и excludedPrimaryTypes , возвращается ошибка INVALID_ARGUMENT .

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

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

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

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

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

  Используемый тип рейтинга. Если этот параметр опущен, результаты ранжируются по популярности. Может быть одним из следующих:

  • POPULARITY (по умолчанию) Сортирует результаты по популярности.
  • DISTANCE Сортирует результаты в порядке возрастания расстояния от указанного местоположения.

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

• Код региона

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

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

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

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

Отображение авторства в вашем приложении

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

Дополнительную информацию см. в разделе Политики для Places SDK для Android .