• 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 recieves arrival and departure events
  • handleBackfillNotification: This handler receives visits that occured in Doze mode or when their was no network connectivity
  • 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

PilgrimSdk.stop(context); should only be called if you need to stop monitoring the user’s visits, for example if they logged out of your app. Repeatedly starting and stopping the SDK will reduce overall accuracy and drain battery.

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 the Advanced Setup Guide for more information on Webhooks, Nearby Venues, and more.

Advanced Setup Guide