home

FAQ - API

Question List


How can I get historical data of Tag?

Available resources of historical data:

  • datastreams
  • positions

Datastreams with history:

  • posX - coordinate X moved to positions history.
  • posY - coordinate Y, moved to positions history.
  • posZ - coordinate Z, moved to positions history.
  • clr - what is the confidance level of position, more about clr → https://docs.sewio.net/docs/position-confidence-level-3244634.html, moved to positions history.
  • numberOfAnchors - how many anchors were used for calculations, moved to positions history.
  • plan_reference - on what plan was the position calculated, moved to positions history.
  • battery_voltage - battery value in voltage.
  • battery_level - battery value in percentage is direct recalculation of battery voltage to 0-100 interval. More about battery value → https://docs.sewio.net/docs/tag-battery-value-9076797.html.
  • user_button - log when user button was pressed.
  • pressure - raw data from barometer sensor.
  • temperature - raw data from thermometer sensor.
  • acc - raw data from accelerometer sensor.
  • gyro - raw data from gyroscope sensor.
  • mag - raw data from magnetometer sensor.
  • quaternion - calculated rotation from accelerometer, gyroscope and magnetometer in quaternion format.

More about sensors data can be found here: https://docs.sewio.net/docs/sensors-guide-1018239.html

Provides all last datapoints of datastream. History for different tag or datastream requires separate request.

  • Path: sensmapserver/api/feeds/{id}/datastreams/{datastreams_id} or sensmapserver/api/tags/{id}/datastreams/{datastreams_id}
    • Query for specific time internal: ?start={time}&end={time}
      • Expected date format: D M d Y H:i:s e + , e.g. “Thu Oct 03 2013 07:03:41 GMT+0200 (Central Europe Standard Time)”
      • Expected date format: YYYY-MM-DDThh:mm:ss.sZ, e.g. “1970-01-01T00:00:01.123Z” or “1970-01-01 00:00:01.123”
  • Header:
    • "accept: application/json"
    • "X-ApiKey: {vlaid API Key}"

Example:

Response: Example how responses looks like can be found in API Payload Examples.

Positions history:

  • x - coordinate X.
  • y - coordinate Y.
  • z - coordinate Z.
  • at - timestamp of computed position.
  • clr - what is the confidence level of position, more about clr → https://docs.sewio.net/docs/position-confidence-level-3244634.html (If verbose = true).
  • numberOfAnchors - how many anchors were used for calculations (If verbose = true).
  • plan - on what plan was the position calculated (If verbose = true).

Provide all possible historical positions. Positional history for each tag requires separate request. It can be fetched to pages if there are more positions then maximum per page. Maximum positions per page is 10000. Verbose will show clr, number of used anchors for calculation and plan ID of the position. It is also possible to change time range of data.

  • Path: sageserver/positions or sensmapserver/positions
    • Querys:
      • id: unique ID or MAC address of the tag (required).
      • plan: optional parameter used to filter results based on plan ID. Otherwise positions from all plans are listed.
      • per_page: how many results should be fetched per page (maximum is 10 000). Default value: 10000.
      • page: number of page to be fetched. Default value: 1.
      • verbose: If set to true, there is additional information per position (clr, plan, number of anchors). Default value: false.
      • from: starting time of data in UTC. Default value: 1970-01-01 00:00:01.
      • to: ending time of data in UTC. Default value: 2038-01-19 03:14:07.
        • Expected date format: YYYY-MM-DDThh:mm:ss.sZ, e.g. “1970-01-01T00:00:01.123Z” or “1970-01-01 00:00:01.123”
  • Header:
    • "accept: application/json"
    • "X-ApiKey: {vlaid API Key}"

Example:

Response:

Available resources of historical data:

  • datastreams
  • positions

Datastreams with history:

  • posX - coordinate X moved to positions history.
  • posY - coordinate Y, moved to positions history.
  • posZ - coordinate Z, moved to positions history.
  • clr - what is the confidance level of position, more about clr → https://docs.sewio.net/docs/position-confidence-level-3244634.html, moved to positions history.
  • numberOfAnchors - how many anchors were used for calculations, moved to positions history.
  • plan_reference - on what plan was the position calculated, moved to positions history.
  • battery_level - battery value in percentage is direct recalculation of battery voltage to 0-100 interval. More about battery value → https://docs.sewio.net/docs/tag-battery-value-9076797.html.
  • user_button - log when user button was pressed.
  • pressure - raw data from barometer sensor.
  • temperature - raw data from thermometer sensor.
  • acc - raw data from accelerometer sensor.
  • gyro - raw data from gyroscope sensor.
  • mag - raw data from magnetometer sensor.
  • quaternion - calculated rotation from accelerometer, gyroscope and magnetometer in quaternion format.

More about sensors data can be found here: https://docs.sewio.net/docs/sensors-guide-1018239.html

Provides last 100 datapoints of datastream. History for different tag, datastream or different 100 datapoints requires separate request.

  • Path: sensmapserver/api/feeds/{id}/datastreams/{datastreams_id}
    • Query for specific time internal: ?start={time}&end={time}
      • Expected date format: D M d Y H:i:s e + , e.g. “Thu Oct 03 2013 07:03:41 GMT+0200 (Central Europe Standard Time)”
  • Header:
    • "accept: application/json"
    • "X-ApiKey: {vlaid API Key}"

