Back to top

Sunstone Cloud API

Sunstone Cloud API is the all-in-one interface to positioning and data backend functions provided to Sunstone Cloud users.

The API is built around the tag concept. The tag is the single entity that can be tracked by Sunstone RTLS. Each tag will have an 3D position and can have additional properties either coming from the Sunstone RTLS or set by the API.

Tags

Tag

Retrieve a Tag
GET/tagdata/{tagId}

Retrieves the tag with the given Id

Example URI

GET /tagdata/tagId
URI Parameters
HideShow
tagId
number (required) 

the Id of the desired tag

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "tagId": 82,
  "type": "minitag",
  "pos": [
    2.3,
    5.5,
    1.8
  ],
  "accelerometer": [
    2.3,
    5.5,
    1.8
  ],
  "batteryPercent": 78,
  "inUserZone": "Not Found",
  "inZone": [
    1,
    23
  ],
  "updatedAt_msFromEpoch": 1535305880647,
  "updatedAt": "2018-08-27T17:52:03.012314"
}
Attribute nameTypeRequiredDescriptionConstraints
tagIdnumber(required)the Id of the tag
typestring(required)the type of the tag, can be minitag, duratag, scannertag, forklifttag
posarray(optional)x,y,z position of the tag in meters
accelerometerarray(optional)x,y,z acceleration affecting the tag in g (9.81m/s2)
batteryPercentnumber(optional)the level of battery relative to full state
inUserZonestring(optional)**DEPRECATED** (will be not supported from 1.0) the name of the zone where tag is else Not Found
inZonearray(required)the zoneIds of zones covering tag's position
updatedAt_msFromEpochnumber(optional)tag structure last updated at this time (milliseconds from epoch)
updatedAtstring(optional)tag structure last updated at this time in ISO8601_FRAC_FORMAT
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tagId": {
      "type": "number",
      "description": "the Id of the tag"
    },
    "type": {
      "type": "string",
      "description": "the type of the tag, can be minitag, duratag, scannertag, forklifttag"
    },
    "pos": {
      "type": "array",
      "description": "x,y,z position of the tag in meters"
    },
    "accelerometer": {
      "type": "array",
      "description": "x,y,z acceleration affecting the tag in g (9.81m/s2)"
    },
    "batteryPercent": {
      "type": "number",
      "description": "the level of battery relative to full state"
    },
    "inUserZone": {
      "type": "string",
      "description": "**DEPRECATED** (will be not supported from 1.0) the name of the zone where tag is else Not Found"
    },
    "inZone": {
      "type": "array",
      "description": "the zoneIds of zones covering tag's position"
    },
    "updatedAt_msFromEpoch": {
      "type": "number",
      "description": "tag structure last updated at this time (milliseconds from epoch)"
    },
    "updatedAt": {
      "type": "string",
      "description": "tag structure last updated at this time in ISO8601_FRAC_FORMAT"
    }
  },
  "required": [
    "tagId",
    "type",
    "inZone"
  ]
}

Create a new Tag
POST/tagdata

Add a new tag

Example URI

