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

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

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

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

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

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

Для выполнения запроса на поиск поблизости (новый метод) вызовите 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();
    });

Результаты поиска поблизости (новые)

Класс 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 :

      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

      Полный список полей и соответствующих им артикулов см. в разделе «Размещение полей данных (новое)» .

    Чтобы задать параметр списка полей, вызовите метод 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 типов.

    Для каждого заведения может быть только один основной тип из таблицы типов 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 см. в разделе «Запросы поиска поблизости (новые)» .

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

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

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

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