Pilgrim Data Usage

This is the data sent to Foursquare servers on every “stop” detected by the SDK. We use these data elements both to predict the current venue a user is at.

Data collected by Pilgrim SDK

VenueSearch Signals

  • Venue type, i.e. does the client think this is a Home/Work location
  • Device lat/long
  • Wifi scan, as available
  • Beacon scan, as available
  • Barometer/magnet/phone sensors. See the list below for a complete review of sensor data rights to be requested (Foursquare does not collect all of this data today but does ask for rights to help conduct R&D that can improve our products)

IDs and Admin

  • Timestamp
  • Unique installid for this instance
  • Consumer ID (i.e. a unique ID for all Partner requests)
  • AdID
  • AdID opt-out setting

Device Info

  • Current battery level
  • Device model
  • Operating system version

NOTE: The only header we add is for our internal user agent

Sensor Data Specifics and Requested Rights

Wifi Address

iOS

Android

  • The bssid and frequency of the nearby wi-fi networks.

Motion State Data

iOS

  • N/A - Rights reserved for future collection

Android

  • If your app requests the Google Activity monitoring permission, we will get a timestamp and a motion state (i.e. “walking”).

Accelerometer

iOS

  • N/A - Rights reserved for future collection

Android

  • N/A - Rights reserved for future collection

Barometer

iOS

  • N/A - Rights reserved for future collection

Android

  • N/A - Rights reserved for future collection

Altimeter

iOS

Android

  • The altitude of the stopped location from the device provided location

Floor Level Data

iOS

Android

  • N/A - Rights reserved for future collection

Magnetometer Data

iOS

  • N/A - Rights reserved for future collection

Android

  • N/A - Rights reserved for future collection

Bluetooth Data

iOS

  • N/A - Rights reserved for future collection

Android

  • N/A - Rights reserved for future collection

Visible Beacon Data

iOS

  • N/A - Rights reserved for future collection

Android

  • N/A - Rights reserved for future collection

Data Sent to Partners via SDK

This is the data returned to the client on every stop detected by the SDK. Clients/Partners/Customers have different rights to this data, depending on the field. As a general principle, partners own data related to the stop in perpetuity, however will only have a license to fields related to the location information of a venue that terminates at the end of the agreement term.

Sample PilgrimSDK Webhook Response

{
    "pilgrimVisitId": "5b8821d9bcbf7a002dab91fc",
    "eventType": "placeArrival",
    "timestamp": 1535648217088,
    "placeEvent": {
        "venues": [
            {
                "id": "3fd66200f964a52098ed1ee3",
                "name": "The Irish Bank",
                "location": {
                    "address": "10 Mark Ln",
                    "crossStreet": "at Harlan Pl.",
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94108",
                    "country": "US",
                    "lat": 37.7903451920591,
                    "lng": -122.40459322929382
                },
                "categories": [
                    {
                        "id": "52e81612bcbc57f1066b7a06",
                        "name": "Irish Pub",
                        "pluralName": "Irish Pubs",
                        "shortName": "Irish",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/nightlife/pub_",
                            "suffix": ".png"
                        }
                    }
                ],
                "probability": 0.6088516762188961
            }
        ],
        "otherPossibleVenues": [
            {
                "id": "49e7e380f964a52027651fe3",
                "name": "Akiko’s Restaurant & Sushi Bar",
                "location": {
                    "address": "431 Bush St",
                    "crossStreet": "at Mark Ln.",
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94108",
                    "country": "US",
                    "lat": 37.790623,
                    "lng": -122.404657
                },
                "categories": [
                    {
                        "id": "4bf58dd8d48988d1d2941735",
                        "name": "Sushi Restaurant",
                        "pluralName": "Sushi Restaurants",
                        "shortName": "Sushi",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/food/sushi_",
                            "suffix": ".png"
                        }
                    },
                    {
                        "id": "4bf58dd8d48988d111941735",
                        "name": "Japanese Restaurant",
                        "pluralName": "Japanese Restaurants",
                        "shortName": "Japanese",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/food/japanese_",
                            "suffix": ".png"
                        }
                    }
                ],
                "probability": 0.042400647818909835
            },
            {
                "id": "4ed92126f5b92139871ce962",
                "name": "Foursquare SF",
                "location": {
                    "address": "425 Bush St Ste 500",
                    "crossStreet": "btwn Grant & Kearny",
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94108",
                    "country": "US",
                    "lat": 37.7905997608588,
                    "lng": -122.40459154855427
                },
                "categories": [
                    {
                        "id": "4bf58dd8d48988d125941735",
                        "name": "Tech Startup",
                        "pluralName": "Tech Startups",
                        "shortName": "Tech Startup",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/shops/technology_",
                            "suffix": ".png"
                        }
                    }
                ],
                "venueChains": [
                    {
                        "id": "556e5779bd6a82902e28bcea",
                        "name": "Foursquare"
                    }
                ],
                "probability": 0.01599619603673202
            },
            ...
        ],
        "confidence": "high",
        "locationType": "venue"
    },
    "lat": 37.790459,
    "lng": -122.404695,
    "user": {
        "userId": "jIkQZBHGrDJt6gMeXlcrWBRO8fStdETO"
    },
    "sdkType": "iossdk"
}

