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

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

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

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

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

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

Выполните запрос поиска поблизости (New), вызвав 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();
    });

Ответы на запросы к новому сервису поиска поблизости

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

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

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

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

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

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

    • Следующие поля активируют поиск поблизости 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 и меньше или равен 50 000,0. Если указать слишком маленький радиус, в ответе будет возвращено значение ZERO_RESULTS.

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

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

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

  • Типы и основные типы

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

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

    У места также может быть несколько значений типа из таблицы А. Например, у ресторана могут быть следующие типы: "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 приведен в разделе Новые запросы поиска поблизости.

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

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

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

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

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

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

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

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

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

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

    Чтобы задать параметр includedPrimaryTypes, вызовите метод 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…