Foursquare LogoFoursquare Developers Logo

Description

Create a custom Polygon geofence of up to 15 different points.

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.
polygon 40.74391982977%2C-73.98824214901%3B40.74221468304%2C-73.90407791138%3B40.743451135696%2C-73.988132637%3B40.743982977%2C-73.984935301 required A string of URL encoded lat/lng points separated by semicolon, with start and end as the same points. Must provide between 4 and 15 points in a clockwise fashion to successfully create the polygon.
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.
boundary Bounds of the geofence. For polygons it will be an array of points.

Response

{
  "meta": {
    "code": 200,
    "requestId": "5cab85a79fb6b713f95cacd5"
  },
  "notifications": [
    {
      "type": "notificationTray",
      "item": {
        "unreadCount": 0
      }
    }
  ],
  "response": {
    "geofence": {
      "type": "Polygon",
      "name": "Madison Square Garden Polygon",
      "id": "5cab85a7646e38002c0d58e3",
      "boundary": {
        "points": [
          {
            "lat": 40.74351791982977,
            "lng": -73.98824214935301
          },
          {
            "lat": 40.74268879921787,
            "lng": -73.98885369300842
          },
          {
            "lat": 40.74224172008897,
            "lng": -73.9889931678772
          },
          {
            "lat": 40.74133942396724,
            "lng": -73.98925065994263
          },
          {
            "lat": 40.74082730450722,
            "lng": -73.98796319961548
          },
          {
            "lat": 40.74277821468304,
            "lng": -73.98650407791138
          },
          {
            "lat": 40.743452891135696,
            "lng": -73.98812413215637
          },
          {
            "lat": 40.74351791982977,
            "lng": -73.98824214935301
          }
        ]
      },
      "dwellTime": 2
    }
  }
}