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

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

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

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

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

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

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

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

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

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

Примечание: Если вы выберете INSIGHT_PLACES , API агрегирования мест вернет идентификаторы мест только в том случае, если их count равно 100 или меньше.

Фильтры

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

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

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

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

Важно: площадь, на которую распространяется любой фильтр местоположения, должна находиться в диапазоне от 1556,86 квадратных метров (примерно размер небольшого городского квартала) до 2 триллионов квадратных метров (примерно размер Аляски). Запросы с площадями, выходящими за пределы этого диапазона, вернут ошибку INVALID_ARGUMENT .

Примечание: Для объектов с заданными полигональными границами, таких как парки или аэропорты, объект считается находящимся в зоне поиска, если какая-либо часть его полигона пересекается с заданной зоной поиска (кругом, регионом или пользовательским полигоном). Центр объекта не обязательно должен находиться в зоне поиска.

Круг

Если вы выберете географическую область в виде круга, вам необходимо указать 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%), представляющей регион.

Important: When using the region filter with the INSIGHT_PLACES insight type, requests that include disputed areas are automatically rejected to ensure the accuracy and neutrality of Google services. Disputed areas are regions with conflicting boundaries or territorial claims by different countries or entities. Disputed boundaries are displayed as a dashed gray line on Google Maps.

Для получения дополнительной информации о том, как определяются спорные регионы, см. раздел «Понимание границ и названий стран» .

Важно: Google не поддерживает некоторые идентификаторы мест, относящиеся к следующим типам регионов:

• Регионы, настолько большие, что приводят к высокой задержке.
• Типы регионов, настолько малые, что они ставят под угрозу соблюдение требований конфиденциальности.

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

К неподдерживаемым типам мест относятся:

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

Примечание: Даже некоторые места, не указанные выше, могут быть отклонены, если у них отсутствует четко определенная полигональная геометрия. Это чаще встречается с такими типами, как neighborhood , locality , sublocality и их номерные варианты ( sublocality_level_1 , sublocality_level_2 , sublocality_level_3 , sublocality_level_4 ). В этом случае возвращается код ошибки 400.

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

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

Важно: Координаты вершин многоугольника должны быть указаны в порядке против часовой стрелки . Это соответствует общепринятой в отрасли конвенции определения многоугольников, где порядок против часовой стрелки указывает на то, что внутренняя часть многоугольника находится слева от его границ.

Важно: пользовательские области должны содержать не более 7000 вершин.

Вы можете посетить Используйте 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 : Список исключенных основных типов населенных пунктов.

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

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

Дополнительные параметры

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

• 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 работает следующим образом:

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

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

Filters places based on their average user ratings. Both these fields are optional and so if they're omitted, they will default to also include places that don't have a rating.

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

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