User States

User states allow you to more accurately interact (or not interact) with your users based on their state. For example, you might not want to send a notification to any users that are at home. But you may want to remind them of a great promotion you have while they are on their way to work or on vacation.

Currently Available

Home and Work

As users of your app begin to establish regular behavior (usually after 3-7 week days), Pilgrim SDK will attempt to determine their home and work locations. This is a foundational feature of Pilgrim that is often used in the calculation of other user states.

Note: the home and work locations that Pilgrim determines are a generalized "area", not a specific address. Instead of a specific venue, the arrival/departure events will designate the locationType as home or work instead of venue. For example, a webhook payload for a work arrival might look something like this:

  "pilgrimVisitId": "4c4b64fdd807ee002cba1560",
  "eventType": "placeArrival",
  "timestamp": 1548444925000,
  "placeEvent": {
    "venues": [],
    "confidence": "high",
    "locationType": "work",
    "arrivalTime": 1548444925000
  "lat": 41.889282,
  "lng": -87.62858,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk",
  "sdkBuild": "2.4.2",
  "segments": [
      "segmentId": 162,
      "name": "The Foursquare Coffee Drinker - U.S."

To check if a user has configured their home/work locations, you can see if this has been set by checking the hasHomeOrWork property:


Note: It's possible that you won't want to process any visits or only trust visits that have a 'High' confidence until home/work has been set. This is due to the fact that a user's home is not in our venue database, so we may be attributing 'home' visits to a venue nearby until we learn that this is in fact their home. An example of this simple check on iOS is below:

func pilgrimManager(_ pilgrimManager: PilgrimManager, didVisit visit: Visit) {
    if pilgrimManager.hasHomeOrWork() {

        // Home and work are set. Lets print them out

    } else if visit.confidence != .high {
        // Home and work aren't set and visit confidence isn't High
        // Depending on my application I might not want to trust this visit


Additional States

Non Home and Work user states will be accessible as an array of states via the userStates property on the visit object in the SDK, as well as via any visit webhook events. Each state will have a name and a properties array that could contain additional relevant data pertaining to the state.


We calculate the travel state by observing users home/work visit patterns. States trigger when users deviate from those patterns in a way that signifies travelling. This can be useful if you want to send targeted messaging that relates to a user traveling, as opposed to being in their normal home/work routine.


Pilgrim defines commuting as when a user is moving some distance between one's home and place of work on a regular basis. This can be useful, for example, if you want to send targeted messaging that relates to their morning or evening commute: "Need a pick me up? Stop by and grab a cup of joe on your way into the office."


func pilgrimManager(_ pilgrimManager: PilgrimManager, handle visit: Visit) {
    let states = visit.userStates?.map { "\($" }
    print("User States: \(states?.joined(separator: ", "))")
    public void handleVisit(Context context, PilgrimSdkVisitNotification notification) {
        Visit visit = notification.getVisit();
        for (UserState state : visit.getUserStates()) {
            Log.d("MyApp", String.format("State: %s", state.getName()));


For examples of how user states are sent via webhook events, see the webhook examples.

Next Steps

If you are interested in learning more about this feature, please reach out to your Foursquare contact.

Request Access