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

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

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

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

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

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

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

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

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

В этом примере запроса поиска поблизости указывается, что ответные объекты Place содержат поля места Place.Field.ID и Place.Field.DISPLAY_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.DISPLAY_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();
    });

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

Вы можете использовать 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 Nearby Search Pro :

    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.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.ID
Place.Field.NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

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

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

  В следующем примере определяется список из двух значений полей, чтобы указать, что объект Place , возвращаемый запросом, содержит поля Place.Field.ID и Place.Field.DISPLAY_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.DISPLAY_NAME);

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

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

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

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

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

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

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

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

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

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

  Когда вы указываете общий основной тип, например "restaurant" или "hotel" , ответ может содержать места с более конкретным основным типом, чем указанный. Например, вы указываете включить основной тип "restaurant" . Тогда ответ может содержать места с основным типом "restaurant" , но ответ также может содержать места с более конкретным основным типом, например "chinese_restaurant" или "seafood_restaurant" .

  Если для поиска заданы ограничения нескольких типов, возвращаются только места, удовлетворяющие всем ограничениям. Например, если вы укажете 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 . Значения по умолчанию нет.

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

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

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

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

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

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