Query the dataset using Places Count functions

Places Count functions are predefined SQL queries that run in BigQuery and are complementary to querying the dataset directly. The main difference between querying the data directly and using a function is that functions don't enforce a minimum count threshold but instead enforce a minimum search area:

• Place datasets queries can only return counts 5 and above, but enforce no limitations on the size of the search area.
• 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²). Functions can also return Place IDs, which can be used to look up information about individual Places.

You might want to use Places Count functions if it's important to know when a query returns no results or if you need to know low counts of places below 5. It is also useful if you need to get individual place information to spot check your results.

Places Count functions only provide counts, so if you need to perform more complex queries such as data joins, or get additional insights such as the average rating of a group of places, then query the dataset directly.

Supported Places Count functions and countries

Places Insights supports the following functions:

• science PLACES_COUNT_V2: Returns a table containing place counts and sample Place IDs. This function accepts a table parameter for multi-geography input, enabling efficient batch processing. It is highly optimized for geospatial joins compared to PLACES_COUNT and PLACES_COUNT_PER_GEO functions.
• science PLACES_COUNT_PER_TYPE_V2: Returns a table of place counts and sample Place IDs, categorized by place type. Similar to PLACES_COUNT_V2, this function accepts a table parameter to process multiple input geographies simultaneously. This architecture supports efficient batch processing and provides optimized geospatial joining compared to PLACES_COUNT_PER_TYPE.
• PLACES_COUNT_PER_H3: Returns a BigQuery table of place counts per H3 cell.
• PLACES_COUNT: Returns a single row containing a count of places.
• PLACES_COUNT_PER_TYPE: Returns a BigQuery table of place counts per places type.
• PLACES_COUNT_PER_GEO: Returns a BigQuery table of place counts per geographies.

Along with the place counts, all functions except PLACES_COUNT also return up to 250 place IDs per element of the response.

Place IDs can be used with:

• Places API (New)
• Geocoding API
• Places UI Kit

Write queries with 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 listed in Reference place count functions in BigQuery. You can also optionally include your project name. If one is not included, the query will default to the active project.

For example:

PROJECT_NAME.places_insights___us.PLACES_COUNT

Use a JSON_OBJECT to pass arguments to the function.

Filter your results

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. See the filter parameters reference for a full list of options.

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:

-- 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.

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 function example

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

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

The response is a BigQuery table that contains the geo_id, the geography, the count, and a sample of place ids.

Visualize results

Analysis and business intelligence tools are crucial to helping you discover insights from your BigQuery data. BigQuery supports several Google and third-party data visualization tools 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. For more information and example on visualizing Places Insights results, see Visualize query results.

Limitations and requirements

Places Count functions have the following limitations and requirements:

• Only COUNT insights are supported.
• A minimum search area of 40.0 meters by 40.0 meters (1600 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), 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, brands, EV charge options, 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 for dataset access.
• Filter parameters (for example, geography or types) are case-sensitive and must match the parameter names exactly, or query will fail.

Reference Places Count functions in BigQuery

All of the cities in the sample dataset and the countries full dataset support Places Count functions.

You have access to the Places Count functions corresponding to the cities and countries datasets you have subscribed to. See Set up Places Insights for dataset access.

These tables list the available cities, countries, and their corresponding table names.

Sample data

Full data