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

Выберите платформу: Android iOS JavaScript Web Service

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

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

Примечание: Nearby Search (New) доступен в 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 в результатах поиска. Он также фильтрует ответ, чтобы возвращать только места типа "restaurant" и "cafe", но исключать места типа "pizza_restaurant" и "american_restaurant".

// 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 см. Инициализация клиента API Places .

Вы можете использовать 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 . Маскирование полей — это хорошая практика проектирования, которая гарантирует, что вы не запрашиваете ненужные данные, что помогает избежать ненужного времени обработки и расходов на выставление счетов.

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

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

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
    * Используйте вместо Place.Field.NAME , который устарел.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL *
    * Используйте вместо Place.Field.ICON_URL , который устарел.
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    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

  • Следующие поля активируют Nearby Search Enterprise Plus 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 было объявлено об устаревании нескольких полей данных Place и добавлены новые поля. Для получения дополнительной информации см. раздел Переход на новые поля данных Place в 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 в качестве фильтра.

  Место может иметь только один основной тип из типов, связанных с ним в Таблице A. Например, основным типом может быть "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 см. в разделе Запросы Nearby Search (New) .

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

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

  Чтобы задать параметр включенных типов, вызовите метод 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, за некоторыми заметными исключениями. Например, ccTLD Соединенного Королевства — «uk» (.co.uk), а его код ISO 3166-1 — «gb» (технически для субъекта «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может влиять на результаты в зависимости от применимого законодательства.

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

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

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

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