Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Начало работы с Places Insights API

Функции подсчета мест – это предопределенные SQL-запросы, которые выполняются в BigQuery. Мы рекомендуем использовать их для запроса набора данных Places Insights, чтобы получить точное количество мест и их идентификаторы. Вы также можете запрашивать набор данных напрямую. Эти два метода запроса по-разному обрабатывают пороги конфиденциальности и области поиска:

Функции подсчета мест могут возвращать любое количество мест, включая 0, но требуют минимальной области поиска 40,0 на 40,0 м (1600 м²). Функции также возвращают идентификаторы мест, которые можно использовать для поиска информации об отдельных местах, и поддерживают анализ исторических объектов инфраструктуры по прошлым ежемесячным снимкам с использованием дополнительных фильтров дат.
Запросы к набору данных о местах могут возвращать только значения от 5 и выше (низкие значения от 0 до 4 опускаются для сохранения дифференциальной конфиденциальности), но не накладывают ограничений на размер области поиска.

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

Выберите оптимальную функцию Places Count

Places Insights поддерживает несколько пространственных функций. Для оптимизации выполнения запросов, параллельной обработки и масштабируемости пакетов рекомендуем использовать следующие функции:

PLACES_COUNT_PER_H3: возвращает таблицу BigQuery с количеством мест в каждой ячейке H3. Эта функция рекомендуется для анализа региональной плотности и теплового картирования картограмм.
PLACES_COUNT_V2: возвращает таблицу с количеством мест и примерами идентификаторов мест. Эта функция принимает параметр table, содержащий входные данные о местоположениях. Передавая всю таблицу напрямую, механизм выполнения BigQuery может распределять рабочую нагрузку и параллельно обрабатывать пространственные пересечения, обеспечивая высокоэффективную пакетную обработку для крупномасштабного анализа.
PLACES_COUNT_PER_TYPE_V2 Возвращает таблицу с количеством мест и примерами идентификаторов мест, сгруппированных по типу места. Как и в случае с PLACES_COUNT_V2, передача входных географических объектов в качестве параметра таблицы позволяет BigQuery параллельно обрабатывать пространственные пересечения в больших наборах данных.
PLACES_COUNT_CHANGE Возвращает таблицу с количеством мест, а также добавленными и удаленными идентификаторами мест за два указанных месяца. Как и в случае с PLACES_COUNT_V2, передача входных географических объектов в качестве параметра таблицы позволяет BigQuery параллельно обрабатывать пространственные пересечения в больших наборах данных.

Помимо количества мест, эти функции также возвращают до 250 идентификаторов мест на каждый элемент ответа.

Идентификаторы мест можно использовать в следующих сервисах:

Выполнение запросов с помощью функций Places Count

Используйте следующий формат: [project name (optional)].[table name].[function name].

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

Пример:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Используйте JSON_OBJECT, чтобы передать аргументы в функцию.

Как фильтровать результаты запросов с помощью параметров, учитывающих регистр

Функции Places Count поддерживают множество фильтров для уточнения поиска. В названиях параметров (например, price_level или types) учитывается регистр. Полный список вариантов приведен в справочнике по параметрам фильтров.

Как запрашивать статистику за определенный период с помощью snapshot_date

По умолчанию функции Places Count запрашивают самый последний доступный снимок данных. Чтобы проанализировать данные о местах за определенный месяц в прошлом, добавьте в JSON_OBJECT необязательный параметр snapshot_date.

Формат: YYYY-MM (например, '2026-07').
По умолчанию. Если этот параметр не указан, функция автоматически запрашивает последний снимок.

В следующем примере запрашивается количество ресторанов в областях поиска, зафиксированное в снимке за июль 2026 года:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07' -- Optional historical snapshot month
  )
);

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

Сначала используйте таблицу с входными данными о регионах или подготовьте ее, указав выбранные регионы.

-- Create a table for the input geographies
CREATE TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas` AS (
  SELECT
    '1' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9857, 40.7484) AS geo -- Empire State Building
  UNION ALL
  SELECT
    '2' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9851, 40.7580) AS geo -- Times Square
);

Затем вызовите PLACES_COUNT_V2 с таблицей и объектом JSON, содержащим фильтры. Радиус поиска включен в фильтры JSON и будет применяться вокруг каждой точки в таблице my_search_areas.

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters around each point in 'geo'
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
);

Пример. Запрос количества ресторанов и местоположений брендов с помощью PLACES_COUNT_V2

В следующем примере используется функция PLACES_COUNT_V2 с пользовательской таблицей географических данных my_search_areas, чтобы получить количество работающих ресторанов в радиусе 1000 метров от Эмпайр-стейт-билдинг и Таймс-сквер в Нью-Йорке в июле 2026 года:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07'
      )
);

Ответ – это таблица BigQuery, которая содержит geo_id, географические данные, количество и примеры идентификаторов мест.

Результаты для функции Places Count в Нью-Йорке.

В следующем примере используется функция PLACES_COUNT_V2 для фильтрации по определенным идентификаторам брендов. В этом примере мы фильтруем заведения Starbucks по идентификатору бренда "1413758728321880760".

Чтобы найти идентификаторы брендов, по которым вы хотите выполнить фильтрацию, отправьте запрос к таблице brands для вашего набора данных (например, places_insights___us.brands). Подробную информацию о наборе данных брендов можно найти в статье Как составить запрос с использованием данных о брендах.

Например, чтобы найти идентификатор бренда Starbucks, выполните следующие действия:

SELECT id, name
FROM `PROJECT_NAME.places_insights___us.brands`
WHERE name = "Starbucks"

Получив идентификаторы брендов, вы можете использовать их в фильтре brand_ids, как показано в следующем запросе:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'brand_ids', ["1413758728321880760"]
      )
);

Визуализация результатов запроса с помощью инструментов Google Cloud

Инструменты для анализа и бизнес-аналитики помогают получать ценную информацию из данных BigQuery. BigQuery поддерживает несколько инструментов визуализации данных от Google и сторонних разработчиков, которые можно использовать для анализа результатов функций, примененных к данным Аналитики мест.

Пример визуализации результатов функции приведен в разделе Визуализация результатов справочной статьи PLACES_COUNT_PER_H3. Подробнее о визуализации результатов запросов…

Ограничения и требования к функциям

Для функций подсчета мест действуют следующие ограничения и требования:

Функции поддерживают только статистику COUNT.
Минимальная площадь поиска составляет 40 x 40 м (1600 м²).
Ограничение на размер входных параметров. Размер объекта JSON, передаваемого в качестве параметра функциям, не должен превышать 1 МБ. Последствия этого ограничения зависят от версии функции:
- Для функций V2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2, PLACES_COUNT_CHANGE) это ограничение применяется только к объекту JSON фильтров. Поскольку географические данные предоставляются отдельно с помощью параметра таблицы, эти функции могут масштабироваться до гораздо большего количества входных географических данных без достижения ограничения на размер JSON.
- Для PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE и PLACES_COUNT_PER_GEO это ограничение применяется ко всему объекту JSON, включая все определения географических объектов. Это может ограничить количество регионов, которые можно обработать за один вызов.
Фильтрация по идентификатору места или компоненту адреса не поддерживается.
Вы можете использовать функции Places Count только для городов и стран, на которые вы подписаны. Инструкции по настройке доступа к набору данных приведены в статье Настройка Аналитики мест.
Параметры фильтра (например, geography или types) чувствительны к регистру и должны точно соответствовать названиям параметров, иначе запрос не будет выполнен.