POST /tagdata
Request
Headers
Content-Type: application/json
Body
{
  "tagId": 82,
  "type": "minitag"
}
Attribute nameTypeRequiredDescriptionConstraints
tagIdnumber(required)the Id of the tag
typestring(required)the type of the tag, can be minitag, duratag, scannertag, forklifttag
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tagId": {
      "type": "number",
      "description": "the Id of the tag"
    },
    "type": {
      "type": "string",
      "description": "the type of the tag, can be minitag, duratag, scannertag, forklifttag"
    }
  },
  "required": [
    "tagId",
    "type"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Update custom properties of a Tag
PUT/tagdata/

Update custom properties of a tag

Example URI

PUT /tagdata/
Request
Headers
Content-Type: application/json
Body
{
  "customProperty1": "Hello, world!",
  "customProperty2": "Hello, world!",
  "customProperty3": "Hello, world!"
}
Attribute nameTypeRequiredDescriptionConstraints
customProperty1string(optional)
customProperty2string(optional)
customProperty3string(optional)
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "customProperty1": {
      "type": "string"
    },
    "customProperty2": {
      "type": "string"
    },
    "customProperty3": {
      "type": "string"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Delete a Tag
DELETE/tagdata/{tagId}

Example URI

DELETE /tagdata/tagId
URI Parameters
HideShow
tagId
number (required) 

the Id of the desired tag

Response  200
HideShow
Headers
Content-Type: application/json

List Tags
GET/tagdata{?filter}

Example URI

GET /tagdata?filter=
URI Parameters
HideShow
filter
filter query (optional) 

a filter query has a following structure

<propertyname>_<operator>=<value>

<propertyname>:

indicates a property in the tag stucture, like batteryPercent or inUserZone

<operator>:

  • equal can be used with string and number type properties, will show tags with matching property

  • has can be used with array types, will show tags, where the array containes the value

Example

?inZone_has=3 lists all the tags, that are in zone with zoneId=3

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "tagId": 82,
    "type": "minitag"
  }
]
Attribute nameTypeRequiredDescriptionConstraints
tagIdnumber(required)the Id of the tag
typestring(required)the type of the tag, can be minitag, duratag, scannertag, forklifttag
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "tagId": {
        "type": "number",
        "description": "the Id of the tag"
      },
      "type": {
        "type": "string",
        "description": "the type of the tag, can be minitag, duratag, scannertag, forklifttag"
      }
    },
    "required": [
      "tagId",
      "type"
    ]
  }
}

Update Stream of All Tags
GET/websocket

A websocket containing updates in json-patch format for all tags. Below example is a position update for tag number 82.

Example URI

GET /websocket
Request
Headers
Upgrade: websocket
Connection: Upgrade
Response  101
HideShow
Body
{ "op": "replace", "path": "/tagdata/82/pos", updatedAt: "2018-08-27T17:52:03.012314", "value": [12.2, 5.3, 2.1] }

Zones

Zones are areas of interest defined by a rectangle

Zone

Modify a Zone
PUT/zones/{zoneId}

Modifies the zone with the given Id

Example URI

PUT /zones/zoneId
URI Parameters
HideShow
zoneId
number (required) 

the Id of the desired zone

Request
Headers
Content-Type: application/json
Body
{
  "name": "myZone",
  "upperBounds": [
    15,
    10,
    2.8
  ],
  "lowerBounds": [
    0,
    0,
    0
  ],
  "zoneId": 1
}
Attribute nameTypeRequiredDescriptionConstraints
namestring(required)the name of the zone
upperBoundsarray(required)x,y,z position of the 1st corner of the zone's rectangle in meters
lowerBoundsarray(required)x,y,z position of the 3rd corner of the zone's rectangle in meters
zoneIdnumber(required)the Id of the zone
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the name of the zone"
    },
    "upperBounds": {
      "type": "array",
      "description": "x,y,z position of the 1st corner of the zone's rectangle in meters"
    },
    "lowerBounds": {
      "type": "array",
      "description": "x,y,z position of the 3rd corner of the zone's rectangle in meters"
    },
    "zoneId": {
      "type": "number",
      "description": "the Id of the zone"
    }
  },
  "required": [
    "name",
    "upperBounds",
    "lowerBounds",
    "zoneId"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Retrieve a Zone
GET/zones/{zoneId}

Retrieves the zone with the given Id

Example URI

GET /zones/zoneId
URI Parameters
HideShow
zoneId
number (required) 

the Id of the desired zone

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "myZone",
  "upperBounds": [
    15,
    10,
    2.8
  ],
  "lowerBounds": [
    0,
    0,
    0
  ],
  "zoneId": 1
}
Attribute nameTypeRequiredDescriptionConstraints
namestring(required)the name of the zone
upperBoundsarray(required)x,y,z position of the 1st corner of the zone's rectangle in meters
lowerBoundsarray(required)x,y,z position of the 3rd corner of the zone's rectangle in meters
zoneIdnumber(required)the Id of the zone
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the name of the zone"
    },
    "upperBounds": {
      "type": "array",
      "description": "x,y,z position of the 1st corner of the zone's rectangle in meters"
    },
    "lowerBounds": {
      "type": "array",
      "description": "x,y,z position of the 3rd corner of the zone's rectangle in meters"
    },
    "zoneId": {
      "type": "number",
      "description": "the Id of the zone"
    }
  },
  "required": [
    "name",
    "upperBounds",
    "lowerBounds",
    "zoneId"
  ]
}

