Foursquare LogoFoursquare Developers Logo

Description

Create a geofence around any venue on Foursquare. This can be submitted for a specific Foursquare venueId, categoryId, or chainId. Although venueIds, categoryIds, and chainIds are all optional, at least one must be used to create a venue geofence.

Request

POST https://api.foursquare.com/v2/apps/CLIENT_ID/geofences/add

Authentication

This endpoint requires user authentication by your application and must include a valid client_id in the path parameters.

In addition to the client_id, calls to this endpoint require a valid OAuth access token in the query string of each request (&oauth_token=XXXX).

For more information about this authentication method and how to obtain an access token, see the Authentication docs.

Parameters

Name Example Description
name My Deals and Offers required A custom string that you can set to help you identify the set of geofences.
radius 100 Area around a venue that will trigger a geofence event. Default and minimum radius is 50 meters with a max of 5000.
venueId 412d2800f964a520df0c1fe3 A single Foursquare venueId.
categoryId 4bf58dd8d48988d1d4941735 A single Foursquare category.
chainId 556ce426aceaff43eb04e8a0 A single Foursquare chain.
dwellTime 2 Number of minutes user needs to be inside of a geofence to trigger a dwell event. Default is 1 minute.

Response Fields

Field Description
id A unique string identifier for this geofence.
name Name of the geofence that will appear in the Pilgrim Console.
venueIds Venues that were geofenced.
chainIds Chains that were geofenced.
categoryIds Categories that were geofenced.
boundary Bounds of the geofence.

Response

{
  "meta": {
    "code": 200,
    "requestId": "5caac6f5dd57977ccc9f0876"
  },
  "notifications": [
    {
      "type": "notificationTray",
      "item": {
        "unreadCount": 0
      }
    }
  ],
  "response": {
    "geofence": {
      "type": "Venue",
      "name": "My Deals and Offers",
      "id": "5caac6f56e69af002502df37",
      "venueIds": ["3fd66200f964a520d0e41ee3"],
      "boundary": {
        "radius": 100
      },
      "dwellTime": 2
    }
  }
}