API

Contents

Introduction

You can access all of your Radar data, including users, events, geofences, and places, via the API. You might use the API to list users in a specific geofence, or to create geofences programmatically.

The API is RESTful, with predictable, resource-oriented URLs. All responses, including errors, return JSON. POST and PUT request body parameters may be sent as application/json or application/x-www-form-urlencoded.

Authentication

All requests must be authenticated. Authenticate using your secret API keys, found on the Settings page. Use your Test Secret key for testing and non-production environments. Use your Live Secret key for production environments. Include your API key in the Authorization header.

Sample request
curl https://api.radar.io/v1/users \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"

Errors

The API uses standard HTTP response codes.

Response codes
  • 200: Success
  • 400: Bad request (missing or invalid params)
  • 401: Unauthorized (invalid API key)
  • 402: Payment required (organization disabled or usage exceeded)
  • 403: Forbidden (insufficient permissions)
  • 404: Not found
  • 409: Conflict
  • 429: Too many requests (rate limit exceeded, no state change, or selective throttling)
  • 451: Unavailable for legal reasons (country blacklisted)
  • 500: Internal server error
  • 503: Service temporarily unavailable
Sample error response
{
  "meta": {
    "code": 400,
    "param": "email",
    "message": "Email is invalid."
  }
}

Resources

Users

A user represents a user tracked in your project. Users can be uniquely referenced by Radar _id or by userId.

Object fields
  • _id (string): A unique ID for the user, provided by Radar. An alphanumeric string.
  • live (boolean): true if the user was created with your live API key, false if the user was created with your test API key.
  • userId (string): A stable unique ID for the user.
  • deviceId (string): The user's device ID.
  • description (string): An optional description for the user.
  • metadata (dictionary): An optional set of custom key-value pairs for the user.
  • location (GeoJSON): The user's last known location, a Point in GeoJSON format.
  • locationAccuracy (number): The accuracy of the user's last known location in meters.
  • foreground (boolean): true if the user's last known location was updated in the foreground, false if the user's last known location was updated in the background.
  • stopped (boolean): true if the user's last known location was updated while stopped, false if the user's last known location was updated while moving.
  • deviceType (string): The user's device type, one of iOS or Android.
  • updatedAt (datetime): The datetime when the user's location was last updated.
  • geofences (array): An array of the user's last known geofences.
  • place (dictionary): When Places is enabled, the user's last known place.
  • insights (dictionary): When Insights is enabled, the user's learned approximate home and office locations, and home, office, and traveling state.
Sample object
{
  "_id": "56db1f4613012711002229f4",
  "live": true,
  "userId": "1",
  "deviceId": "A305F2DB-56DC-404F-B6C1-BC52F0B680D8",
  "description": "Jerry Seinfeld",
  "metadata": {
    ...
  },
  "location": {
    "type": "Point",
    "coordinates": [-73.975363, 40.783826]
  },
  "locationAccuracy": 5,
  "foreground": true,
  "stopped": true,
  "deviceType": "iOS",
  "updatedAt": "2016-06-10T13:44:10.535Z",
  "geofences": [
    {
      "_id": "56db1f4613012711002229f5",
      "tag": "neighborhood",
      "externalId": "1",
      "description": "Upper West Side",
      ...
    },
    ...
  ],
  "place": {
    "_id": "56db1f4613012711002229f7",
    "facebookId": "37965424481",
    "name": "Starbucks",
    "categories": ["food-beverage", "cafe", "coffee-shop"],
    "chain": {
      "name": "Starbucks",
      "slug": "starbucks"
    }
  },
  "insights": {
    "locations": [
      {
        "type": "home",
        "location": {
          "type": "Point",
          "coordinates": [-73.974912, 40.786978]
        },
        "confidence": 3,
        "updatedAt": "2017-04-04T01:23:47.495Z"
      },
      {
        "type": "office",
        "location": {
          "type": "Point",
          "coordinates": [-73.988859, 40.769949],
        },
        "confidence": 1,
        "updatedAt": "2017-04-04T01:23:47.495Z"
      }
    ],
    "state": {
      "home": false,
      "office": false,
      "traveling": false
    }
  }
}

List users

List users. Users are sorted descending by updatedAt.

Definition

GET https://api.radar.io/v1/users