Example:

Response: Example how responses looks like can be found in API Payload Examples.

Positions history:

  • x - coordinate X.
  • y - coordinate Y.
  • z - coordinate Z.
  • at - timestamp of computed position.
  • clr - what is the confidence level of position, more about clr → https://docs.sewio.net/docs/position-confidence-level-3244634.html (If verbose = true).
  • numberOfAnchors - how many anchors were used for calculations (If verbose = true).
  • plan - on what plan was the position calculated (If verbose = true).

Provide all possible historical positions. Positional history for each tag requires separate request. It can be fetched to pages if there are more positions then maximum per page. Maximum positions per page is 10000. Verbose will show clr, number of used anchors for calculation and plan ID of the position. It is also possible to change time range of data.

  • Path: sageserver/positions
    • Querys:
      • id: unique ID or MAC address of the tag (required).
      • plan: optional parameter used to filter results based on plan ID. Otherwise positions from all plans are listed.
      • per_page: how many results should be fetched per page (maximum is 10 000). Default value: 10000.
      • page: number of page to be fetched. Default value: 1.
      • verbose: If set to true, there is additional information per position (clr, plan, number of anchors). Default value: false.
      • from: starting time of data in UTC. Default value: 1970-01-01 00:00:01.
      • to: ending time of data in UTC. Default value: 2038-01-19 03:14:07.
        • Expected date format: YYYY-MM-DDThh:mm:ss.sZ, e.g. “1970-01-01T00:00:01.123Z” or “1970-01-01 00:00:01.123”
  • Header:
    • "accept: application/json"
    • "X-ApiKey: {vlaid API Key}"

Example:

Response:



How can I find [id] for a Tag or search full-text within all feeds?

There is full-text search available with following syntax:

http://[SERVER IP]/sensmapserver/api/feeds?q=[attribute]

,where attribute can be MAC address, feed id, plan or description.


How to get Zone (Geo Fence) notifications?

For obtaining notifications from the zones can be used WebSocket connector.

Communication is based on publish-subscribe model, where client can subscribe to stream from zone and be immediately updated about change.

Subscribe to zone changes:

{“headers”:{“X-ApiKey”:”YOUR_KEY”},”method”:”subscribe”, “resource”:”/zones/YOUR_ZONE_ID”}

Unsubscribe to zone changes:

{“headers”:{“X-ApiKey”:”YOUR_KEY”},”method”:”unsubscribe”, “resource”:”/zones/YOUR_ZONE_ID”}

Example of zone change, for example tag with ID 23 entered zone with ID 2 at particular UTC time:

{“body”:{“feed_id”:”23″,”zone_id”:”2″,”status”:”in”,”at”:”2016-10-26 09:30:58.428415″},”resource”:”\/zones\/2″}

or tag left that zone 1 minute later:

{“body”:{“feed_id”:”23″,”zone_id”:”2″,”status”:”out”,”at”:”2016-10-26 09:31:58.428415″},”resource”:”\/zones\/2″}

 

More about WebSockets in API Documentation.

Why positions are not available via REST in real-time?

Firstly storing to DB must be activated in order to get positions via REST interface.

RTLS Studio -> RTLS Manager -> RTLS Server

In order to prevent server overloading with frequent DB position writes. Position are stored in a queue and written in DB in batches of app. 200 positions or after one minute of inactivity for tag. 

Since the REST interface obtain data from DB this latency is applied for REST queries. For strict real-time positioning with minimum latency please use Websockets or UDP connector.

How to get an information about tag's Building and Plan ID from the API?

JSON body contains information about positions and additionally also data from activated sensors of the tag. Because of performance reasons, it is necessary to reduce the amount of delivered data, therefore relatively static information like building and plan name is sent only once when the tag moves from one plan to another.

See example of JSON response in the picture below:

All three available connectors inform about building and plan name:

  • On-change event (via Publish/Subscribe method) - using Websocket API. It works with subscription either on single tag or all tags.
  • On-change event - using UDP client 
  • On-demand (via Poll) - using REST API
    • GET requests of the tag information returns a JSON structure which contains part named location and in this object you can find out current Building's "name" and Plan's "ele" of the tag, which stands for plan's name. More information in API Documentation of RTLS Studio.
      • GET request on /tags - gives an information about all tags
      • GET request on /tags/{id} - gives an information about tag with specific feed id
"id": "7",
"alias": "Guard #1",
...
"location": {
  "disposition": "mobile",
  "ele": "3rd",
  "name": "Building:jic",
  "lat": "0",
  "exposure": "indoor",
  "lon": "0",
  "domain": "physical"
},
...

What is the best approach to handle building and plan considering connectivity drops?

Both REST and WebSocket are built on the top of the reliable TCP/IP connection. There is a notification available once there is an issue with an established connection. Here is a suggested procedure handling the connectivity drops within your application:

  1. Firstly subscribe tags from WebSocket.

  2. Then read last state (building/plan) for all tags via REST interface.

  3. Once the actual state of building/plan is known, you will getting updates from WebSocket.
  4. IF there is a loss Websocket connectivity some tag could change its plan in the background. Then repeat the procedure from the point 1 after the connection is established.