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

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

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

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

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

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

• Тип прозрения.
• Фильтр местоположения и фильтр типа.

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

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

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

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

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

Фильтры

Определяет критерии фильтрации мест. Как минимум, вы должны указать LocationFilter и TypeFilter .

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

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

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

Круг

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

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

Область

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

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

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

• establishment : обычно указывает на место, которое еще не было отнесено к категории.
• street_number : указывает точный номер улицы.
• floor : указывает этаж адреса здания.
• post_box : указывает конкретный почтовый ящик.
• street_address : указывает точный адрес.
• room : указывает комнату по адресу здания.
• intersection : указывает на крупный перекресток, обычно двух основных дорог.
• landmark : указывает на близлежащее место, которое используется в качестве ориентира для облегчения навигации.
• subpremise : указывает адресный объект ниже уровня помещения, например квартиру, блок или люкс.
• sublocality_level_5 : наиболее конкретный уровень детализации компонентов адреса сублокации. обычно представляет собой очень небольшой район или гиперлокальный район в городе.

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

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

Вы можете посетить 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 Insights, см. в таблице A в разделе «Типы мест для API Places (новое)». Необходимо указать хотя бы один тип includedTypes или includedPrimaryTypes .

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

Подробнее о том, как работают фильтры типов и типы мест, читайте в статье «Фильтры типов» .

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

Эти фильтры являются дополнительными:

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

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

С помощью фильтра operatingStatus вы можете фильтровать данные по рабочему статусу (например, «работает» или «временно закрыто»). Если фильтр operatingStatus не установлен, в результаты включаются только места с рабочим статусом OPERATING_STATUS_OPERATIONAL .

Уровень цен

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

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

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

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

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