• Android v15+ (ICE_CREAM_SANDWICH_MR1)

Getting your Foursquare API keys

If you do not have a Foursquare API key whitelisted for Pilgrim access, read our guide on Foursquare API Access.


1. Adding the dependency

Foursquare must whitelist your app to enable access to the Pilgrim SDK.

Request Access

Once you have been given a username and password from Foursquare, you can access the repository that has the Pilgrim SDK. Add the following snippet to your root build.gradle file and you will be able to resolve the library.

allprojects {
    repositories {
        maven {
            url ''
            credentials {
                username 'Provided username'
                password 'Provided password'

Then in the build.gradle file for the project you would like to include the Pilgrim SDK in just add

compile 'com.foursquare:pilgrimsdk:1.2.20'

Configure and start Pilgrim

1. Set up Pilgrim SDK with your credentials

Configure Pilgrim by adding the following keys to your AndroidManifest.xml file as shown. Be sure to replace MY_API_KEY and MY_API_SECRET with your real API credentials.


2. Configure the Pilgrim SDK

Use the following code to configure the Pilgrim SDK notification handler in your’s onCreate method. Also, you can optionally set the log level to DEBUG to receive more detailed logs while you’re developing and persist them on disk.


3. Set up the Pilgrim notification handler

In order to be notified of visits, add the Pilgrim SDK notification handlers to your Application’s onCreate method.

private final PilgrimNotificationHandler pilgrimNotificationHandler = new PilgrimNotificationHandler() {
        // Primary visit handler
        public void handlePlaceNotification(Context context, PilgrimSdkPlaceNotification extras) {
            CurrentPlace currentPlace = extras.getCurrentPlace();
            Venue venue = currentPlace.getVenue();
            // Do something with the place

        // Visit occured while in Doze mode or without network connectivity
        public void handleBackfillNotification(Context context, PilgrimSdkBackfillNotification extras) {
            super.handleBackfillNotification(context, extras);
            CurrentPlace currentPlace = extras.getCurrentPlace();
            Venue venue = currentPlace.getVenue();
            // Do something with the place

        // Optional: If nearby triggers are configured
        public void handleNearbyNotification(Context context, PilgrimSdkNearbyNotification extras) {
            List<NearbyVenue> nearbyPlaces = extras.getNearbyPlaces();
            // Do something with the places

Note the three types of notifications you may receive:

  • handlePlaceNotification: The primary visit handler that receives arrival and departure events.
  • handleBackfillNotification: This handler receives visits that occurred when their was no network connectivity or for failed visits that have been retried. For arrivals, departureTime will be null.
  • handleNearbyNotification: If any nearby triggers are configured, those places will be returned here.

4. Start Pilgrim

Once Pilgrim is configured, you can start running it by calling PilgrimSdk.start(this); in your MainActivity#onCreate.


5. Handle a visit

With Pilgrim properly configured, the notification handlers hit whenever you arrive or depart one of our 105+M places around the world. In order to test your visit callback without physically walking around, we provide two test methods:

  • sendTestNotification can test your PilgrimNotificationHandler implementation without moving around
    void sendTestNotification(
      @NonNull Context context,
      @NonNull Confidence confidence,
      @NonNull RegionType placeType,
      boolean isExit
  • sendConnectedTestNotification is an online version of the helper method to test your PilgrimNotificationHandler implementation without moving around. This method communicates with the Foursquare servers and validates that what you pass would generate a visit notification to your app if you were actually there.
    void sendConnectedTestNotification(
      String venueId,
      @NonNull Confidence confidence,
      @NonNull RegionType placeType,
      boolean isExit


Stop Monitoring Visits

If you need to stop monitoring the user’s visits, for example if they opt out or turn off your background feature, you can turn off the Pilgrim SDK by calling:


This will stop all Pilgrim activity. To resume Pilgrim, just call start() again. Repeatedly starting and stopping the SDK will temporarily reduce accuracy and drain battery.

Clearing All History

In certain instances, you may want to clear a users visit history entirely from the device, including their Home and Work locations. An example of this may be a user logging out of your app. For this you should use:


Android Permissions

These are the permissions that the SDK will add to your manifest. Please let us know if you have any questions about this list.

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

Targeting Android Marshmallow

If you are using targetSdk 23 then you will need to make sure that your app requests the ACCESS_FINE_LOCATION permission. Pilgrim will not run without the location permission. Once your user accepts the location permission, you should call PilgrimSdk.start(context).

public void requestLocationPermission(Activity activity, int requestCode) {
    ActivityCompat.requestPermissions(activity, new String[]{Manifest.permission.ACCESS_FINE_LOCATION},

Next Steps

You can download the full javadocs with the same credentials used to access the SDK here: foursquare/pilgrimsdk/1.2.20/

Be sure to check out how to provide visit confirmation feedback to help make Pilgrim more accurate:

Visit Feedback