Geofences - Foursquare Developer

Available since version 2.0.0, Pilgrim SDK allows geofencing around a configurable set of venues or points. 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.

In SDK version 2.2.0, support for polygon shapes and arbitrary latitude/longitude points is also available. This allows greater customization and removes the reliance upon geofencing only Foursquare venue locations.

Why use Geofences

For use cases that rely on accuracy, regular Pilgrim SDK place visit detection is 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 rather than visiting.
When you want to track when users that are en-route to a specific venue, and you want to know as soon as 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 five potential 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.
venue confirmed	Triggered when the device has dwelled inside a geofence radius and confirmed a stop at the venue within the radius. Only available in SDK versions 2.1.2 or greater
exit	Triggered on the first GPS signal that is received outside of the geofence.
presence	Triggered when the device is in a geofence radius during a get location request. Only available in SDK versions 2.1 or greater

Receiving Events

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

Swift (iOS) Java (Android)

// 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:
@Override
public void handleGeofenceEventNotification(Context context, PilgrimSdkGeofenceEventNotification pilgrimSdkGeofenceEventNotification) {
    List<GeofenceEvent> geofenceEvents = pilgrimSdkGeofenceEventNotification.getGeofenceEvents();
    // Code to handle geofenceEvents...
}

Geofences will need to be set to a specific Foursquare venue, chain, category or shape (see below). For example, a partner could set up geofences for Foursquare HQ, all coffee shops, and all Chick-fil-a’s. You can also set up a geofence for an arbitrary lat/lng or custom polygon shapes. For Foursquare venues, this means that some venue harmonization may need to take place beforehand if you already have a specific list of places you want to geofence.

Note: Geofences are set up globally across all users of the app. User specific geofences are not yet something we provide.

A geofence event will contain the following:

Field	Description
eventType	`entrance`, `dwell`, `venueConfirmed`, `exit`, or `presence`.
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.

Webhook Examples

Enter Dwell Venue Confirmed Exit Presence

{
    "eventType":"geofenceEnter",
    "timestamp":1545078269223,
    "geofenceEvent":{
        "eventType":"entrance",
        "eventLat":41.8893897,
        "eventLng":-87.6297896,
        "radius":100.0,
        "venueId":"4a9037fef964a5209b1620e3",
        "categoryIds":"4bf58dd8d48988d1e0931735",
        "chainIds":"",
        "venues":[
            {
                "id":"4a9037fef964a5209b1620e3",
                "name":"Einstein Bros Bagels",
                "location":{
                    "address":"400 N Dearborn St",
                    "crossStreet":"",
                    "city":"Chicago",
                    "state":"IL",
                    "postalCode":"60654",
                    "country":"US",
                    "lat":41.8893897,
                    "lng":-87.6297896
                },
                "categories":[
                    {
                        "id":"4bf58dd8d48988d179941735",
                        "name":"Bagel Shop",
                        "pluralName":"Bagel Shops",
                        "shortName":"Bagels",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                            "suffix":".png"
                        }
                    },
                    {
                        "id":"4bf58dd8d48988d1e0931735",
                        "name":"Coffee Shop",
                        "pluralName":"Coffee Shops",
                        "shortName":"Coffee Shop",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                            "suffix":".png"
                        }
                    }
                ],
                "venueChains":[
                    {
                        "id":"556ce8d9aceaff43eb0588d6",
                        "name":"Einstein Bros."
                    }
                ]
            }
        ]
    },
    "lat":41.88928251303856,
    "lng":-87.62870316744883,
    "user":{
        "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
        "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
    },
    "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
    "sdkType":"iossdk"
}