Query parameters
  • limit (number, optional): Retrieves a specific number of users. A number between 1 and 1000. Defaults to 100.
  • updatedBefore (datetime, optional): A cursor for use in pagination. Retrieves users updated before the specified datetime. A date or valid ISO date string.
  • updatedAfter (datetime, optional): A cursor for use in pagination. Retrieves users updated after the specified datetime. A date or valid ISO date string.
Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/users \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200,
    "hasMore": true
  },
  "users": [
    {
      "_id": "56db1f4613012711002229f4",
      "live": true,
      "userId": "1",
      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",
      "description": "Jerry Seinfeld",
      ...
    },
    ...
  ]
}

List users in a geofence

List users in a geofence. The geofence can be uniquely referenced by Radar _id or by tag and externalId. Users are sorted descending by updatedAt.

Definition

GET https://api.radar.io/v1/geofences/:id/users
GET https://api.radar.io/v1/geofences/:tag/:externalId/users

Query parameters
  • limit (number, optional): Retrieves a specific number of users. A number between 1 and 1000. Defaults to 100.
  • updatedBefore (datetime, optional): A cursor for use in pagination. Retrieves users updated before the specified datetime. A date or valid ISO date string.
  • updatedAfter (datetime, optional): A cursor for use in pagination. Retrieves users updated after the specified datetime. A date or valid ISO date string.
Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/geofences/56db1f4613012711002229f5/users \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200,
    "hasMore": true
  },
  "users": [
    {
      "_id": "56db1f4613012711002229f4",
      "live": true,
      "userId": "1",
      "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",
      "description": "Jerry Seinfeld",
      ...
    },
    ...
  ]
}

Get a user

Get a user. The user can be uniquely referenced by Radar _id, userId, or deviceId.

Definition

GET https://api.radar.io/v1/users/:id

Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/users/56db1f4613012711002229f4 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200
  },
  "user": {
    "_id": "56db1f4613012711002229f4",
    "live": true,
    "userId": "1",
    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",
    "description": "Jerry Seinfeld",
    ...
  }
}

Upsert a user

Upsert a user. Returns the user and the events generated, if any. The user can be uniquely referenced by _id, userId, or deviceId. If a matching user already exists, it will be updated. If not, it will be created.

Definition

PUT https://api.radar.io/v1/users/:id

Body parameters
  • latitude (number, required): The user's current latitude. A number between -90 and 90.
  • longitude (number, required): The user's current longitude. A number between -180 and 180.
  • accuracy (number, required): The accuracy of the user's current latitude and longitude, in meters. A number greater than 0.
  • foreground (boolean): true if the client is in the foreground, false if the client is in the background.
  • stopped (boolean): true if the user is stopped, false if the user is moving.
  • userId (string, optional): A stable unique ID for the user. If userId and deviceId are not specified and no matching users exist, defaults to :id.
  • deviceId (string, optional): The device ID of the user.
  • description (string, optional): An optional description for the user, displayed in the dashboard.
  • metadata (dictionary, optional): An optional set of custom key-value pairs for the user. Must have 16 or fewer keys and values of type string, boolean, or number.
  • updatedAt (datetime, optional): The client timestamp or historical timestamp when the user's location was updated. Historical data must be upserted in chronological order. Optional, defaults to the current server timestamp if not provided or not in chronological order. A valid date or ISO date string.
  • placesProvider (string, optional): When Places is enabled, the place data provider to use. A string, one of facebook or none.
Rate limit

60 requests per hour per user

Sample request
curl https://api.radar.io/v1/users/1 \
  -H "Authorization: prj_live_pk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X PUT \
  -d "latitude=40.783826" \
  -d "longitude=-73.975363" \
  -d "accuracy=65"
  -d "deviceId=C305F2DB-56DC-404F-B6C1-BC52F0B680D8"
  -d "description=Jerry Seinfeld"
Sample response
{
  "meta": {
    "code": 200
  },
  "user": {
    "_id": "56db1f4613012711002229f4",
    "live": true,
    "userId": "1",
    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",
    "description": "Jerry Seinfeld",
    ...
  },
  "events": [
    ...
  ]
}
Delete a user

Delete a user. The user can be uniquely referenced by Radar _id, userId, or deviceId.

Definition

