Places Count functions are predefined SQL queries that run in BigQuery and are
the recommended way of querying the Places Insights dataset to retrieve exact
counts and Place IDs. While you can also [query the dataset
directly](https://developers.google.com/maps/documentation/placesinsights/queries), the two query methods
handle privacy thresholds and search areas:

- **Places Count functions** can return any counts, including 0, but enforce a
  minimum search area of 40.0 meters by 40.0 meters (1600 m^2^) (40.0 meters by 40.0 meters / 1,600
  m²). Functions also return [Place
  IDs](https://developers.google.com/maps/documentation/places/web-service/place-id), which can be used to
  look up information about individual Places, and support historical POI analysis across past monthly snapshots using optional date filters.

- **Place dataset queries** can only return counts 5 and
  above (omitting low counts of 0--4 to preserve differential privacy), but
  enforce no limitations on the size of the search area.

Unless you need to perform complex spatial analysis, we recommend starting with
Places Count functions such as
[`PLACES_COUNT_PER_H3`](https://developers.google.com/maps/documentation/placesinsights/place-count-functions/places-count-per-h3.md.txt).
It provides immediate spatial density insights across standardized grid cells,
returns Place IDs for ground-truth inspection, and is purpose-built for
geospatial feature engineering and ML models.

## Select the optimal Places Count function

Places Insights supports several spatial functions. For optimized query
execution, parallel processing, and batch scalability, we recommend using
the following functions:

- [**`PLACES_COUNT_PER_H3`**](https://developers.google.com/maps/documentation/placesinsights/place-count-functions/places-count-per-h3.md.txt): Returns a BigQuery table of place counts per H3 cell. This function is recommended for regional density analysis and choropleth heatmapping.
- [**`PLACES_COUNT_V2`**](https://developers.google.com/maps/documentation/placesinsights/place-count-functions/places-count-v2.md.txt): Returns a table containing place counts and sample Place IDs. This function accepts a [table
  parameter](https://docs.cloud.google.com/bigquery/docs/table-functions#table_parameters) containing your input geographies. By passing an entire table directly, the BigQuery execution engine can distribute the workload and process spatial intersections in parallel, enabling highly efficient batch processing for large-scale analysis.
- [**`PLACES_COUNT_PER_TYPE_V2`**](https://developers.google.com/maps/documentation/placesinsights/place-count-functions/places-count-per-type-v2.md.txt): Returns a table of place counts and sample Place IDs, categorized by place type. Similar to `PLACES_COUNT_V2`, passing your input geographies as a table parameter allows BigQuery to natively parallelize spatial intersections across large datasets.
- [**`PLACES_COUNT_CHANGE`**](https://developers.google.com/maps/documentation/placesinsights/place-count-functions/places-count-change.md.txt): Returns a table of place counts plus added and removed Place IDs between two given months. Similar to `PLACES_COUNT_V2`, passing your input geographies as a table parameter allows BigQuery to natively parallelize spatial intersections across large datasets.

Along with place counts, these functions also return up to 250 [Place
IDs](https://developers.google.com/maps/documentation/places/web-service/place-id) per element of the
response.

Place IDs can be used with:

- [Places API (New)](https://developers.google.com/maps/documentation/places/web-service)
- [Geocoding API](https://developers.google.com/maps/documentation/geocoding)
- [Places UI Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/overview.md.txt)

> [!NOTE]
> **Note:** You can access the Places Count functions for the same cities and countries you have access to.

## Execute queries with Places Count functions

Use the following format to call the functions: `[project name
(optional)].[table name].[function name]`.

If you changed the linked dataset name when setting up Places Insights, then use
your custom name instead of the default table names. You can also optionally
include your project name. If one isn't included, the query defaults to the
active project.

For example:

```googlesql
PROJECT_NAME.places_insights___us.PLACES_COUNT_V2
```

Use a
[`JSON_OBJECT`](https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_object)
to pass arguments to the function.

> [!NOTE]
> **Note:** When you use a Places Count function, specify the function in the `FROM` clause and omit `WITH_AGGREGATION_THRESHOLD`.

### Filter query results using case-sensitive parameters

The Places Count functions support many filters to refine your search. These
parameters (for example, `price_level` or `types`) are case-sensitive and must
match the parameter names exactly. For a full list of options, see the
[filter parameters reference](https://developers.google.com/maps/documentation/placesinsights/reference/filter-params.md.txt).

### Query historical snapshots with snapshot_date

By default, Places Count functions query the most recent data snapshot available.
To analyze places data as it existed during a specific past month, add the
optional `snapshot_date` parameter to your `JSON_OBJECT`.

- **Format:** `YYYY-MM` (for example, `'2026-07'`).
- **Default:** If omitted, the function automatically queries the latest snapshot.

The following example queries restaurant counts around your search areas as
recorded in the July 2026 snapshot:

```googlesql
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
  )
);
```

In the next example, you apply filters to limit the search by minimum user
rating, price level, business status, and whether the restaurant allows dogs,
using the `PLACES_COUNT_V2` function.

First, use your input geography table or prepare one with the chosen
geographies:

> [!IMPORTANT]
> **Important:** You must create the dataset containing the input geographies table in the same region as the linked Places Insights dataset. If the locations don't match, BigQuery returns an error.

```googlesql
-- 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
);
```

Next, call `PLACES_COUNT_V2` with the table and the JSON object containing the
filters. The search radius is included in the JSON filters and will be applied
around each point in the `my_search_areas` table.

```googlesql
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
      )
);
```

> [!NOTE]
> **Note:** Include the `business_status` filter to make sure that you get the count of `OPERATIONAL` businesses. Otherwise, the count includes closed businesses.

### Example: Query restaurant counts and brand locations with PLACES_COUNT_V2

The following example uses the `PLACES_COUNT_V2` function with the custom input
geography table `my_search_areas` to return the number of operational
restaurants within 1000 meters of the Empire State Building and Times Square in
New York City in July 2026:

```googlesql
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'
      )
);
```

The response is a BigQuery table that contains the `geo_id`, the geography, the
count, and a sample of Place IDs.

![Results for Places Count function in New York City.](https://developers.google.com/static/maps/documentation/placesinsights/images/place_count_v2_overview.png)

The following example uses the `PLACES_COUNT_V2` function to filter by specific
brand IDs. In this example, we filter for Starbucks locations using the brand ID
`"1413758728321880760"`.

To find the brand IDs for the brands you want to filter by, query the `brands`
table for your dataset (for example, `places_insights___us.brands`). For more
information on the brands dataset, see [Write a query using brands
data](https://developers.google.com/maps/documentation/placesinsights/brands).

For example, to find the brand ID for "Starbucks":

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

After obtaining the brand IDs, you can use them in the `brand_ids` filter as
shown in the following query:

```googlesql
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"]
      )
);
```

> [!NOTE]
> **Note:** The required and optional parameters differ for each Places Count function as described in [filters](https://developers.google.com/maps/documentation/placesinsights/reference/filter-params.md.txt).

## Visualize query output with Google Cloud tools

Analysis and [business intelligence
tools](https://cloud.google.com/bigquery/docs/data-analysis-tools-intro) help
you discover insights from your BigQuery data. BigQuery supports several Google
and third-party [data visualization
tools](https://cloud.google.com/bigquery/docs/geospatial-visualize) that you can
use to analyze the results of your functions on Places Insights data.

For an example of visualizing the results of a function, see [Visualize results
inside the PLACES_COUNT_PER_H3
reference](https://developers.google.com/maps/documentation/placesinsights/place-count-functions/places-count-per-h3#visualize_results).
For more information on visualizing Places Insights results, see [Visualize
query results](https://developers.google.com/maps/documentation/placesinsights/visualize-data).

## Function limitations and requirements

Places Count functions have the following limitations and requirements:

- The functions only support `COUNT` insights.
- A minimum search area of 40.0 meters by 40.0 meters (1600 m^2^) (40.0 meters by 40.0 meters / 1,600 m²) is required.
- **Parameter Input Size Limit:** The JSON object passed as a parameter to the functions is limited to 1 MB. The impact of this limit depends on the function version:
  - *For V2 functions* (`PLACES_COUNT_V2`, `PLACES_COUNT_PER_TYPE_V2`, `PLACES_COUNT_CHANGE`), this limit applies only to the filters JSON object. Since geographies are provided separately using a table parameter, these functions can scale to a much larger number of input geographies without reaching the JSON size limit.
  - *For `PLACES_COUNT_PER_H3`, `PLACES_COUNT`, `PLACES_COUNT_PER_TYPE`, and
    `PLACES_COUNT_PER_GEO`*, this limit applies to the entire JSON object, including all geography definitions. This may limit the number of geographies that can be processed in a single call.
- No support for filtering by Place ID or address component.
- You can only access the Places Count functions for the cities and countries you have subscribed to. See [Set up
  Places Insights](https://developers.google.com/maps/documentation/placesinsights/cloud-setup) for dataset access.
- Filter parameters (for example, `geography` or `types`) are case-sensitive and must match the parameter names exactly, or the query will fail.