This document describes the request parameters for Places Aggregate API and includes
insights and best practices for using this service.

The Places Aggregate API lets you perform several key functions:

- **Count places**: Determine the number of places that match specific criteria, such as location type, operating status, price level, and ratings.
- **Retrieve place details**: Obtain the names of places that meet the specified filters, then fetch more detailed information using the Places API.
- **Flexible filtering** : Apply comprehensive filters to get precise aggregates. Available filters include the following:
  - Geographic area (circle, region, or custom polygon)
  - Place types
  - Operating status
  - Price levels
  - Rating ranges

## Required parameters

This section covers the required parameters when issuing a request to the
Places Aggregate API. Each request must supply the following:

- A type of insight.
- A location filter and type filter.

### Insight type

Specifies the type of insight you want to compute. The following insight types
are supported:

- `INSIGHT_COUNT`: Returns the number of places matching filter criteria.
- `INSIGHT_PLACES`: Returns the [place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) matching the filter criteria.

> [!NOTE]
> **Note:** If you select `INSIGHT_PLACES`, the Places Aggregate API returns place IDs only if the `count` is 100 or less.

### Filters

Specifies the criteria for filtering places. At a minimum, you must specify the
`LocationFilter` and `TypeFilter`.

#### Location filter

A location filter can have one of the following types:

- `circle`: Defines an area as a circle with a center and radius.
- `region`: Defines an area as a region.
- `customArea`: Defines an area as a custom polygon.

> [!IMPORTANT]
> **Important:** The area for any location filter must be between 1556.86 square meters (approximately the size of a small city block) and 2 trillion square meters (approximately the size of Alaska). Requests with areas outside this range will return an `INVALID_ARGUMENT` error.

> [!NOTE]
> **Note:** For entities with defined polygonal boundaries such as parks or airports, the entity is considered to be within the search area if any part of its polygon intersects with the defined search area (circle, region, or custom polygon). The entity's center point does not need to be within the search area.

##### Circle

If you select your geographical area as a circle, you need to provide a `center`
and a `radius`. The `center` can be either a latitude and longitude, or the
Place ID of the center of the circle. This method allows for precise and
accurate filtering based on your defined circular region.

- `center`:
  - `latLng`: Latitude and longitude of the center of the circle. Latitudes must be a number between -90, 90, inclusive. Longitude must be a number between -180, 180, inclusive.
  - `place`: Place ID of the center of the circle. Note that only point places are supported. This string must start with the `places/` prefix.
- `radius`: Radius of the circle in meters. This number must be positive.

##### Region

Define your area as a region by passing a place ID to the `place` parameter. The
place ID represents a geographical area (such as an area representable by a
polygon). For example, the place ID of Tampa, FL is
`places/ChIJ4dG5s4K3wogRY7SWr4kTX6c`. Note that not all place IDs have a
well-defined geometry and in these cases Places Aggregate API returns a 400 error
code with a message that indicates the region is not supported. Additionally,
for complex geographical regions, internal processing optimizations might lead
to a slight over-approximation of the area (up to 2-3%) that represents the
region.