DELETE https://api.radar.io/v1/users/:id

Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/users/56db1f4613012711002229f4 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X DELETE
Sample response
{
  "meta": {
    "code": 200
  }
}

Geofences

A geofence represents a custom region or place monitored in your project. Geofences can be uniquely referenced by Radar _id or by tag and externalId.

Object fields
  • _id (string): The unique ID for the geofence, provided by Radar. An alphanumeric string.
  • createdAt (datetime): The datetime when the geofence was created.
  • live (boolean): true if the geofence was created with your live API key, false if the user was created with your test API key.
  • tag (string): An optional group for the geofence.
  • externalId (string): An optional external ID for the geofence that maps to your internal database.
  • description (string): A description for the geofence.
  • type (string): The type of geofence geometry, either polygon or circle.
  • geometry (GeoJSON): The geometry of the geofence. Coordinates for type polygon. A calculated polygon approximation for type circle. A Polygon in GeoJSON format.
  • geometryCenter (GeoJSON): The center of the circle for type circle. The calculated centroid of the polygon for type polygon. A Point in GeoJSON format.
  • geometryRadius (number): The radius of the circle in meters for type circle.
  • metadata (dictionary): An optional set of custom key-value pairs for the geofence.
  • userId (string): An optional user restriction for the geofence. If set, the geofence will only generate events for the specified user. If not set, the geofence will generate events for all users.
  • enabled (boolean): If true, the geofence will generate events. If false, the geofence will not generate events. Defaults to true.
Sample object
{
  "_id": "56db1f4613012711002229f5",
  "createdAt": "2016-06-10T13:44:10.535Z",
  "live": true,
  "tag": "venue",
  "externalId": "2",
  "description": "Monk's Café",
  "type": "circle",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[...]]
  },
  "geometryCenter": {
    "type": "Point",
    "coordinates": [-73.975363, 40.783826]
  },
  "geometryRadius": 50,
  "metadata": {
    ...
  },
  "enabled": true
}

List geofences

Definition

List geofences. Geofences are sorted descending by createdAt.

GET https://api.radar.io/v1/geofences

Query parameters
  • limit (number, optional): Retrieves a specific number of geofences. A number between 1 and 1000. Defaults to 100.
  • createdBefore (datetime, optional): A cursor for use in pagination. Retrieves geofences created before the specified datetime. A date or valid ISO date string.
  • createdAfter (datetime, optional): A cursor for use in pagination. Retrieves geofences created after the specified datetime. A date or valid ISO date string.
  • tag (string, optional): Retrieves geofences with the specified tag.
Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/geofences \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200,
    "hasMore": true
  },
  "geofences": [
    {
      "_id": "56db1f4613012711002229f5",
      "createdAt": "2016-06-10T13:44:10.535Z",
      "live": true,
      "tag": "venue",
      "externalId": "2",
      "description": "Monk's Café",
      "type": "circle",
      ...
    },
    ...
  ]
}

Get a geofence

Get a geofence. The geofence can be uniquely referenced by Radar _id or by tag and externalId.

Definition

GET https://api.radar.io/v1/geofences/:id
GET https://api.radar.io/v1/geofences/:tag/:externalId

Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/geofences/56db1f4613012711002229f5 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200
  },
  "geofence": {
    "_id": "56db1f4613012711002229f5",
    "createdAt": "2016-06-10T13:44:10.535Z",
    "live": true,
    "tag": "venue",
    "externalId": "2",
    "description": "Monk's Café",
    "type": "circle",
    ...
  }
}

Create a geofence

Create a geofence. If a geofence with the specified tag and externalId already exists, the request will fail.

Definition

POST https://api.radar.io/v1/geofences

