This document provides a clear overview of all parameters within the Places Insights API. We'll cover each one in detail, offering insights and best practices to help you use this tool for your geographic data needs.
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
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 this option is selected, the Places Insights API returns place IDs
only if the count
is 100 or less.
Filter
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.custom_area
: Defines an area as a custom polygon.
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:
lat_lng
: 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 theplaces/
prefix.
radius
: Radius of the circle in meters. This number must be positive.
Region
You can define your area as a region using the place
parameter. Use a place ID
that represents a geographical area (such as an area representable by a
polygon). For example, the place ID of Tampa, FL is
places/ChIJ4dG5s4K3wogRY7SWr4kTX6c
.
Unsupported Region 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 |
You can use the types
field from a Geocoding API call to determine the
type of location or address associated with a place ID, such as whether it is a
city, neighborhood, or country.
Custom area
Defines the area of a custom polygon using coordinates.
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. Besides the first and last coordinate, there must not be any other duplicate coordinates. Additionally, non-adjacent edges are not allowed to intersect, and edges of length 180 degrees are not allowed (i.e., 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, refer to Table
A under Place Types guide for the Places API
(New). At least one included_types
or included_primary_types
type must be
included.
included_types
: List of included place types.excluded_types
: List of excluded place types.included_primary_types
: List of included primary place types.excluded_primary_types
: List of excluded primary place types.
To learn more about how type filters and place types work, visit more on type filters.
Optional parameters
The remaining three filters are optional:
operating_status
: Specifies the statuses of places to include or exclude. Defaults to filtering byoperating_status: OPERATING_STATUS_OPERATIONAL
(one specific value).price_levels
: Specifies the price levels of the places. Defaults to no filtering (all price levels are included in the results).rating_filter
: Specifies the rating range of the places. Defaults to no filtering (all ratings are included in the results).
Operating status
Filter based on Operating Status (such as operational or temporarily closed).
Price level
Filter based on Price Level (such as free, moderate, or expensive).
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.
min_rating
: Minimum average user rating (between 1.0 and 5.0).max_rating
: Maximum average user rating (between 1.0 and 5.0).