NAV
cURL node.js

Introduction

Welcome to Coposition! You can use our API to securely store and retrieve geolocation info associated with devices and users. You can also use the api to view and manage permissions.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

// For brevity, the node code samples use
// the Request module (https://www.npmjs.com/package/request)
// But feel free to use whatever method you prefer
// to make http requests

var request = require("request");

var options = {
  method: 'HTTP_VERB_HERE',
  url: 'API_ENDPOINT_HERE',
  headers:
   { 'cache-control': 'no-cache',
     'x-api-key': 'YOUR_API_KEY_HERE' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});


# With cURL, you can just pass the correct header with each request
curl "API_ENDPOINT_HERE"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

Make sure to replace YOUR_API_KEY_HERE with your API key.

Coposition uses custom HTTP headers to control access to different parts of the API. All API requests are expected to have an API key header:

X-Api-Key: YOUR_API_KEY_HERE

You can get a new Coposition API key from your developer console.

Other custom headers used by the API are shown below. We’ll revisit them when they’re required.

Header Value
X-UUID Unique identifier associated with a specific device in our database.

Oauth

You will need your Oauth secret key, UID and redirect uri from your developer console

Link user to 
'https://coposition.com/oauth/authorize?response_type=code&client_id=UID&redirect_uri=REDIRECT_URI'

Once user has completed authorisation they will be redirected to 
'YOUR_REDIRECT_URI?code=ACCESS_GRANT'

curl -X POST "https://coposition.com/oauth/token"
     -H "Content-Type: application/json"
     -d '{
      "client_id" : OAUTH_UID,
      "client_secret" : OAUTH_SECRET,
      "code" : ACCESS_GRANT
      "grant_type" : "authorization_code",
      "redirect_uri" : "YOUR_REDIRECT_URI?code=ACCESS_GRANT"
     }'

Link user to 
'https://coposition.com/oauth/authorize?response_type=code&client_id=UID&redirect_uri=REDIRECT_URI'

Once user has completed authorisation they will be redirected to 
'YOUR_REDIRECT_URI?code=ACCESS_GRANT'

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://coposition.com/oauth/token',
  headers: { 'Content-Type': 'application/json' },
  body: { 
    client_id: OAUTH_UID,
    client_secret: OAUTH_SECRET,
    code : ACCESS_GRANT
    grant_type: 'authorization_code',
    redirect_uri: 'YOUR_REDIRECT_URI?code=ACCESS_GRANT'
  }
}

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this.

{
  "access_token": ACCESS_TOKEN,
  "user": {
    "id": 1,
    "email": "tom@email.com",
    "username": "tom",
    "slug": "tom"
  }
}

In order to access a user’s data, the user will need to have authorized your application to access their data via oAuth.

You can add oAuth to your app using our ruby gem. Instructions for authorizing a user via javascript or curl are included to the right.

You will need to provide both your API key and an access token associated with the user who’s data you are trying to access when using the API. The access token can be included by appending the following query parameter:

?access_token=ACCESS_TOKEN

UUID

All hardware is identified by a universally unique identifier (UUID). This is because not all devices share the same identifying marks e.g. serial numbers, IMEI so we create an artificial one to standardize on.

Create a new UUID

UUID’s can be pre-generated to allow you to uniquely identify a device after manufacture. When you request a UUID, a device config will also be created allowing you the developer to control any additional device settings you may want to configure.

At the moment: 1 request = 1 UUID.

curl -X GET "https://api.coposition.com/uuid"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/uuid',
  headers:
   { 'cache-control': 'no-cache',
     'x-api-key': 'YOUR_API_KEY_HERE' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "uuid": "7d274e7c-76ab-45e7-8d96-ef063ad725f8"
}

HTTP Request

GET https://api.coposition.com/uuid

Users

Getting app users

Allows you to view a list of users who have approved your app/developer and obtain user ID’s which can be used in creating/updating an approval or updating permissions for a device.

curl -X GET "https://api.coposition.com/users"
  -H "X-Api-Key: YOUR_API_KEY_HERE"
  -H "Content-Type: application/json"
  -H "Cache-Control: no-cache"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/users',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-Api-Key': 'YOUR_API_KEY_HERE'},
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

