Pilgrim SDK allows geofencing around a configurable set of venues. Geofences can be set for the venues, categories, or chains of your choosing. By default, Foursquare will use its knowledge of the venue’s location to return the right fence for a given place. You may also configure a radius of your choosing, but we recommend letting Pilgrim pick the right one to give you the optimal experience.

Why use Geofences

For use cases that rely on accuracy, regular Pilgrim SDK visit events are superior to geofencing. However, there are certain instances where geofencing is preferable.

  • When speed and proximity to a specific subset of venues is more important than accurately detecting visits there.
  • When it’s more important to know if a user is nearby a certain place than visiting.
  • When you know a user is en route to a specific venue, and you want to know the second they arrive.

Geofencing runs independently alongside regular Pilgrim SDK visit detection so you can still get the benefit of understanding everywhere your users go while enabling additional use cases.

Event Types

Geofences have three event types that are delivered directly to the client and through an optional webhook.

Event Type Description
entrance Triggered on the first GPS signal that is received inside of the geofence.
dwell Triggered after the user has “dwelled” within the geofence for a configurable length of time. Default is 1 minute.
exit Triggered on the first GPS signal that is received outside of the geofence.

Receiving Events

To receive geofence events on the client, add the event handler below:

// In your implementation of the pilgrim delegate, add:
func pilgrimManager(_ pilgrimManager: PilgrimManager, handle geofenceEvents: [GeofenceEvent]) {
    // Code to handle geofenceEvents:
// In your implementation of the PilgrimNotificationHandler, add:
public void handleGeofenceEventNotification(Context context, PilgrimSdkGeofenceEventNotification pilgrimSdkGeofenceEventNotification) {
    // Code to handle event:
    // List<GeofenceEvent> geofenceEvents = pilgrimSdkGeofenceEventNotification.getGeofenceEvents();

Geofences will need to be set to a specific Foursquare venue, chain, or category (see below). For example, a partner could set up geofences for Foursquare HQ, all coffee shops, and all Chick-fil-a’s. A caveat here is that you cannot set up a geofence for an arbitrary lat/lng; this also means that some venue harmonization may need to take place beforehand if you already have a specific list of places you want to geofence. Geofences are set up globally across all users of the app.

A geofence event will contain the following:

Field Description
eventType entrance, dwell, or exit.
venue Same as regular pilgrim venue object.
categoryIDs Array of categoryIDs used by triggered geofence.
chainIDs Array of chainIDs used by triggered geofence.
partnerVenueID String of harmonized venueId.
location Object containing location information about the geofence event.
timestamp Unix/epoch timestamp in milliseconds of when the event occured.

Geofence Management

Geofences are set up through a CSV upload in the Pilgrim developer console. If you want to geofence an entire chain or category of venues, you only need to upload the category or chain ID once and Foursquare will manage all of the geofences globally.

CSV upload should contain a header row. Our importer will look for any of the headers below:

Field Description
name A custom string that you can set to help you identify rules. Ex: coffee shops
venue_ids optional A single venue’s foursquare venue id. Ex: "556f676fbd6a75a99038d8ec". Multiple entries are comma separated. "556f676fbd6a75a99038d8ec,556f676fbd6a75a99038d8ec".
category_ids optional A comma separated list of Foursquare category ids.
chain_ids optional A comma separated list of Foursquare chain ids.
dwell_time Dwell time (minutes) can be configured independently for each venue, category, or chain. Leaving dwell_time blank will default to using 1 minute as a default, where the user will be required to get 2 location points inside the geofence for trigger event to fire.
radius Defaults to 100 meters. Minimum 50 meters.

Sample file:

"Test Single Venue","556f676fbd6a75a99038d8ec",,,1,100
"Multiple Venues","556f676fbd6a75a99038d8ec,556f676fbd6a75a99038d8ec",,,1,200

Note: One of venue_ids, category_ids, or chain_ids is required. If different dwell times are set for a matching venue, chain, and category (i.e., Starbucks venue, coffee category, Starbucks chain), the order of precedence is venue > chain > category.