Developers

Fencer exposes a simple, RESTful, API. You'll feel right at home.

1. Getting Started

First, you'll need an account on Fencer. Just sign up. There's a free tier you can get started with immediately. It may be all you'll need.

Need more? Check out the plans and upgrade in your account settings - for more requests, private geofences, or just support.

To enable all the features of your Fencer account you'll need to respond to the activation email we'll send you. Click the link in that email and you are go.

2. Obtaining an API Key

Once you've signed up and activated your account, you'll find your Fencer API key in your account settings. You'll need this API key to use Fencer in your own web/mobile applications, or just to test against.

Picture of account/settings API key

API keys can be regenerated at any time. Please be aware that regenerating your API key will require you to update all your applications which use the Fencer API service with this key.

3. Geofence Access Keys

Every geofence you create has an Access key. You can find the key for a geofence in your account. You need an Access key to use any geofence over the API.

Picture of account Access key

Your private geofences are visible only by you. Any public geofences you create are visible to all Fencer users, who may use them in their own applications.

To find other users' public geofences you can search on the Fencer website *** here ***.

4. Making Requests

The Fencer API is secure and simple to access. Authorization is done using your API Key, which is required to be sent with each request.

API keys should be sent with your request using the HTTP Authorization header.

Position as mentioned in the API documentation is a position represented by a latitude/longitude coordinate pair.

Origin/Center as mentioned, is a coordinate point inside a goefence and is selected when the geofence is created and edited.

5. Sending Data

Depending on the type of request being made, in addition to the HTTP Authorization header you will need to provide other data, such as a geofence Access key and lat/lng coordinate pairs.

All data required for your request should also be sent using HTTP request headers.

Acceptable HTTP request headers, including the Authorization header previously mentioned, are:

  • Authorization = your Fencer API key
  • Lat-Pos = latitude of a position to query against a Geofence
  • Lng-Pos = longitude of a position to query against Geofence

HTTP request headers are case insensitive. For example, passing a request header of "authorization" rather than "Authorization" works fine.

Fencer CORS policy sets the "Access-Control-Allow-Origin" header on all responses to "*".

6.CURL Example

A request via CURL for a list of geofences you've created in Fencer would look like this:

curl -H "Authorization: {API key}" https://api.fencer.io/v1.0/geofence

7.Sample Responses

Responses are sent in JSON format. The response is wrapped with 'data' and 'error' properties. If valid data is returned, 'error' will be null. If not, 'data' will be null with the 'error' property returning information about the problem.

For example, a request using an incorrect API key, gets this response. A 401 HTTP status header is also set.

401 Unauthorized

{
  "data": null,
  "error": "401 Unauthorized"
}

A successful request for information about a stored geofence would get a JSON response similar to this.

200 OK
                  
{
  "data": {
    "id": "d5bea76b-a152-4bd7-8706-eb1cfd3c011f",
    "alias": "My First Geofence",
    "status": "Public",
    "points": [
      {
        "lat": 52.34523207882104,
        "lng": -2.6389581999999336
      },
      {
        "lat": 52.34500750000001,
        "lng": -2.6385820180107658
      },
      {
        "lat": 52.344782921178975,
        "lng": -2.6389581999999336
      },
      {
        "lat": 52.34500750000001,
        "lng": -2.6393343819891015
      }
    ],
    "center": {
      "lat": 52.34500750000001,
      "lng": -2.638958199999921
    }
  },
  "error": null
}

8.Rate Limits

Fencer plans each have a daily request limit, 2000 for the free plan, for example. Requests made above the limits will currently receive a 429 HTTP status header with no data.

429 Too Many Requests
                    
{
  "data": null,
  "error": "429 Too Many Requests"
}

If you need to make more requests in a 24 hour period you can change your plan.

9.API Reference

The base route for all calls to version 1.0 of the Fencer API is

https://api.fencer.io/v1.0

The remainder of this section provides endpoints, verbs and required HTTP request headers for the API, as well as showing sample response data.

10./geofence

GET /geofence

Obtain information about public and private geofences associated with an API key.

Request Headers

Authorization: {API Key}

Request
https://api.fencer.io/v1.0/geofence
Response

200 OK

{
  "data": [
    {
      "id": "69d2b535-72b2-4771-a3ba-776c6876888a",
      "alias": "My First Geofence",
      "status": "Public"
    },
    {
      "id": "d5bea75b-a172-4bd7-8908-eb1cfd2c011f",
      "alias": "Another Test Geofence",
      "status": "Public"
    },
    {
      "id": "d0744041-5c35-4e8e-b765-393891f99090",
      "alias": "My Private Geofence, with tags",
      "status": "Private",
      "tags": [
        "private",
        "geofence",
        "united kingdom"
      ]
    }
  ],
  "error": null
}