📘

Object Table Key

Green - Partner owns the field in perpetuity
Yellow - Partner owns a subset of fields on the child object
Red - Partner is licensed to use field data for the term of the agreement

Visit Object

Key Type Description Example
venues Array<Venue> The place the user is at. Currently a max of 1 item is sent. Below
confidence String The venue confidence, which is one of none, low, med, high High
lat Double The latitude of the user when they arrived at the place 40.777502
long Double The longitude of the user when they arrived at the place -73.969508
pilgrimVisitId String The unique ID of the visit. Required for confirming visits back to Foursquare 593eede7d48ec143c034a349
timestamp long Time of the event in milliseconds since epoch 1497296359056
visitType String The type of notification that is coming through: arrival, departure, historical. arrival
locationType String The type of place the event corresponds to. One of venue, home, work, none, unknown venue
sdkType String The SDK that generated the notification iosSdk or androidSdk androidsdk
arrivalTime long Time of the arrival in milliseconds since epoch 1535648217088
departureTime (Optional) long Time of the departure in milliseconds since epoch. Available on exit and historicalvisit types. 1535648217088
otherPossibleVenues (Optional) List<Venue> A list of other venues that the user might be at. Only returned if you have the checkbox selected in the Pilgrim console Format same as above
nearbyVenues (Optional) List The list of places nearby that matched your selected nearby triggers as configured on the Pilgrim console or locally in the SDK on a per user basis. Format same as above

Venue Object

Key Type Description Example
id String The venue id 4ed92126f5b92139871ce962
name String The venue name Cafe Pushkin
location Location The location of the venue See below in red.
categories Array<Category> The categories of the venue Coffee Shop
hierarchy (optional) Array The parent venues of this place, containing a subset of venue information (id, name, categories) Same format as Venues above
chains (optional) Array<Chain> The chains that the venue belongs to Starbucks

Location Object

Key Type Description Example
crossStreet String Venue cross street. btwn Grant & Kearny
address String The address of the venue 425 Bush St Ste 500
city String The city of the venue San Francisco
state String The state of the venue CA
postalCode String The postal code of the venue 94108
country String The country of the venue US
lat Double The latitude of the venue center 37.7905997608588
lng Double The longitude of the venue center -122.40459154855427

Category Object

Key Type Description Example
id String The category id 4ed92126f5b92139871ce962
name String The category name Coffee Shop
shortName String The shortened version of the category name i.e. American vs American Restaurant American
pluralName String The plural name of the categories

Chain Object

Key Type Description Example
id String The chain id 556e5779bd6a82902e28bcea

Sign In