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

В этом документе описаны параметры запроса для 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 возвращает код ошибки 404.

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

Неподдерживаемые типы регионов
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark 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 Insights, см. в таблице A в разделе «Типы мест для API Places (новое)». Необходимо указать хотя бы один тип includedTypes или includedPrimaryTypes .

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

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

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

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

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

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

Фильтрация по рабочему состоянию (например, рабочее или временное закрытие).

Уровень цен

Фильтрация по уровню цен (например, бесплатно, умеренно или дорого).

Рейтинговый фильтр

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

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