[
  {
    "id": 2,
    "email": "tom@email.com",
    "username": "tom",
    "slug": "tom"
  },
  {
    "id": 3,
    "email": "sam@email.com",
    "username": "sam",
    "slug": "sam"
  }
]

HTTP Request

GET https://api.coposition.com/users

Headers

X-Api-Key Content-Type Cache-Control

Showing user info

Allows you to view user info such as username and email.

curl -X GET "https://api.coposition.com/users/USER_ID"
  -H "X-Api-Key: YOUR_API_KEY_HERE"
  -H "Content-Type: application/json"
  -H "Cache-Control: no-cache"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/users/USER_ID',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-Api-Key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "id": 1,
  "email": "delia.kirlin@ortiz.biz",
  "username": "coporulez",
  "slug": "coporulez"
}

HTTP Request

GET https://api.coposition.com/users/USER_ID

Headers

X-Api-Key Content-Type Cache-Control

Approvals

Asking for approval

Use this endpoint to create a pending approval between an App/User and the current User.

curl -X POST "https://api.coposition.com/users/USER_ID/approvals/"
  -H "X-Api-Key: YOUR_API_KEY_HERE"
  -H "Content-Type: application/json"
  -H "Cache-Control: no-cache"
  -d '{
    "approval" : {
      "approvable": DEVELOPER_ID,
      "approvable_type": "Developer"
      }
    }'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.coposition.com/users/USER_ID/approvals/',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-Api-Key': 'YOUR_API_KEY_HERE'},
  body: { approval: { approvable: DEVELOPER_ID, approvable_type: 'Developer' } },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "id": 103,
  "approvable_id": 2,
  "user_id": 2,
  "approval_date": "2016-05-17T09:34:24.118Z",
  "created_at": "2016-04-19T09:44:55.319Z",
  "updated_at": "2016-05-17T09:34:24.120Z",
  "status": "accepted",
  "approvable_type": "Developer"
}

HTTP Request

POST https://api.coposition.com/users/USER_ID/approvals/

Headers

X-Api-Key Content-Type Cache-Control

Body

Attribute Value
approval approvable, approvable_type
approvable integer (id of user/developer)
approvable_type ‘User’ or 'Developer’

Check-ins

A check-in is our basic unit of geolocation information. It has a latitude, longitude and the UUID of the device it belongs to. It can also contain an address and privacy information.

Check-in privacy

Coposition allows you to pass a less specific location on to your friends and apps. We call this “fogging”. A check-in’s fogged location is either the centre of the nearest named urban area with a population of more than 1000 people (usually a city district, borough, town, village or suburb). If there isn’t one within 200 miles, it is assigned a random location ±0.5 decimal degrees of latitude/longitude. This information is saved to the check-in so you can consistently report the same location.

You may also delay sharing a check-in to a less sensitive time by changing the delay property on the parent device.

Create a new check-in

A latitude and longitude are required. You can also provide a created at date and time in the format “yyyy-mm-dd [hh:mm:ss]”. If the API key belongs to the developer who originally created the device, the device config will also be returned.