GET /geofence/{access key}

Obtain information about a geofence. You can query a public or private geofence of your own, or any public geofence.

Request Headers

Authorization: {API Key} Access-Key: {Geofence Access Key}

Request
https://api.fencer.io/v1.0/geofence/d5bea86b-a162-4bd7-8709-eb1cfd2c011f
Response
200 OK
                    
{
  "data": {
    "alias": "My First Geofence",
    "status": "Public",
    "tags": [
        "tag",
        "another"
    ],
    "points": [
      {
        "lat": 52.34523207882104,
        "lng": -2.6389581999999336
      },
      {
        "lat": 52.34500750000001,
        "lng": -2.6385820180107658
      },
      {
        "lat": 52.344782921178975,
        "lng": -2.6389581999999336
      },
      {
        "lat": 52.34500750000001,
        "lng": -2.6393343819891015
      }
    ],
    "center": {
      "lat": 52.34500750000001,
      "lng": -2.638958199999921
    }
  },
  "error": null
}

12./navigation/in

GET /navigation/in/{access key}

Check a position and obtain bearing and distance of shortest route into a geofence. You can query a public or private geofence of your own, or any public geofence. If you omit the Lat-Pos or Lng-Pos headers, or not of the correct format, a 416 HTTP status will be returned.

Request Headers

Authorization: {API Key} Lat-Pos: {Latitude coordinate} Lng-Pos: {Longitude coordinate}

Endpoint
https://api.fencer.io/v1.0/navigation/in/d5bea86b-a162-4bd7-8709-eb1cfd2c011f
Response
200 OK
                    
{
  "data": {
    "inside": true
  },
  "error": null
}

13./navigation/origin

GET /navigation/out/{access key}

Check a position and obtain bearing and distance (km) of shortest route to origin/center of geofence. You can query a public or private geofence of your own, or any public geofence. If you omit the Lat-Pos or Lng-Pos headers, or not of the correct format, a 416 HTTP status will be returned.

Request Headers

Authorization: {API Key} Lat-Pos: {Latitude coordinate} Lng-Pos: {Longitude coordinate}

Endpoint
https://api.fencer.io/v1.0/navigation/origin/d5bea86b-a162-4bd7-8709-eb1cfd2c011f
Response
200 OK
                    
{
  "data": {
    "distance": 0.139,
    "bearing": 270.5
  },
  "error": null
}

14./navigation/out

GET /navigation/out/{access key}

Check a position and obtain bearing and distance (km) of shortest route out of a geofence. You can query a public or private geofence of your own, or any public geofence. If you omit the Lat-Pos or Lng-Pos headers, or not of the correct format, a 416 HTTP status will be returned.

Request Headers

Authorization: {API Key} Lat-Pos: {Latitude coordinate} Lng-Pos: {Longitude coordinate}

Endpoint
https://api.fencer.io/v1.0/navigation/out/d5bea86b-a162-4bd7-8709-eb1cfd2c011f
Response
200 OK
                    
{
  "data": {
    "distance": 0.039,
    "bearing": 88.5
  },
  "error": null
}

15./position/inside

GET /position/inside/{access key}

Check a position to ascertain if inside or outside of a geofence. You can query a public or private geofence of your own, or any public geofence.Returns true if coordinates sit inside the geofence, false if not. If you omit the Lat-Pos or Lng-Pos headers, or not of the correct format a 416 HTTP status will be returned.

Request Headers

Authorization: {API Key} Lat-Pos: {Latitude coordinate} Lng-Pos: {Longitude coordinate}

Endpoint
https://api.fencer.io/v1.0/position/inside/d5bea86b-a162-4bd7-8709-eb1cfd2c011f
Response
200 OK
                    
{
  "data": {
    "inside": true
  },
  "error": null
}

16./position/status

GET /position/status/{access key}

Check a position against a geofence. Returns returns informationa about whether inside or outside a geofence and routes to enter or exit and origin. If you omit the Lat-Pos or Lng-Pos headers, or not of the correct format a 416 HTTP status will be returned.

Request Headers

Authorization: {API Key} Lat-Pos: {Latitude coordinate} Lng-Pos: {Longitude coordinate}

Endpoint
https://api.fencer.io/v1.0/position/status/d5bea86b-a162-4bd7-8709-eb1cfd2c011f
Response
200 OK
                    
{
  "data": {
    "inside": false,
    "enter": {
      "distance": 5.153,
      "bearing": 204
    },
    "origin": {
      "distance": 5.172,
      "bearing": 203
    }
  },
  "error": null
}