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

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

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

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

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

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

• Тип статистики.
• Фильтр по местоположению и типу.

Тип статистики

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

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

Примечание. Если вы выберете INSIGHT_PLACES, Places Aggregate API вернет идентификаторы мест, только если значение count не превышает 100.

Фильтры

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

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

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

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

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

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

Круг

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

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

Регион

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

Важно! При использовании фильтра region с типом статистики INSIGHT_PLACES запросы, включающие спорные территории, автоматически отклоняются, чтобы обеспечить точность и нейтральность сервисов Google. Спорные территории – это регионы, границы которых не определены или на которые претендуют разные страны или организации. Оспариваемые границы обозначаются на Google Картах серыми пунктирными линиями.

Подробнее о том, как обозначаются спорные территории…

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

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

Чтобы определить, относится ли идентификатор места к неподдерживаемому типу, передайте его в запросе Geocoding 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/, нарисовать собственный многоугольник и ввести его координаты в запрос. Многоугольник должен иметь не менее четырех координат, причем первая и последняя координаты должны совпадать. По крайней мере три из указанных координат должны быть уникальными.

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

Кроме того, несмежные ребра не должны пересекаться, а ребра не могут иметь длину 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
   }
]

Фильтр по типу

Указывает типы мест, которые нужно включить или исключить. Список основных и дополнительных типов мест, поддерживаемых Places Aggregate API, приведен в таблице А в разделе Типы мест документации по Places API (New). Необходимо указать хотя бы один тип 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 работает следующим образом:

• Если фильтры не заданы, возвращаются все места независимо от того, назначен ли им уровень цен. В том числе места, для которых не указан уровень цен. Они могут не возвращаться при фильтрации по определенным уровням цен.
• Если указан один или несколько фильтров, возвращаются только места, соответствующие указанным уровням цен.

Фильтр: оценка

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

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

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