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

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

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

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

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

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

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

Понимание

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

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

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

Фильтр

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

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

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

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

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

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

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

Неподдерживаемые типы регионов
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

Вы можете использовать поле types из вызова API геокодирования, чтобы определить тип местоположения или адреса, связанного с идентификатором места, например, является ли это городом, районом или страной.

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

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

Вы можете посетить 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, см. в таблице А в руководстве по типам мест для API Places (новое). Должен быть включен хотя бы один тип included_types или included_primary_types .

  • included_types : список включенных типов мест.
  • excluded_types : список исключенных типов мест.
  • included_primary_types : список включенных основных типов мест.
  • excluded_primary_types : список исключенных основных типов мест.

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

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

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

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

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

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

Уровень цен

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

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

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

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