curl -X POST "https://api.coposition.com/checkins"
     -H "X-Api-Key: YOUR_API_KEY_HERE"
     -H "Content-Type: application/json"
     -H "X-UUID: DEVICE-UUID-HERE"
     -H "Cache-Control: no-cache"
     -d '{
      "lat" : "51.588330",
      "lng" : "-0.513069",
      "created_at" : "2016-10-31 [10:30:12]"
     }'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.coposition.com/checkins',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-UUID': 'DEVICE-UUID-HERE'
     'x-api-key': 'YOUR_API_KEY_HERE' },
  body: { lat: '51.588330', lng: '-0.513069', created_at : '2017-02-01 [11:01:38]' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this. Config will only be returned if checkin is created with the api key of the developer who created the device.

{
  "data": [
    {
      "lat": 51.58833,
      "lng": -0.513069,
      "device_id": 309,
      "fogged": false,
      "id": 287282,
      "uuid": "cb732efc-b34f-427a-b80c-c39d4ff4a8f7",
      "fogged_lat": 51.60333,
      "fogged_lng": -0.48546,
      "fogged_city": "Harefield",
      "country_code": "GB",
      "fogged_country_code": "GB",
      "created_at": "2017-02-01T11:01:38.000Z",
      "updated_at": "2017-02-01T11:04:02.661Z",
      "address": "Not yet geocoded",
      "city": null,
      "postal_code": null,
      "output_lat": 51.58833,
      "output_lng": -0.513069,
      "output_address": "Not yet geocoded",
      "output_city": null,
      "output_postal_code": null,
      "output_country_code": "GB",
      "edited": false
    }
  ],
  "config": {
    "id": 23,
    "developer_id": 2,
    "device_id": 309,
    "custom": null,
    "created_at": "2016-06-08T07:59:17.005Z",
    "updated_at": "2016-06-13T09:27:52.338Z"
  }
}

HTTP Request

POST https://api.coposition.com/checkins

Headers

X-Api-key X-UUID Content-Type

Body

Attribute Value
lat -180/+180
lng -180/+180
created_at (optional) A valid Ruby datetime value e.g. “yyyy-mm-dd [hh:mm:ss]”

Create a batch of new check-ins

Again, the latitude and longitude of each check-in is required and you can also supply a created at date and time.

curl -X POST "https://api.coposition.com/checkins/batch_create"
     -H "X-Api-Key: YOUR_API_KEY_HERE"
     -H "Content-Type: application/json"
     -H "X-UUID: DEVICE-UUID-HERE"
     -H "Cache-Control: no-cache"
     -d '[
       {
         "lat" : "51.588330",
         "lng" : "-0.513069",
         "created_at" : "2016-10-31 [10:30:12]"
       },
       {
         "lat" : "52.345334",
         "lng" : "-0.563423",
         "created_at" : "2016-10-31 [11:05:54]"
       }]'

var request = require("request");

var options = { method: 'POST',
  url: 'https://api.coposition.com/checkins/batch_create',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-UUID': 'DEVICE-UUID-HERE'
     'x-api-key': 'YOUR_API_KEY_HERE' },
  body: [
    { lat: '51.588330', lng: '-0.513069', created_at : '2017-02-01 [11:01:38]' },
    { lat: '52.345334', lng: '-0.563423', created_at: '2016-10-31 [11:05:54]' }
  ],
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this.

{
  "message": "Checkins created"
}

HTTP Request

POST https://api.coposition.com/checkins/batch_create

Headers

X-Api-key X-UUID Content-Type

Body

Attribute Value
lat -180/+180
lng -180/+180
created_at (optional) A valid Ruby datetime value e.g. “yyyy-mm-dd [hh:mm:ss]”

Get a list of user checkins

Get a list of a user’s checkins, you can choose to geocode the checkins to get a full address if available, you can specific a device from which you want checkins from and how many checkins you want to receive.

