Places

Contents

Introduction

Radar can tell you when a user visits a place, chain, or category, even if you haven't set up a geofence for that place.

Radar is integrated with Facebook Places, the same place database that powers Facebook and Instagram, with over 140M places worldwide. We also ingest and curate place data from other sources, providing you with a comprehensive view of the world.

Enable Places to receive the following events:

  • user.entered_place
  • user.exited_place

You can enable Places on the Settings page, under Places.

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

Quickstart

Want to get started quickly? Follow these three steps:

  1. Start tracking. Integrate the SDK to start tracking users. Or, test with our toolkit apps for iOS or Android. Don't forget to install and configure the Facebook SDK, then set Facebook as your place data provider.

  2. Add context. Enable Places on the Settings page, under Places. Optionally, set category and chain filters to restrict the categories and chains monitored.

  3. Handle events. Handle places events client-side or server-side via webhooks or integrations.

How it works

Radar uses Facebook Places to determine if a user is at a place. Radar generates events when a user enters or exits a place with sufficient confidence. If Radar or Facebook is unsure, Radar may not generate an event. Places works in the foreground and in the background.

All place events have confidence levels, and places may have one or more categories and a chain. Confidence, categories, and chains are described in detail below.

Confidence

All place events have confidence levels. Confidence levels range from 1 (low) to 3 (high). Confidence will be low for less-visited places or in areas of high density, and high for more-visited places or in areas of low density.

You can ignore events based on confidence levels. For example, to ignore place events with low confidence, via a webhook:

app.post('/webhooks/radar', (req, res, next) => {
    const event = req.body.event;
    if (event.type === 'user.entered_place' &&
        event.confidence > 1) { // 1 === low, 2 === medium, 3 === high
        // do something
    }
}

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
        }
    }
}

Place filters

In addition to filtering events programmatically, you can also filter 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.

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)

To reject an event on Android:

Radar.rejectEvent(event._id);

Report inaccurate places

In addition to verifying events, you can report missing or inaccurate place data to Facebook. Click the Facebook ID on the Place page. Then, on Facebook, go to the place's About page and click Suggest Edits.

Support

Have questions after reading the documentation? We're here to help! Click the button on the bottom right of any page to chat with us, or email us at [email protected].