Body parameters
  • description (string, required): A description for the geofence.
  • type (string, required): The type of geofence geometry. A string, one of polygon or circle.
  • coordinates (array, required): An array or JSON string representing a center in the format [longitude,latitude] for type circle. A two-dimensional array or JSON string representing a closed ring of between 4 and 256 coordinates in the format [[longitude0, latitude0],[longitude1,latitude1],[longitude2,latitude2],...,[longitude0,latitude0]] for type polygon. Note that longitude comes before latitude, a GeoJSON convention.
  • radius (number, required for type circle): The radius of the circle in meters for type circle, a number between 50 and 10000. Ignored for type polygon.
  • tag (string, optional): An optional group for the geofence.
  • externalId (string, optional): An optional external ID for the geofence.
  • metadata (dictionary, optional): An optional set of custom key-value pairs for the geofence. A dictionary or JSON string with up to 16 keys and values of type string, boolean, or number.
  • userId (string, optional): An optional user restriction for the geofence. If set, the geofence will only generate events for the specified user. If not set, the geofence will generate events for all users.
  • enabled (boolean, optional): If true, the geofence will generate events. If false, the geofence will not generate events. Defaults to true.
Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/geofences \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X POST \
  -d "description=Monk's Café" \
  -d "tag=venue" \
  -d "externalId=2" \
  -d "type=circle" \
  -d "coordinates=[-73.975363,40.783826]" \
  -d "radius=50"
Sample response
{
  "meta": {
    "code": 200
  },
  "geofence": {
    "_id": "56db1f4613012711002229f5",
    "createdAt": "2016-06-10T13:44:10.535Z",
    "live": true,
    "tag": "venue",
    "externalId": "2",
    "description": "Monk's Café",
    "type": "circle",
    ...
  }
}

Upsert a geofence

Upsert a geofence. The geofence can be uniquely referenced by tag and externalId. If a geofence with the specified tag and externalId already exists, it will be updated. If not, it will be created.

Definition

PUT https://api.radar.io/v1/geofences/:tag/:externalId

Body parameters
  • description (string, required): A description for the geofence.
  • type (string, required): The type of geofence geometry. A string, one of polygon or circle.
  • coordinates (array, required): An array or JSON string representing a center in the format [longitude,latitude] for type circle. A two-dimensional array or JSON string representing a closed ring of between 4 and 256 coordinates in the format [[longitude0, latitude0],[longitude1,latitude1],[longitude2,latitude2],...,[longitude0,latitude0]] for type polygon. Note that longitude comes before latitude, a GeoJSON convention.
  • radius (number, required for type circle): The radius of the circle in meters for type circle. Ignored for type polygon. A number between 50 and 10000.
  • metadata (dictionary, optional): An optional set of custom key-value pairs for the geofence. A dictionary or JSON string with up to 16 keys and values of type string, boolean, or number.
  • userId (string, optional): An optional user restriction for the geofence. If set, the geofence will only generate events for the specified user. If not set, the geofence will generate events for all users.
  • enabled (boolean, optional): If true, the geofence will generate events. If false, the geofence will not generate events. Defaults to true.
Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/geofences/venue/2 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X PUT \
  -d "description=Monk's Café" \
  -d "type=circle" \
  -d "coordinates=[-73.975363,40.783826]" \
  -d "radius=50"
Sample response
{
  "meta": {
    "code": 200
  },
  "geofence": {
    "_id": "56db1f4613012711002229f5",
    "createdAt": "2016-06-10T13:44:10.535Z",
    "live": true,
    "tag": "venue",
    "externalId": "2",
    "description": "Monk's Café",
    "type": "circle",
    ...
  }
}

Delete a geofence

Delete a geofence. The geofence can be uniquely referenced by Radar _id or by tag and externalId.

Definition

DELETE https://api.radar.io/v1/geofences/:id
DELETE https://api.radar.io/v1/geofences/:tag/:externalId

Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/geofences/56db1f4613012711002229f5 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X DELETE
Sample response
{
  "meta": {
    "code": 200
  }
}

Events

An event represents a change in user state. Events can be uniquely referenced by Radar _id.