curl -X GET "https://api.coposition.com/users/USER_ID/checkins?access_token=ACCESS_TOKEN"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.coposition.com/users/USER_ID/checkins?access_token=ACCESS_TOKEN',
  headers:
   { 'x-api-key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

[
  {
    "id": 18546,
    "lat": 51.513977,
    "lng": -0.234924,
    "created_at": "2016-05-12T17:10:55.776Z",
    "updated_at": "2016-05-13T09:23:33.125Z",
    "device_id": 7,
    "address": "Community Centre, India Way, White City, London W12 7AQ, UK",
    "city": "London",
    "postal_code": "W12 7AQ",
    "country_code": "GB"
  },
  {
    "id": 18544,
    "lat": 51.587736,
    "lng": -0.302124,
    "created_at": "2016-05-11T14:36:15.604Z",
    "updated_at": "2016-05-12T14:23:46.519Z",
    "device_id": 7,
    "address": "3 Westfield Ln, Harrow, Greater London HA3 9EA, UK",
    "city": "Harrow",
    "postal_code": "HA3 9EA",
    "country_code": "GB"
  },
]

HTTP Request

For checkins for a user.

GET https://api.coposition.com/users/USER_ID/checkins?access_token=ACCESS_TOKEN

Just the last checkin

GET https://api.coposition.com/users/USER_ID/checkins/last?access_token=ACCESS_TOKEN

Optional filters

You can specify additional filtering in the query string

Option Query string
Filter by device ?device_id=DEVICE_ID
Show street address (only when filtering by device) ?type=address
Page and results per page (default 30 max 1000) ?per_page=100&page=2
Filter by date ?date=DD MM YYYY
Find checkins near to coordinates ?near=[LATITUDE LONGITUDE]
Returns only one checkin for each area you have visited ?unique_places=true
Find check-ins created in the last n hours/days/weeks ?time_unit=UNIT&time_amount=AMOUNT e.g. ?time_unit=day&time_amount=10

Headers

X-Api-Key Content-Type Cache-Control

Devices

Get a list of user’s devices

Returns a list of devices belonging to the specified user. The user must have approved your App.

curl -X GET "https://api.coposition.com/users/USER_ID/devices?access_token=ACCESS_TOKEN"
  -H "X-Api-Key: YOUR_API_KEY_HERE"
  -H "Content-Type: application/json"
  -H "Cache-Control: no-cache"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/users/USER_ID/devices?access_token=ACCESS_TOKEN',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-Api-Key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

[
  {
    "id": 54,
    "user_id": 2,
    "name": "empty",
    "alias": null,
    "published": false
  },
  {
    "id": 7,
    "user_id": 2,
    "name": "Computer",
    "alias": null,
    "published": true
  }
]

HTTP Request

GET https://api.coposition.com/users/USER_ID/devices?access_token=ACCESS_TOKEN

For a specific device (will return full device info if developer configures device)

GET https://api.coposition.com/users/USER_ID/devices/DEVICE_ID?access_token=ACCESS_TOKEN

For a specific device:

{
  "data": {
    "id": 1,
    "uuid": "95515f5a-c89c-476d-9360-f58a12fb3878",
    "user_id": 1,
    "name": "mobile",
    "fogged": false,
    "delayed": null,
    "alias": null,
    "published": false,
    "cloaked": false
  },
  "config": {
    "id": 1,
    "developer_id": 1,
    "device_id": 1,
    "custom": null,
    "created_at": "2016-08-30T10:48:15.911Z",
    "updated_at": "2016-08-30T10:48:15.911Z"
  }
}

Headers

X-Api-Key Content-Type Cache-Control

Configs

Configs allow developers to set and control any additional device settings they would like. For example, a developer producing a tracking device may want to be able to control the how often the tracking device checks in. Configs are created when a developer requests a UUID. The device with this UUID will have a config that can be updated by the developer.

Getting a list of configs

Use this endpoint to see a list of device configs under your control.

curl -X GET "https://api.coposition.com/configs/"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/configs/',
  headers:
   { 'x-api-key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

[
  {
    "id": 3,
    "developer_id": 2,
    "device_id": 100,
    "custom": null,
    "created_at": "2016-06-09T11:22:22.109Z",
    "updated_at": "2016-06-09T11:22:22.109Z"
  }
]

HTTP Request

GET https://api.coposition.com/configs

Headers

X-Api-Key

Getting a specific config

Use this endpoint to see a specific config

curl -X GET "https://api.coposition.com/configs/CONFIG_ID"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/configs/CONFIG_ID',
  headers:
   { 'x-api-key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "id": 3,
  "developer_id": 2,
  "device_id": 100,
  "custom": null,
  "created_at": "2016-06-09T11:22:22.109Z",
  "updated_at": "2016-06-09T11:22:22.109Z"
}

HTTP Request

GET https://api.coposition.com/configs/CONFIG_ID

Headers

X-Api-Key

Updating a specific config

Use this endpoint to update a specific config. Any and as many key/value combinations you want can go within custom, type/mode/frequency are just examples.

curl -X PUT "https://api.coposition.com/configs/CONFIG_ID"
  -H "X-Api-Key: YOUR_API_KEY_HERE"
  -H "Content-Type: application/json"
  -d '{
    "config": {
      "custom": {
        "type": "herds",
        "mode": "accurate",
        "frequency": "1000"
        }
      }
    }'

var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.coposition.com/configs/CONFIG_ID',
  headers:
    { 'x-api-key': 'YOUR_API_KEY_HERE'
      'content-type': 'application/json' },
    body: { config: { custom: { "type": "herds", "mode": "accurate", "frequency": "1000" } } },
    json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "id": 3,
  "developer_id": 2,
  "device_id": 195,
  "custom": {
    "type": "herds",
    "mode": "accurate",
    "frequency": "1000"
  },
  "created_at": "2016-06-09T11:22:22.451Z",
  "updated_at": "2016-06-15T14:22:13.214Z"
}

