Request parameters

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

The Places Insights 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 insights. 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 Insights API. Each request must supply the following:

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

Insight type

Specifies the type of insights 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 matching the filter criteria.

  Note: If you select INSIGHT_PLACES, the Places Insights 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

Caution: Location filters that have a large or concentrated search space can time out. Searches across entire countries or continents are likely to fail due to the default network timeout of 60 seconds.

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: 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 Mexico). Requests with areas outside this range will return an INVALID_ARGUMENT error.

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.

• 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 Insights API returns a 400 error code with a message that indicates the region is not supported.

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.

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.

The following table lists unsupported place types. To determine if a place ID represents an unsupported place type, pass the place ID in a Geocoding API request. The response includes the type array listing the place types associated with the place ID, such as city, neighborhood, or country.

Unsupported Place Types
establishment	place_of_worship
floor	post_box
food	postal_code_suffix
general_contractor	room
geocode	street_address
health	street_number
intersection	sublocality_level_5
landmark	subpremise

Custom area

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

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.

You can visit https://geojson.io/ to draw a custom polygon and enter those coordinates into the request. A polygon 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:

"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 Insights API supports, see 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.

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 the places. Defaults to no filtering (all price levels are included in the results).
• 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 (such as operational or temporarily closed). If the operatingStatus filter is not set, only places with an operating status of OPERATING_STATUS_OPERATIONAL are included in the results.

Price level

With the price_levels filter, you can filter based on Price Level (such as free, moderate, or expensive). If the price_levels filter is not set, all price levels are included in the results.

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

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