Параметры запроса

В этом документе описываются параметры запроса для API Places Aggregate, а также содержатся рекомендации и рекомендации по использованию этого сервиса.

API Places Aggregate позволяет выполнять несколько ключевых функций:

• Подсчитайте количество мест : определите количество мест, которые соответствуют определенным критериям, таким как тип местоположения, статус работы, уровень цен и рейтинги.
• Получение сведений о месте : получение названий мест, соответствующих указанным фильтрам, а затем получение более подробной информации с помощью API Places.
• Гибкая фильтрация : используйте комплексные фильтры для получения точных сводных данных. Доступны следующие фильтры:
  • Географическая область (круг, регион или пользовательский многоугольник)
  • Типы мест
  • Рабочее состояние
  • Уровни цен
  • Диапазоны оценок

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

В этом разделе рассматриваются обязательные параметры запроса к API Places Aggregate. Каждый запрос должен содержать следующие данные:

• Своего рода прозрение.
• Фильтр по местоположению и фильтр по типу.

Тип понимания

Указывает тип аналитических данных, которые вы хотите получить. Поддерживаются следующие типы аналитических данных:

• INSIGHT_COUNT : Возвращает количество мест, соответствующих критериям фильтра.
• INSIGHT_PLACES : возвращает идентификаторы мест , соответствующие критериям фильтра.

Фильтры

Задаёт критерии фильтрации мест. Как минимум, необходимо указать LocationFilter и TypeFilter .

Фильтр местоположения

Фильтр местоположения может иметь один из следующих типов:

• circle : определяет область как окружность с центром и радиусом.
• region : определяет область как регион.
• customArea : определяет область как пользовательский многоугольник.

Круг

Если вы выбрали географическую область в виде круга, необходимо указать center и radius . center может быть задан широтой и долготой или идентификатором места в центре круга. Этот метод обеспечивает точную фильтрацию на основе заданной вами круговой области.

• center :
  • latLng : Широта и долгота центра окружности. Широта должна быть числом от -90 до 90 включительно. Долгота должна быть числом от -180 до 180 включительно.
  • place : идентификатор центра круга. Обратите внимание, что поддерживаются только точки place. Эта строка должна начинаться с префикса places/ .
• radius : Радиус окружности в метрах. Это число должно быть положительным.

Область

Определите свою область как регион, передав идентификатор места в параметр place . Идентификатор места представляет географическую область (например, область, представленную многоугольником). Например, идентификатор места Тампы, штат Флорида, — places/ChIJ4dG5s4K3wogRY7SWr4kTX6c . Обратите внимание, что не все идентификаторы мест имеют чётко определённую геометрию, и в таких случаях API Places Aggregate возвращает код ошибки 400 с сообщением о том, что регион не поддерживается. Кроме того, для сложных географических регионов внутренняя оптимизация обработки может привести к небольшому завышению значения площади (до 2–3%), представляющей регион.

Чтобы определить, относится ли идентификатор места к неподдерживаемому типу, передайте его в запросе API геокодирования . Ответ включает массив type , содержащий список типов мест, связанных с этим идентификатором, например, locality , neighborhood » или country . Местоположение будет отклонено при фильтрации по региону, если хотя бы один из его типов соответствует этому списку.

Неподдерживаемые типы мест включают:

• establishment : обычно обозначает место, которое еще не было классифицировано.
• intersection : обозначает крупный перекрёсток, обычно двух основных дорог.
• subpremise : указывает на адресуемую сущность, находящуюся ниже уровня помещения, например, квартиру, блок или апартаменты.

Пользовательская область

Определяет площадь пользовательского многоугольника с использованием координат широты и долготы.

Вы можете посетить https://geojson.io/ , чтобы нарисовать собственный многоугольник и ввести эти координаты в запрос. Многоугольник должен иметь как минимум 4 координаты, при этом первая и последняя координаты должны быть идентичными. Как минимум 3 из предоставленных координат должны быть уникальными.

Последовательно идентичные координаты будут рассматриваться как одна. Однако непоследовательные повторяющиеся координаты (за исключением требуемых идентичных первой и последней координат) приведут к ошибке.

Кроме того, не допускается пересечение несмежных ребер, а также не допускается наличие ребер длиной 180 градусов (то есть смежные вершины не могут быть антиподами).

Например:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Фильтр типа

Указывает типы мест, которые следует включить или исключить. Список основных и дополнительных типов мест, поддерживаемых API Places Aggregate, см. в таблице A в разделе «Типы мест» API Places (новое). Необходимо указать хотя бы один тип includedTypes или includedPrimaryTypes .

• includedTypes : Список включенных типов мест.
• excludedTypes : Список исключенных типов мест.
• includedPrimaryTypes : Список включенных основных типов мест.
• excludedPrimaryTypes : Список исключенных основных типов мест.

Чтобы узнать больше о том, как работают фильтры по типам и типы мест, см. дополнительную информацию о фильтрах по типам .

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

Эти фильтры необязательны:

• operatingStatus : определяет статусы мест, которые следует включить или исключить. По умолчанию фильтрация по operatingStatus: OPERATING_STATUS_OPERATIONAL (одно конкретное значение).
• priceLevels : определяет уровни цен мест, которые нужно включить. По умолчанию фильтрация по уровню цен не применяется, и возвращаются все места (включая те, для которых информация об уровне цен отсутствует).
• ratingFilter : определяет диапазон рейтинга мест. По умолчанию фильтрация отключена (все рейтинги включены в результаты).

Рабочее состояние

Фильтр operatingStatus позволяет фильтровать данные по статусу работы , например, OPERATIONAL или TEMPORARILY_CLOSED . Фильтр operatingStatus работает следующим образом:

• Если фильтры не указаны, в результаты включаются только места со статусом работы OPERATING_STATUS_OPERATIONAL .
• Если предоставлен один или несколько фильтров, необходимо указать допустимые значения рабочего состояния ( OPERATING_STATUS_OPERATIONAL , OPERATING_STATUS_PERMANENTLY_CLOSED или OPERATING_STATUS_TEMPORARILY_CLOSED ).

Уровень цен

Фильтр priceLevels позволяет фильтровать места по уровню цены . Допустимые значения уровня цены: PRICE_LEVEL_FREE , PRICE_LEVEL_INEXPENSIVE , PRICE_LEVEL_MODERATE , PRICE_LEVEL_EXPENSIVE и PRICE_LEVEL_VERY_EXPENSIVE .

Фильтр priceLevels ведет себя следующим образом:

• Если фильтры не указаны: возвращаются все места, независимо от того, указан ли им уровень цен . Это включает места без информации об уровне цен, которые могут не возвращаться при фильтрации по определённым уровням цен.
• Если предоставлен один или несколько фильтров: возвращаются только места, соответствующие указанному(ым) уровню(ям) цен.

Фильтр рейтинга

Фильтрует места по среднему рейтингу пользователей. Оба эти поля необязательны, поэтому, если их не заполнить, по умолчанию будут включены и места без рейтинга.

• minRating : Минимальный средний рейтинг пользователя (от 1,0 до 5,0).
• maxRating : максимальный средний рейтинг пользователя (от 1,0 до 5,0).

Кроме того, значение minRating всегда должно быть меньше или равно значению maxRating . Если minRating больше maxRating , возвращается ошибка INVALID_ARGUMENT .