{
    "eventType":"geofenceDwell",
    "timestamp":1545078408140,
    "geofenceEvent":{
        "eventType":"dwell",
        "eventLat":41.8893897,
        "eventLng":-87.6297896,
        "radius":100.0,
        "venueId":"4a9037fef964a5209b1620e3",
        "categoryIds":"4bf58dd8d48988d1e0931735",
        "chainIds":"",
        "venues":[
            {
                "id":"4a9037fef964a5209b1620e3",
                "name":"Einstein Bros Bagels",
                "location":{
                    "address":"400 N Dearborn St",
                    "crossStreet":"",
                    "city":"Chicago",
                    "state":"IL",
                    "postalCode":"60654",
                    "country":"US",
                    "lat":41.8893897,
                    "lng":-87.6297896
                },
                "categories":[
                    {
                        "id":"4bf58dd8d48988d179941735",
                        "name":"Bagel Shop",
                        "pluralName":"Bagel Shops",
                        "shortName":"Bagels",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                            "suffix":".png"
                        }
                    },
                    {
                        "id":"4bf58dd8d48988d1e0931735",
                        "name":"Coffee Shop",
                        "pluralName":"Coffee Shops",
                        "shortName":"Coffee Shop",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                            "suffix":".png"
                        }
                    }
                ],
                "venueChains":[
                    {
                        "id":"556ce8d9aceaff43eb0588d6",
                        "name":"Einstein Bros."
                    }
                ]
            }
        ]
    },
    "lat":41.889335266663636,
    "lng":-87.62856037188838,
    "user":{
        "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
        "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
    },
    "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
    "sdkType":"iossdk"
}

{
    "eventType":"geofenceVenueConfirmed",
    "timestamp":1545078428140,
    "geofenceEvent":{
        "eventType":"venueConfirmed",
        "eventLat":41.8893897,
        "eventLng":-87.6297896,
        "radius":100.0,
        "venueId":"4a9037fef964a5209b1620e3",
        "categoryIds":"4bf58dd8d48988d1e0931735",
        "chainIds":"",
        "venues":[
            {
                "id":"4a9037fef964a5209b1620e3",
                "name":"Einstein Bros Bagels",
                "location":{
                    "address":"400 N Dearborn St",
                    "crossStreet":"",
                    "city":"Chicago",
                    "state":"IL",
                    "postalCode":"60654",
                    "country":"US",
                    "lat":41.8893897,
                    "lng":-87.6297896
                },
                "categories":[
                    {
                        "id":"4bf58dd8d48988d179941735",
                        "name":"Bagel Shop",
                        "pluralName":"Bagel Shops",
                        "shortName":"Bagels",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                            "suffix":".png"
                        }
                    },
                    {
                        "id":"4bf58dd8d48988d1e0931735",
                        "name":"Coffee Shop",
                        "pluralName":"Coffee Shops",
                        "shortName":"Coffee Shop",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                            "suffix":".png"
                        }
                    }
                ],
                "venueChains":[
                    {
                        "id":"556ce8d9aceaff43eb0588d6",
                        "name":"Einstein Bros."
                    }
                ]
            }
        ]
    },
    "lat":41.889335266663636,
    "lng":-87.62856037188838,
    "user":{
        "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
        "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
    },
    "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
    "sdkType":"iossdk"
}

{
    "eventType":"geofenceExit",
    "timestamp":1545091987992,
    "geofenceEvent":{
        "eventType":"exit",
        "eventLat":41.8893897,
        "eventLng":-87.6297896,
        "radius":100.0,
        "venueId":"4a9037fef964a5209b1620e3",
        "categoryIds":"4bf58dd8d48988d1e0931735",
        "chainIds":"",
        "venues":[
            {
                "id":"4a9037fef964a5209b1620e3",
                "name":"Einstein Bros Bagels",
                "location":{
                    "address":"400 N Dearborn St",
                    "crossStreet":"",
                    "city":"Chicago",
                    "state":"IL",
                    "postalCode":"60654",
                    "country":"US",
                    "lat":41.8893897,
                    "lng":-87.6297896
                },
                "categories":[
                    {
                        "id":"4bf58dd8d48988d179941735",
                        "name":"Bagel Shop",
                        "pluralName":"Bagel Shops",
                        "shortName":"Bagels",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                            "suffix":".png"
                        }
                    },
                    {
                        "id":"4bf58dd8d48988d1e0931735",
                        "name":"Coffee Shop",
                        "pluralName":"Coffee Shops",
                        "shortName":"Coffee Shop",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                            "suffix":".png"
                        }
                    }
                ],
                "venueChains":[
                    {
                        "id":"556ce8d9aceaff43eb0588d6",
                        "name":"Einstein Bros."
                    }
                ]
            }
        ]
    },
    "lat":41.88709567122635,
    "lng":-87.63105850113463,
    "user":{
        "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
        "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
    },
    "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
    "sdkType":"iossdk"
}