> [!IMPORTANT]
> **Important:** When using the `region` filter with the `INSIGHT_PLACES` insight type, requests that include disputed areas are automatically rejected to ensure the accuracy and neutrality of Google services. Disputed areas are regions with conflicting boundaries or territorial claims by different countries or entities. Disputed boundaries are displayed as a dashed gray line on Google Maps.
>
> For more information on how disputed regions are identified, see
> [Understand country borders and names](https://support.google.com/maps/answer/3145721).

> [!IMPORTANT]
> **Important:** Google doesn't support certain place IDs that belong to the following kinds of region types:
>
> - Regions types that are so large that they result in high latency.
> - Region types that are so small that they compromise privacy compliance.

To determine if a place ID represents an unsupported place type, pass the place
ID in a [Geocoding API](https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types) request. The response includes the `type` array
listing the place types associated with the place ID, such as `locality`,
`neighborhood`, or `country`. A place will be rejected for region filtering if
*any* of its types match this list.

**Unsupported place types include:**

- `establishment`: typically indicates a place that has not yet been categorized.
- `intersection`: indicates a major intersection, usually of two major roads.
- `subpremise`: indicates an addressable entity below the premise level, such as an apartment, unit, or suite.

> [!NOTE]
> **Note:** Even some places *not* listed above may be rejected if they lack a well-defined polygon geometry. This is more common with types like `neighborhood`, `locality`, `sublocality`, and its numbered variants (`sublocality_level_1`, `sublocality_level_2`, `sublocality_level_3`, `sublocality_level_4`). A 400 error code is returned in this case.

##### Custom area

Defines the area of a custom polygon using latitude and longitude coordinates.

> [!IMPORTANT]
> **Important:** Coordinates defining the vertices of the polygon must be listed in *counter-clockwise* order. This follows the industry standard convention for defining polygons, where counter-clockwise order indicates the interior of the polygon lies to the left of the boundary edges.

> [!IMPORTANT]
> **Important:** Custom areas must have 7000 vertices or fewer.

You can visit [](https://geojson.io/)<https://geojson.io/> to
draw a custom polygon and enter those coordinates into the request. A
[polygon](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6) must have at minimum 4 coordinates, where the first and last
coordinates are identical. At least 3 of the provided coordinates must be
unique.

Consecutively identical coordinates will be treated as a single coordinate.
However, non-consecutive duplicate coordinates (other than the required
identical first and last coordinates) will result in an error.

Additionally, non-adjacent edges are not allowed to intersect, and edges of
length 180 degrees are not allowed (that is, adjacent vertices cannot be
antipodal).

For example:

```json
"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
   }
]
```

#### Type filter

Specifies the types of places to include or exclude. For a list of both primary
and secondary place types that the Places Aggregate API supports, see [Table
A](https://developers.google.com/maps/documentation/places/web-service/place-types#table-a) under **Place Types** for the Places API
(New). You must specify at least one `includedTypes` or `includedPrimaryTypes`
type.

- `includedTypes`: List of included place types.
- `excludedTypes`: List of excluded place types.
- `includedPrimaryTypes`: List of included primary place types.
- `excludedPrimaryTypes`: List of excluded primary place types.

To learn more about how type filters and place types work, see [more on type
filters](https://developers.google.com/maps/documentation/places-aggregate/more-on-type-filters).

> [!NOTE]
> **Note:** Type filters automatically include subtypes of the specified types. For example, if you filter by `gym`, the results also include places that are categorized under its subtypes, such as `yoga_studio`.

## Optional parameters

These filters are optional:

- `operatingStatus`: Specifies the statuses of places to include or exclude. Defaults to filtering by `operatingStatus: OPERATING_STATUS_OPERATIONAL` (one specific value).
- `priceLevels`: Specifies the price levels of places to include. By default, no price level filtering is applied, and all places (including those without price level information) are returned.
- `ratingFilter`: Specifies the rating range of the places. Defaults to no filtering (all ratings are included in the results).

### Operating status

With the `operatingStatus` filter, you can filter based on [Operating Status](https://developers.google.com/maps/documentation/places-aggregate/reference/rest/v1/TopLevel/computeInsights.md.txt#operatingstatus)
such as `OPERATIONAL` or `TEMPORARILY_CLOSED`. The `operatingStatus` filter
behavior works as follows:

- If no filters have been provided, only places with an operating status of `OPERATING_STATUS_OPERATIONAL` are included in the results.
- If one or more filters are provided, you must specify valid operating status values (`OPERATING_STATUS_OPERATIONAL`, `OPERATING_STATUS_PERMANENTLY_CLOSED`, or `OPERATING_STATUS_TEMPORARILY_CLOSED`).

### Price level

With the `priceLevels` filter, you can filter places based on their [Price
Level](https://developers.google.com/maps/documentation/places-aggregate/reference/rest/v1/TopLevel/computeInsights#pricelevel). Valid price level values are: `PRICE_LEVEL_FREE`,
`PRICE_LEVEL_INEXPENSIVE`, `PRICE_LEVEL_MODERATE`, `PRICE_LEVEL_EXPENSIVE`, and
`PRICE_LEVEL_VERY_EXPENSIVE`.

The behavior of the `priceLevels` filter is as follows:

- **If no filters are provided:** All places are returned, **regardless of
  whether they have a price level assigned**. This includes places without price level information, which may not be returned when filtering by specific price levels.
- **If one or more filters are provided:** Only places matching the specified price level(s) are returned.

### Rating filter

Filters places based on their average user ratings. Both these fields are
optional and so if they're omitted, they will default to also include places
that don't have a rating.

- `minRating`: Minimum average user rating (between 1.0 and 5.0).
- `maxRating`: Maximum average user rating (between 1.0 and 5.0).

Additionally, the `minRating` value must always be less than or equal to the
`maxRating` value. If `minRating` is specified as greater than `maxRating`, an
`INVALID_ARGUMENT` error is returned.