Places

Places is available on the Enterprise plan.

With Places, you can use our points-of-interest (POI) database to detect when a user visits a place, chain, or category, even if you haven't set up geofences for those places.

Our database includes millions of places around the world from open and commercial datasets, with coverage for major chains (like McDonald's or Walmart) and categories (like airports or stadiums), often with accurate polygon geometry and additional metadata like address or operating hours.

Places provides the following user context:

{  "place": {    "name": "Starbucks",    "chain": {      "name": "Starbucks",      "slug": "starbucks",      "externalId": "123",      "metadata": {        "customFlag": true      }    },    "categories": ["food-beverage", "coffee-shop"],    "location": {      "type": "Point",      "coordinates": [-73.977797, 40.783826]    }  }}

Places also provides the following events:

user.entered_place
user.exited_place

You can receive events client-side via the SDK or server-side via event integrations, including webhooks.

You can enable Places on the Settings page.

Alternatively, if you have your own custom place data, you can create geofences instead. Learn more about Geofences.

Quickstart#

First, sign up for Radar and get an API key.

Then, enable Places events and enable chains or categories on the Settings page.

From there, integrate the SDK and call Radar.trackOnce() or Radar.startTracking(), depending on your use case. Radar will generate an entry event on the first stopped location update at a place matching your enabled chains or categories.

How it works#

Radar generates a place entry event if a user stops at a place (i.e., when stopped is true based on tracking options or when foreground is true) matching filters with sufficient confidence, then a place exit event when the user leaves the place with sufficient confidence.

All place events have confidence levels, and places may have one or more categories and a chain.

Confidence#

All place events have confidence levels. Confidence levels range from 1 (low) to 3 (high). Confidence is a function of the accuracy of the location reported by the device, the footprint of the place, the density of the area, the popularity of the place, and other signals.

You may decide to ignore events based on confidence levels.

Categories#

Places may have one or more categories. Radar supports hundreds of categories, organized in a hierarchy. View the full list of categories.

You can listen for place events with specific categories. For example, to do something if a user is at an airport, on iOS:

Radar.trackOnce { (status, location, events, user) in    if let place = user?.place,       place.hasCategory("airport") {        // do something    }}

Chains#

Places may have a chain. Radar supports thousands of U.S. and international chains. View the full list of chains.

You can listen for place events with specific chains. For example, to do something when a user stops at a Starbucks, on Android:

public void onEventsReceived(Context context,                             RadarEvent[] events,                             RadarUser user) {    for (RadarEvent event : events) {        if (event.type == RadarEventType.USER_ENTERED_PLACE &&            event.confidence == RadarEventConfidence.HIGH &&            event.place.isChain("starbucks")) {            // do something        }    }}

Mappings#

To map Radar chain slugs to custom IDs, set Chain mappings under Places on the Settings page.

You can set a JSON string representing a dictionary with keys and values of type string.

For example, to map burger-king to 123 and mcdonalds to 456:

{ "burger-king": "123", "mcdonalds": "456" }

Custom chain IDs will be exposed as place.chain.externalId in user context and events. These custom IDs can also be used in place of chain slugs when performing searches with the search places API.

Metadata#

To map Radar chain slugs to custom metadata, set Chain metadata under Places on the Settings page.

You can set a JSON string with values of type dictionary, each with between 1 and 16 keys and values of type string, boolean, or number.

For example, to map metadata.category and metadata.offers for burger-king and mcdonalds:

{  "burger-king": { "category": "Restaurant", "offers": true },  "mcdonalds": { "category": "Restaurant", "offers": false }}

Custom chain metadata will be exposed as place.chain.metadata in user context and events.

Place filters#

We recommend filtering events to specific categories or chains under Places on the Settings page.

For example, to monitor only fast food restaurants, you might add fast-food-restaurant to category filters, or add burger-king, mcdonalds, and others to chain filters.

View the full list of categories and the full list of chains.

State blocklist#

To suppress tracking specific place categories in certain states, set Category state blocklist mapping under Places on the Settings page.

For example, blocking the fast-food-restaurant category in New York would bypass visits to fast-food-restaurant places in New York.

Regions must be enabled to expose this setting.

Verify events#

You can accept or reject places events after user check-ins or other forms of verification. Event verifications will be used to improve the accuracy and confidence level of future events.

For example, to accept an event on iOS:

Radar.acceptEventId(event._id, verifiedPlaceId: event.alternatePlaces[0]._id)

Place matching#

Place matching is available on the Enterprise plan.

Place matching is the easiest way to make sure your geofence coordinates and geometries are accurate and stay up-to-date over time. Place matching will ensure that entry and exit events are reliable, trip approaching and arrived signals are precise, and messaging for nearby locations is relevant.

Navigate to the Geofences page and select Import. If Places are enabled for your project, toggle Enable place matching on.

How it works#

Import your geofences against Radar's places data. Select chains to match your geofences against while importing your geofences into Radar.
View the results of place matching. After the import has completed, look at the results on the Import history page. Click View import to see a summary and logs that indicate the outcome for each row. If the place match was successful, the import log will contain a link to the Radar place and the distance that the geofence center was corrected.
Filter and export the results for further analysis. Apply Filters to isolate rows that were not place matched, geofences that have large center correction values, or errors. Click Export rows to download a CSV of the results.

Geofence types#

circle: When a circle geofence is matched, it will take on the geometry of the Radar place.
polygon: When a polygon geofence is matched, it will be linked to the Radar place, but not adopt the place center or geometry.
isochrone: When an isochrone geofence is matched, it will only take on the center of the Radar place, regenerating the isochrone geometry from the new center.

Advanced options#

Search radius. Place matching will look for the nearest location within 10 kilometers by default. This value can be reduced to enforce a tighter search distance.
Geofence tag(s). Filter the rows to place match. For example, only perform place matching on rows where tag = store but not tag = nearby.
Use Radar's place geometry. By default, circle geofences will adopt both the center and geometry of the Radar place. Toggle this off for circle geofences to take on the center but not the geometry.