{
    "eventType":"geofencePresence",
    "timestamp":1549553712000,
    "geofenceEvent":{
        "eventType":"presence",
        "eventLat":41.8893897,
        "eventLng":-87.6297896,
        "radius":100.0,
        "venueId":"4a9037fef964a5209b1620e3",
        "categoryIds":"4bf58dd8d48988d1e0931735",
        "chainIds":"",
        "venues":[
            {
                "id":"4a9037fef964a5209b1620e3",
                "name":"Einstein Bros Bagels",
                "location":{
                    "address":"400 N Dearborn St",
                    "crossStreet":"",
                    "city":"Chicago",
                    "state":"IL",
                    "postalCode":"60654",
                    "country":"US",
                    "lat":41.8893897,
                    "lng":-87.6297896
                },
                "categories":[
                    {
                        "id":"4bf58dd8d48988d179941735",
                        "name":"Bagel Shop",
                        "pluralName":"Bagel Shops",
                        "shortName":"Bagels",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                            "suffix":".png"
                        },
                        "primary":true
                    },
                    {
                        "id":"4bf58dd8d48988d1e0931735",
                        "name":"Coffee Shop",
                        "pluralName":"Coffee Shops",
                        "shortName":"Coffee Shop",
                        "icon":{
                            "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                            "suffix":".png"
                        }
                    }
                ],
                "venueChains":[
                    {
                        "id":"556ce8d9aceaff43eb0588d6",
                        "name":"Einstein Bros."
                    }
                ]
            }
        ]
    },
    "lat":41.889356,
    "lng":-87.628725,
    "user":{
        "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
        "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
    },
    "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
    "sdkType":"iossdk"
}

Geofence Management

Geofences can be 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.

To manage geofences via API, please see our Geofence API docs.

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

Field		Description
name	required	A custom string that you can set to help you identify rules. Ex: `coffee shops` or `Polygon of park in NYC`
venue_ids	optional	A single venue’s Foursquare venue id. Ex: `556f676fbd6a75a99038d8ec`
category_ids	optional	A single Foursquare category id. Ex: `4bf58dd8d48988d111941735`
chain_ids	optional	A single Foursquare chain id. Ex: `556e0690a7c82e6b724e70ae`
points	optional	For arbitrary lat/lng: A single comma separated latitude and longitude pair. Ex: `37.7901332,-122.4088525` For polygons: A semi-colon separated list of at least 3 latitude and longitude pairs. Ex: `37.7901332,-122.4088525;...;37.7901332,-122.4088525` Note: When drawing polygons, make sure the first and last points match.
dwell_time	optional	The number of minutes where the user will be required to get 2 location points inside the geofence for a “dwell” event to fire. Defaults to 1 minute.
radius	optional	The geofences’s radius in meters. Does not apply to polygon geofences. Minimum: 50 meters. Maximum: 5,000 meters. Defaults to 50 meters.

Sample file:

name,venue_ids,category_ids,chain_ids,points,dwell_time,radius
"Venue Example","556f676fbd6a75a99038d8ec",,,,1,50
"Category Example",,"4bf58dd8d48988d111941735",,,2,100
"Arbitrary LatLng",,,,"37.79013322796654,-122.40885257720946",5,50
"Polygon",,,,"37.79013322796654,-122.40885257720946;37.790845424906784,-122.40404605865479;37.79805179347195,-122.40554809570311;37.79013322796654,-122.40885257720946",10,

Note: One of venue_ids, category_ids, chain_ids or points 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.