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

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

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

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

Необходимые параметры

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

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

Тип аналитической информации

Указывает тип получаемой информации. Поддерживаются следующие типы информации:

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

Фильтры

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

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

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

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

Круг

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

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

Область

Определите свою область как регион, передав идентификатор места (place ID) параметру 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 .