Create a new Zone
POST/zones

Add a new zone in the collection

Example URI

POST /zones
Request
Headers
Content-Type: application/json
Body
{
  "name": "myZone",
  "upperBounds": [
    15,
    10,
    2.8
  ],
  "lowerBounds": [
    0,
    0,
    0
  ]
}
Attribute nameTypeRequiredDescriptionConstraints
namestring(required)the name of the zone
upperBoundsarray(required)x,y,z position of the 1st corner of the zone's rectangle in meters
lowerBoundsarray(required)x,y,z position of the 3rd corner of the zone's rectangle in meters
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the name of the zone"
    },
    "upperBounds": {
      "type": "array",
      "description": "x,y,z position of the 1st corner of the zone's rectangle in meters"
    },
    "lowerBounds": {
      "type": "array",
      "description": "x,y,z position of the 3rd corner of the zone's rectangle in meters"
    }
  },
  "required": [
    "name",
    "upperBounds",
    "lowerBounds"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "myZone",
  "upperBounds": [
    15,
    10,
    2.8
  ],
  "lowerBounds": [
    0,
    0,
    0
  ],
  "zoneId": 1
}
Attribute nameTypeRequiredDescriptionConstraints
namestring(required)the name of the zone
upperBoundsarray(required)x,y,z position of the 1st corner of the zone's rectangle in meters
lowerBoundsarray(required)x,y,z position of the 3rd corner of the zone's rectangle in meters
zoneIdnumber(required)the Id of the zone
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the name of the zone"
    },
    "upperBounds": {
      "type": "array",
      "description": "x,y,z position of the 1st corner of the zone's rectangle in meters"
    },
    "lowerBounds": {
      "type": "array",
      "description": "x,y,z position of the 3rd corner of the zone's rectangle in meters"
    },
    "zoneId": {
      "type": "number",
      "description": "the Id of the zone"
    }
  },
  "required": [
    "name",
    "upperBounds",
    "lowerBounds",
    "zoneId"
  ]
}

Delete a Zone
DELETE/zones/{zoneId}

Example URI

DELETE /zones/zoneId
URI Parameters
HideShow
zoneId
number (required) 

the Id of the desired zone

Response  200
HideShow
Headers
Content-Type: application/json

List All Zones
GET/zones

Example URI

GET /zones
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "name": "myZone",
    "upperBounds": [
      15,
      10,
      2.8
    ],
    "lowerBounds": [
      0,
      0,
      0
    ],
    "zoneId": 1
  }
]
Attribute nameTypeRequiredDescriptionConstraints
namestring(required)the name of the zone
upperBoundsarray(required)x,y,z position of the 1st corner of the zone's rectangle in meters
lowerBoundsarray(required)x,y,z position of the 3rd corner of the zone's rectangle in meters
zoneIdnumber(required)the Id of the zone
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "the name of the zone"
      },
      "upperBounds": {
        "type": "array",
        "description": "x,y,z position of the 1st corner of the zone's rectangle in meters"
      },
      "lowerBounds": {
        "type": "array",
        "description": "x,y,z position of the 3rd corner of the zone's rectangle in meters"
      },
      "zoneId": {
        "type": "number",
        "description": "the Id of the zone"
      }
    },
    "required": [
      "name",
      "upperBounds",
      "lowerBounds",
      "zoneId"
    ]
  }
}

Historical data

Get data from past

Get data from past
GET/tagdata/history{?from,to,timeformat,filter}

Example URI

GET /tagdata/history?from=&to=&timeformat=&filter=
URI Parameters
HideShow
from
string (optional) 

from date filter in UTC, UTC time in the selected format

to
string (optional) 

to date filter, UTC time in the selected format

timeformat
string (optional) 

timeformat of the from and to parameters and the output: iso8601 (default), iso8601frac, http, rfc1036, rfc1123, msFromEpoch, usecFromEpoch

filter
filter query (optional) 

a filter query has a following structure

<propertyname>_<operator>=<value>