Object fields
  • _id (string): The unique ID for the event, provided by Radar. An alphanumeric string.
  • createdAt (datetime): The datetime when the event was created.
  • live (boolean): true if the event was generated for a user and geofence created with your live API key, false if the event was generated for a user and geofence created with your test API key.
  • type (string): The type of event. By default, events are generated when a user enters a geofence (type user.entered_geofence) or exits a geofence (type user.exited_geofence). When Insights is enabled, events will also be generated when a user enters their home (type user.entered_home), exits their home (type user.exited_home), enters their office (type user.entered_office), exits their office (type user.exited_office), starts traveling (type user.started_traveling), or stops traveling (user.stopped_traveling).
  • user (dictionary): The user for which the event was generated.
  • geofence (dictionary): For user.entered_geofence and user.exited_geofence events, the geofence for which the event was generated, including description, tag, and externalId.
  • place (dictionary): For user.entered_place and user.exited_place events, the place for which the event was generated, including name, categories, chain, and facebookId.
  • alternatePlaces (array): For user.entered_place events, alternate place candidates.
  • verifiedPlace (dictionary): For verified user.entered_place events, the verified place.
  • location (GeoJSON): The location of the user at the time of the event. A Point in GeoJSON format.
  • locationAccuracy (number): The accuracy of the user's location at the time of the event in meters.
  • confidence (number): The confidence level of the event, one of 3 (high), 2 (medium), or 1 (low).
  • duration (number): The duration between entry and exit events, in minutes, for user.exited_geofence and user.exited_place events.
  • verification (number): The verification for the event, one of 1 (accepted), -1 (rejected), or 0 (unverified).
Sample object
{
  "_id": "56db1f4613012711002229f6",
  "createdAt": "2016-06-10T13:44:10.535Z",
  "live": true,
  "type": "user.exited_geofence",
  "location": {
    "type": "Point",
    "coordinates": [-73.977797, 40.783826]
  },
  "locationAccuracy": 5,
  "confidence": 3,
  "duration": 48.389201,
  "user": {
    "_id": "56db1f4613012711002229f4",
    "userId": "1",
    "deviceId": "C305F2DB-56DC-404F-B6C1-BC52F0B680D8",
    "description": "Jerry Seinfeld",
    ...
  },
  "geofence": {
    "_id": "56db1f4613012711002229f5",
    "tag": "venue",
    "externalId": "2",
    "description": "Monk's Café",
    ...
  }
}

List events

List events. Events are sorted descending by createdAt.

Definitions

GET https://api.radar.io/v1/events

Query parameters
  • limit (number, optional): Retrieves a specific number of events. A number between 1 and 1000. Defaults to 100.
  • createdBefore (datetime, optional): A cursor for use in pagination. Retrieves events created before the specified datetime. A date or valid ISO date string.
  • createdAfter (datetime, optional): A cursor for use in pagination. Retrieves events created after the specified datetime. A date or valid ISO date string.
Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/events \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200,
    "hasMore": true
  },
  "events": [
    {
      "_id": "56db1f4613012711002229f6",
      "createdAt": "2016-06-10T13:44:10.535Z",
      "live": true,
      "type": "user.exited_geofence",
      ...
    },
    ...
  ]
}

Get an event

Get an event. The event can be uniquely referenced by Radar _id.

Definition

GET https://api.radar.io/v1/events/:id

Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/events/56db1f4613012711002229f6 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469"
Sample response
{
  "meta": {
    "code": 200
  },
  "event": {
    "_id": "56db1f4613012711002229f6",
    "createdAt": "2016-06-10T13:44:10.535Z",
    "live": true,
    "type": "user.exited_geofence",
    ...
  }
}

Verify an event

Verify an event. Events can be accepted or rejected after user check-ins or other forms of verification. Event verifications will be used to improve the confidence level of future events.

Definitions

PUT https://api.radar.io/v1/events/:id/verification

Body parameters
  • verification (number, required): 1 to accept the event, -1 to reject the event, 0 to unverify the event.
  • verifiedPlaceId (string, optional): For user.entered_place events, the ID of the verified place.
Rate limit

1 request per second per event

Sample request
curl https://api.radar.io/v1/events/56db1f4613012711002229f6/verification \
  -H "Authorization: prj_live_pk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X PUT
  -d "verification=1"
  -d "verifiedPlaceId=56db1f4613012711002229f7"
Sample response
{
  "meta": {
    "code": 200
  }
}

Delete an event

Delete an event. The event can be uniquely referenced by Radar _id.

Definitions

DELETE https://api.radar.io/v1/events/:id

Rate limit

10 requests per second

Sample request
curl https://api.radar.io/v1/events/56db1f4613012711002229f6 \
  -H "Authorization: prj_live_sk_108c97506e7549bdbffd68cc4512a7df1fc1c469" \
  -X DELETE
Sample response
{
  "meta": {
    "code": 200
  }
}

Support

Have questions after reading the documentation? We're here to help! Click the button on the bottom right of any page to chat with us, or email us at [email protected].