## Places Insights data

Places Insights provides [full and sample
datasets](https://developers.google.com/maps/documentation/placesinsights/cloud-setup#available-listings) in
BigQuery.

The sample datasets are intended to allow you to try out Places Insights so
that you can assess the usability and value of the product before making a
decision to purchase the full dataset. The sample dataset only contains data for
the city itself. It does not contain data for the surrounding metropolitan area.

The sample listing includes data for a top city for each of the supported
countries:

- Amsterdam (NL)
- Ankara (TR)
- Arequipa (PE)
- Athens (GR)
- Bad Gastein (AT)
- Berlin (DE)
- Brno (CZ)
- Brussels (BE)
- Bucharest (RO)
- Buenos Aires (AR)
- Busan (KR)
- Cairo (EG)
- Chiang Mai (TH)
- Copenhagen (DK)
- Cork (IE)
- Debrecen (HU)
- Hanoi (VN)
- Helsinki (FI)
- Hong Kong (HK)
- Jakarta (ID)
- Jeddah (SA)
- Johannesburg (ZA)
- Kuala Lumpur (MY)
- Lisbon (PT)
- London (GB)
- Lusail (QA)
- Madrid (ES)
- Manila (PH)
- Medellín (CO)
- Mexico City (MX)
- Mumbai (IN)
- New York City (US)
- Oslo (NO)
- Paris (FR)
- Plovdiv (BG)
- Riffa (BH)
- Rome (IT)
- Santiago (CL)
- Sao Paulo (BR)
- Sharjah (AE)
- Singapore (SG)
- Stockholm (SE)
- Sydney (AU)
- Taipei (TW)
- Tel Aviv-Yafo (IL)
- Tokyo (JP)
- Toronto (CA)
- Warsaw (PL)
- Wellington (NZ)
- Zurich (CH)

The full datasets include data for each supported country and must be purchased.
If you are interested in signing up for Places Insights, fill out [the request
form](https://mapsplatform.google.com/assets/geo-analytics-sample-data/).
Only the data subscriber needs to request access to the Places Insights
dataset. Once the subscription is active in a BigQuery project, any user with
access to that project can query the Places Insights data.

Each country dataset has its own listing that you must subscribe to separately.
For more information on subscribing to a listing, see [Set up Places
Insights](https://developers.google.com/maps/documentation/placesinsights/cloud-setup).

### Dataset schemas

The places dataset schema for each country is comprised of two parts:

- The [core schema](https://developers.google.com/maps/documentation/placesinsights/reference/core-schema.md.txt) that is common to the datasets for all countries.
- A [country-specific schema](https://developers.google.com/maps/documentation/placesinsights/reference/country-schema.md.txt) that defines schema components specific to that country.

For example, if you are working with the dataset for Spain (ES), reference both
the core schema and the ES-specific schema.

The schema for the brands dataset defines three fields:

- `id`: The brand ID.
- `name`: The name of the brand, such as "Hertz" or "Chase".
- `category`: The high-level category of the brand, such as "Gas Station", "Food and Drink", or "Lodging".

> [!NOTE]
> **Note:** Brands data is only available for the United States, Canada, United Kingdom, and Australia in the current release.

## Query Places Insights data

Places Insights offers two ways to query the datasets:

- **Query the dataset directly using SQL** : Execute standard BigQuery SQL queries against the dataset tables. This provides the most flexibility for complex filtering, joining with your own data, custom analysis, and support for additional aggregation functions beyond `COUNT`, such as `AVG`, `SUM` and `GROUP BY`. [See the
  documentation](https://developers.google.com/maps/documentation/placesinsights/queries).
- **Query the dataset using Places Count functions** : Places Count functions are predefined, optimized SQL queries that run directly in BigQuery and simplify common data retrieval tasks. They provide more granular insights such as returning Place IDs to look up details about individual places. [See
  the
  documentation](https://developers.google.com/maps/documentation/placesinsights/get-started#select_the_optimal_places_count_function).

### Direct queries

Querying the data directly enforces an aggregation threshold. A result is
returned only if the query aggregates at least 5 Places. For example, if your
search criteria result is a count of 0, 1, 2, 3, or 4, then the result is
omitted from the response. For example, a query for the total count of
restaurants in a given area, will only return a response if the total count is 5
or higher, otherwise no response is returned.

### Places Count function queries

Places Count functions can return a list of Place IDs, which can be used to look
up individual place information using other GMP products like the [Places
API](https://developers.google.com/maps/documentation/places/web-service/place-details) and the [Places UI
Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/get-started).

Places Count functions don't enforce an aggregation threshold, but instead
enforce a minimum search area of 40.0 meters by 40.0 meters (1600 m^2^). This means that as long as
your search query is larger than the minimum search area, you will always get a
result, including if there are 0 places matching your query.

### When to query the data directly and when to use functions

Query the data directly if you don't need low result counts, if you want to get
insights beyond counts, such as `AVG`, `SUM`, or `COUNTIF`, or if you need to
perform more complex queries such as joining datasets.

Query using the functions if you need to know if there are a low number or zero
results, or if you need to retrieve individual place information such as place
name or address.

This table provides a detailed comparison of the differences between direct
queries and Places Count functions.

|   | Places Count functions | Direct dataset queries |
|---|---|---|
| **Benefits** | - Returns Place IDs that can be used to query other APIs. - Can return any count. - Optimized for performance and low processing cost. - Simple to use. No need to write complex queries. - Validates the input parameters and returns an error making it easier to use and debug. | - Allows for complex queries such as advanced filtering and joins. - Does not enforce a minimum search area. - Supports additional aggregate functions beyond `COUNT` such as `AVG`, `SUM`, and `GROUP BY`. |
| **Interface** | Four predefined SQL functions that generate `COUNT` insights: single count, count per type, count per geography, count per H3 cell. A `JSON_OBJECT` passes arguments to the function. | Write your own SQL to run aggregation functions such as `COUNT`, `COUNT_IF`, `SUM`, and `AVG.` Additional insights can be generated using `JOIN`, `GROUP BY`, `WHERE`, and others. |
| **Restrictions** | Enforces a minimum search area of 40.0 meters by 40.0 meters (1600 m^2^). A function returns a result even if the aggregation count is less than 5 as long as the minimum search area is met. | Results with counts less than 5 are omitted from the results (i.e., row is excluded). |
| **Supported attribute filters** | [Places Count function filter parameters](https://developers.google.com/maps/documentation/placesinsights/reference/filter-params.md.txt) support the same as the direct query attribute filters except for: - Place `id` - Address components | [Full schema](https://developers.google.com/maps/documentation/placesinsights/reference.md.txt) supported. |