<propertyname>:

indicates a property in the historical tag structure, can be tagId or property

<operator>:

  • equal can be used with string and number type properties, will show tags with matching property

  • anyof can be used with string and number type properties, will show tags with matching any of the properties given with a comma separated list

Example

?property_equal=inZone&tagId_anyof=1111,2222 lists all zone entering and leaving

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "tagId": 82,
    "updatedAt": "2019-03-14T10:29:53.764990Z",
    "updatedAt_msFromEpoch": 1552559272657,
    "updatedAt_usecFromEpoch": 1552559333218990,
    "pos": [
      2.3,
      5.5,
      1.8
    ],
    "op": "update",
    "property": "batteryPercent",
    "value": {}
  }
]
Attribute nameTypeRequiredDescriptionConstraints
tagIdnumber(required)the Id of the tag
updatedAtstring(optional)when the update happened in the requested timeformat according to UTC.
updatedAt_msFromEpochnumber(optional)if the requested timeformat if msFromEpoch, this property will appear instead of updatedAt
updatedAt_usecFromEpochnumber(optional)if the requested timeformat if usecFromEpoch, this property will appear instead of updatedAt.
posarray(optional)x,y,z position of the tag in meters
opstring(required)the reason of the change: update, create, delete
propertystring(required)the property that has changed
valueobject(optional)the value of the property, can be number,float,string,json object
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "tagId": {
        "type": "number",
        "description": "the Id of the tag"
      },
      "updatedAt": {
        "type": "string",
        "description": "when the update happened in the requested timeformat according to UTC."
      },
      "updatedAt_msFromEpoch": {
        "type": "number",
        "description": "if the requested timeformat if msFromEpoch, this property will appear instead of updatedAt"
      },
      "updatedAt_usecFromEpoch": {
        "type": "number",
        "description": "if the requested timeformat if usecFromEpoch, this property will appear instead of updatedAt."
      },
      "pos": {
        "type": "array",
        "description": "x,y,z position of the tag in meters"
      },
      "op": {
        "type": "string",
        "description": "the reason of the change: update, create, delete"
      },
      "property": {
        "type": "string",
        "description": "the property that has changed"
      },
      "value": {
        "type": "object",
        "properties": {},
        "description": "the value of the property, can be number,float,string,json object"
      }
    },
    "required": [
      "tagId",
      "op",
      "property"
    ]
  }
}

Settings

Settings of the backend

List All Anchors

List All Anchors
GET/settings/anchors

Example URI

GET /settings/anchors
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "zoneId": 1,
    "pos": [
      15,
      10,
      2.8
    ]
  }
]
Attribute nameTypeRequiredDescriptionConstraints
zoneIdnumber(required)the Id of the anchor
posarray(required)x,y,z position of the anchor in meters
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "zoneId": {
        "type": "number",
        "description": "the Id of the anchor"
      },
      "pos": {
        "type": "array",
        "description": "x,y,z position of the anchor in meters"
      }
    },
    "required": [
      "zoneId",
      "pos"
    ]
  }
}

Get Map in SVG

Get Map in SVG
GET/settings/map/svg

Example URI

GET /settings/map/svg
Response  200
HideShow
Headers
Content-Type: image/svg+xml

Get Map Config

Get Map Config
GET/settings/map/config

Example URI

GET /settings/map/config
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "scale": 0.605,
  "xoff": 4.12,
  "yoff": 2.3,
  "xmirror": 1,
  "ymirror": 1,
  "switchxy": 1
}
Attribute nameTypeRequiredDescriptionConstraints
scalenumber(required)
xoffnumber(required)
yoffnumber(required)
xmirrornumber(required)
ymirrornumber(required)
switchxynumber(required)
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "scale": {
      "type": "number"
    },
    "xoff": {
      "type": "number"
    },
    "yoff": {
      "type": "number"
    },
    "xmirror": {
      "type": "number"
    },
    "ymirror": {
      "type": "number"
    },
    "switchxy": {
      "type": "number"
    }
  },
  "required": [
    "scale",
    "xoff",
    "yoff",
    "xmirror",
    "ymirror",
    "switchxy"
  ]
}

Generated by aglio on 14 Mar 2019