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 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. See 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 are accessible via the lastKnownUserState property on the PilgrimManager instance. This object will have a coordinate, timestamp and a state property.

Note: It is always a good idea to check the timestamp and coordinate of this property, as it’s possible that the user may have moved since the last time the user state was updated.

If you'd like to be notified of any changes in user state, you can do so via the handleUserState callback in the respective iOS, or Android SDK.


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."

Location Context

As part of enhancing and extending User State, Pilgrim also provides an additional Location Context.This can be useful for providing a contextual notification based on a regional change in your user's location. For example, your user entering the City of Wheaton.

The Location Context includes the following:

  • State
  • City
  • Postal Code
  • Country
  • DMA



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