HTTP Request

PUT https://api.coposition.com/configs/CONFIG_ID

Headers

X-Api-Key Content-Type

Body

Attribute Value
config custom
custom { ‘any key’: 'any value’ }

Developers

Showing developer info

Allows you to view developer info such as Company name and ID which can be used in creating/updating an approval or updating permissions for a device.

curl -X GET "https://api.coposition.com/developers/DEVELOPER_ID"
  -H "X-Api-Key: YOUR_API_KEY_HERE"
  -H "Content-Type: application/json"
  -H "Cache-Control: no-cache"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/developers/DEVELOPER_ID',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json',
     'X-Api-Key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "id": 1,
  "email": "orland@kulasrolfson.net",
  "company_name": "Fakebook",
  "tagline": null,
  "redirect_url": "http://kaulkerenner.biz/"
}

HTTP Request

GET https://api.coposition.com/developers/DEVELOPER_ID

List of all developers

GET https://api.coposition.com/developers

Headers

X-Api-Key Content-Type Cache-Control

Requests

We log all the API requests you make, each request contains information regarding the controller and action the request was made to and user the data belongs to.

For example, if you requested to see a list of a user’s checkins, this would be recorded as a request to the index action of the checkins controller and would contain the user_id for the user who’s checkins you requested.

Getting API request information

Allows you to view previous API requests that you have made regarding a specific user.

curl -X GET "https://api.coposition.com/users/USER_ID/requests?access_token=ACCESS_TOKEN"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/users/USER_ID/requests?access_token=ACCESS_TOKEN',
  headers:
   { 'X-Api-Key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

[
  {
    "id": 2,
    "developer_id": 1,
    "created_at": "2017-11-24T22:53:31.403Z",
    "paid": false,
    "user_id": 1,
    "action": "index",
    "controller": "api/v1/checkins"
  },
  {
    "id": 1,
    "developer_id": 1,
    "created_at": "2017-11-23T16:26:34.542Z",
    "paid": false,
    "user_id": 1,
    "action": "last",
    "controller": "api/v1/checkins"
  },
]

HTTP Request

GET https://api.coposition.com/users/USER_ID/requests?access_token=ACCESS_TOKEN

Headers

X-Api-Key

Getting last API request made

Allows you to view the last API request you made for a specific user.

curl -X GET "https://api.coposition.com/users/USER_ID/requests/last?access_token=ACCESS_TOKEN"
  -H "X-Api-Key: YOUR_API_KEY_HERE"

var request = require("request");

var options = { method: 'GET',
  url: 'https://api.coposition.com/users/USER_ID/requests/last?access_token=ACCESS_TOKEN',
  headers:
   { 'X-Api-Key': 'YOUR_API_KEY_HERE' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

[
  {
    "id": 2,
    "developer_id": 1,
    "created_at": "2017-11-24T22:53:31.403Z",
    "paid": false,
    "user_id": 1,
    "action": "index",
    "controller": "api/v1/checkins"
  }
]

HTTP Request

GET https://api.coposition.com/users/USER_ID/requests/last?access_token=ACCESS_TOKEN

Headers

X-Api-Key

Errors

The Coposition API uses the following error codes.

Error Code Meaning
400 Bad Request – Your request is missing required parameters.
401 Unauthorized – Your API key is wrong, a user has not approved you or you need to sign in.
403 Forbidden – You do not have access to the specified resource.
404 Not Found – The specified resource or endpoint could not be found.
500 Internal Server Error – We had a problem with our server. Try again later.
cURL node.js