API get started | Indoor Tracking

Available resources

Bluetooth Beacon Tracker exposes a RESTful web API that can be used to access and manipulate the state of set of resources registered with a site. Below you can find the list of accessible resources

Sites

Resources are accessed in the context of a particular site. Sites are identified by short alphanumeric strings (the SiteId) assigned by Accuware during the creation of each site. The SiteID can be found inside the Accuware Activation email and inside the Indoor Tracking Dashboard under General > Sites.

Levels

Each site can be made of one or multiple levels identified by a numeric IDs (the LevelId) that can be a positive or negative integer. By default, each site contains a default level (LevelId = 0) that can’t be eliminated. Using the Indoor Tracking Dashboard it is possible to create up to 30 Levels (from Level -10 to level +20) plus Level 0. Additional levels can be created using this PUT API call. Levels can be used to divide:

different physical floors of a multi-story building (e.g. a LevelId for each floor of a shopping mall).
or different areas (at the same altitude) of one or multiple buildings (e.g. a LevelId for each store of a retail chain).

Floorplans

Floor plans provide reference points inside a building, such as the location of walls, rooms, hallways, elevators, staircases, atriums, windows, doors etc… Each floorplan is identified by an alphanumeric strings (the fpId) assigned by the Indoor Tracking server during the upload of the floor plan image through the Indoor Tracking Dashboard. Even if it is possible to assign more than one floor plan to each level we strongly suggest to add one and only one floor plan to each level.

BLE nodes and BLE beacons

BLE nodes within a site are identified by their MAC addresses. The MAC address is printed on a small label on the bottom of the nodes. BLE beacons within a site are identified by their pseudo MAC address (pMAC) which is a unique ID generated by the Bluetooth Beacon Tracker dashboard starting from the UUID, Major and Minor.

MAC addresses and pMAC be can expressed in three different formats:

000000000000
00:00:00:00:00:00
00-00-00-00-00-00

[stextbox id=”grey”]

Example

The following URIs contain valid MAC addresses that points to the same BLE node:

https://its.accuware.com/api/v1/sites/1001/nodes/7072CF2148F0/
https://its.accuware.com/api/v1/sites/1001/nodes/70:72:CF:21:48:F0/
https://its.accuware.com/api/v1/sites/1001/nodes/70-72-CF-21-48-F0/

The following URIs contain valid pMAC addresses that points to the same BLE device:

https://its.accuware.com/api/v1/sites/1001/stations/IAHXUH9AAZJ4/
https://its.accuware.com/api/v1/sites/1001/stations/IA:HX:UH:9A:AZ:J4/
https://its.accuware.com/api/v1/sites/1001/stations/IA-HX-UH-9A-AZ-J4/

User accounts

Access to the resources is restricted to registered users on a per-site basis. Each account is identified by an username (an email address) and a password. Bluetooth Beacon Tracker defines three possible access levels for each user account registered with a site:

Read-Only (access = 10)
Read-Write (access = 20)
Full Control (access = 30)

Users with Read-Only access are not allowed to make changes to the site, while users with Read-Write access can modify data regarding BLE nodes and BLE beacons. Full control access is required to create and delete user accounts within a specific site.

[stextbox id=”grey”]

Example

The list of sites associated with each account is available by querying the global site resource:

curl -u username:password https://its.accuware.com/api/v1/sites/

The command above returns a JSON representation of all the sites registered with the account defined by username:password

[
{
    "desc": "EXP. JUN 8th - DEVELOPMENT",
    "siteId": "1001",
    "address": "1.899079,4.80904",
    "name": "Site A",
    "access": "20",
},
{
    "desc": "OPEN ENDED - PRODUCTION",
    "siteId": "1002",
    "address": "43.857165, -79.460979"
    "name": "Site B",
    "access": "30",
}
]

Operations on resources

Operations on resources are controlled by using one of the following HTTPS methods:

GET: retrieves the representation of a resource (JSON format).
PUT, POST: creates or modifies a resource.
DELETE: removes a resource.

[stextbox id=’info’]

Performances of the API: the Bluetooth Beacon Tracker server supports HTTPS data compression allowing thus a better use of available bandwidth between your client and our server and providing in the end a greater transmission speeds between both.

In order to make use of the compression you have to includes the following supported compression schema in the header of the HTTPS request:

"Accept-Encoding: gzip, deflate"

More information in this page.

Accessing the API

The API is accessed using URIs that points to the resource to be manipulated.

[stextbox id=”grey”]

Example

The URI below refers to the BLE node with MAC address 7072CF2148F0 installed at site with ID 1001:

https://its.accuware.com/api/v1/sites/1001/nodes/7072CF2148F0/

Browser access

For debugging and testing purposes you can access the API using your browser along with a plugin such as:

for Google Chrome – JSONView and JSONLint.
for Firefox – JSONovich.

After you have installed the plugin, simply:

type the URI in the address bar of the browser.
supply your Accuware credentials when prompted.

Using the browser access you can only invoke GET methods.
[stextbox id=’grey’]

Example

The URI below refers to the BLE device with pMAC E8:92:A4:99:36:F9 inside site 1001:

cURL (command line)

Another way to access the API is via the command line tool cURL freely available at this link that can be used to transfer data with URL syntax. To install and use cURL:

Download cURL.
Unzip cURL in a folder on your PC (e.g. C:\curl).
Open a shell/command line and go in the cURL folder (e.g. C:\curl).

Using cURL, it is possible to supply user credentials necessary to access a resource with the -u option:

curl -u username:password https://its.accuware.com/api/v1/sites/1001/nodes/7072CF2148F0/

By default, the HTTP method GET is invoked on the resource. Other methods can be called with the –X option:

curl -u username:password -X PUT https://its.accuware.com/api/v1/sites/1001/nodes/7072CF2148F0/
curl -u username:password -X POST https://its.accuware.com/api/v1/sites/1001/nodes/7072CF2148F0/
curl -u username:password -X DELETE https://its.accuware.com/api/v1/sites/1001/nodes/7072CF2148F0/

POSTman for Chrome

POSTman is a powerful client to help test web services easily and efficiently. POSTman can be easily downloaded from the Chrome Webstore at this link.

[stextbox id=’grey’]

Example

To retrieve the location (and the RSS) of the BLE device with pMAC address I8:92:A4:99:36:F9 inside site 1001, you have to:

Install POSTman from the link above and access the POSTman app in Chrome by clicking the Apps button (located in the top-left corner of your browser) and the POSTman – REST Client icon.
Insert the following URL into the Enter request URL here text field: https://its.accuware.com/api/v1/sites/1001/stations/I8:92:A4:99:36:F9/?rss=yes.
Choose GET from the drop-down menu.
Click on the button URL params.
Click on the Basic Auth tab.
- Username: your_username.
- Password: your_password.
Click on the Refresh Header button.
Click on Send.

Additional REST clients for your browser:

for Google Chrome – ADVANCED REST CLIENT
for Firefox – RESTClient

Access to location Information

Bluetooth Beacon Tracker is designed to track/provide the locations to the BLE beacons active within a site. Location can be accessed synchronously or asynchronously (via a callback mechanism).

Synchronous access

The synchronous interface is used to query the location of a BLE device within a specific site. The URI for the query is composed by combining the SiteID with the pMAC address of the BLE device to track.

[stextbox id=”grey”]

Example

The URI below provides access to the information available in site 1001 about the BLE device with pMAC address 00:23:76:98:BD:EC.

https://its.accuware.com/api/v1/sites/1001/stations/00237698BDEC/

The API also allows the developer to retrieve the locations of all the BLE beacons active within a site. In this case, the URI only contains a reference to the SiteId.

[stextbox id=”grey”]

Example

the URI below provides access to the information about all the BLE beacons seen by all the BLE nodes of the site 1001.

https://its.accuware.com/api/v1/sites/1001/stations/

Since the number of BLE beacons active within a site can be potentially large, it is possible to filter the results by only querying those BLE beacons that were active in a specified time interval, for example in the last five minutes.The list of query parameters is available in the API – reference page.

The API – Code samples page contains examples written in different programming languages that show how to query the service and parse the JSON results.

JSON Representation of a BLE device information

The location of a BLE device is represented in JSON format as in the following example:

{
    "mac": "10BF48F0E653",
    "name": "Tablet",
    "desc": "iPad 3",
    "loc": {
        "lat": 32.797585,
        "lng": -117.249064,
        "levelId": 0,
        "prec": 5 //do not consider this field
    },
    "lrrt": 1,
     "rss": {
         "AC8674106778": -81,
         "AC8674102580": -63,
         "AC8674106780": -80
      }
}

The fields name and desc will be included in the representation only if the BLE device has been previously registered in the list of known devices for the site.

The BLE device’s location is contained in the loc field, and it is represented by a pair of latitude/longitude coordinates and the ID of the level where the BLE device was seen active. The loc field will be present only if the BLE device was active in the site in the last two hours.

Querying a BLE device that was not active in the site for the past two hours and not registered in the list of known devices will cause the server to return a HTTP 404 – Not Found status code.

The field RSS represents the signal strength received by all the nodes in your site. Click here to get more information about the RSS.

The field lrrt (Last Report Relative Time) measures the seconds elapsed between the time the device was last seen active and the time the server was queried. For example, a value lrtt=4 means that the BLE device was active four seconds before its location was queried. If the BLE device remains not active and its location is queried again after 10 seconds, the lrrt field will be 14 seconds.

Asynchronous access (callback mechanism) at site level

The asynchronous interface allows the user to define a list of BLE beacons to monitor and a callback URI that will be invoked whenever any of these BLE beacons is detected by any of the BLE nodes of the site. Basically whenever one of the BLE beacons (registered in the callback list of the site) emit a BLE signal.

A JSON representation of the devices will be POSTED to the user-defined URI (callback URI). The service rate is limited to a maximum of 1 notification every 5 seconds, and each call will contain information about all the BLE beacons detected by any of the BLE nodes of the site.

Create and delete a callback list

To activate the callback service you need to:

Activate a web server on an URI where you will receive the notifications. In the following examples, we will assume that your server is accessible (make sure the URI is accessible from outside the firewall) at:
```
http://my.domain.com/ItsPost.php
```

Associate the callback URI to your Bluetooth Beacon Tracker site:

curl -u username:password -X PUT -d "url=https://my.domain.com/ItsPost.php" https://its.accuware.com/api/v1/sites/{siteId}/callbacks/

And you will get this message:

{
    "url": "https://my.domain.com/ItsPost.php"
}

To disable all the notifications you have to delete the callback URL by calling this URI:

curl -u username:password -X DELETE https://its.accuware.com/api/v1/sites/{siteId}/callbacks/

Manage the BLE beacons in a callback list

Register a BLE device to the callbacks list
To register the pMAC address of any BLE device you want to be notified about:

curl -u username:password -X PUT https://its.accuware.com/api/v1/sites/{siteId}/callbacks/stations/{mac}/

Retrieve the BLE beacons registered in a callback list
To retrieve the pMAC addresses of all the BLE beacons registered in the callback list:

curl -u username:password https://its.accuware.com/api/v1/sites/{siteId}/callbacks/stations/

Delete a BLE device registered in a callback list:
To remove a BLE device from the callback list:

curl -u username:password -X DELETE https://its.accuware.com/api/v1/sites/{siteId}/callbacks/stations/{mac}/

Asynchronous access (callback mechanism) at node level

The callback mechanism described above operates at the site level, i.e. the callback URL will be invoked whenever any of the registered BLE beacons is detected by any of the BLE nodes of the site.

In addition to this service, Bluetooth Beacon Tracker also provides a callback mechanism that operates at node level. The asynchronous interface allows the user to define, for specific BLE nodes, a list of BLE beacons to monitor and a callback URL that will be invoked whenever any of the BLE beacons (registered in the callback list of a BLE node) is detected by the specific BLE node of the site.

Create and delete a callback list

To activate the callback service you need to:

Activate a web server on an URL where you will receive the notifications. In the following examples, we will assume that your server is accessible (make sure the URL is accessible from outside the firewall) at:
```
http://my.domain.com/ItsPost.php
```

Associate the callback URL to your Bluetooth Beacon Tracker site:

curl -u username:password -X PUT -d "url=https://my.domain.com/ItsPost.php" https://its.accuware.com/api/v1/sites/{siteId}/callbacks/

And you will get this message:

{
    "url": "https://my.domain.com/ItsPost.php"
}

To disable all the notifications you have to delete the callback URL by calling this URI:

curl -u username:password -X DELETE https://its.accuware.com/api/v1/sites/{siteId}/callbacks/

Manage the BLE beacons in a callback list of a BLE node

Register a BLE device to the callbacks list of a BLE node
To register the pMAC address of any BLE device you want to be notified about, to the callback list of a BLE node:

curl -u username:password -X PUT https://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/stations/{mac}/

Retrieve BLE beacons registered in a callback list of a BLE node
To retrieve the pMAC addresses of the BLE beacons registered in the callback list of a BLE node:

curl -u username:password https://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/stations/

Delete a BLE device registered in a callback list of a BLE node
To remove a BLE device from the callback list of a BLE node:

curl -u username:password -X DELETE https://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/stations/{mac}/

JSON representation of the data POSTED to the callback URL

{
    "time": 1324416340589,
    "siteNotifications": [
        {
            "mac": "0072CF1733B1",
            "loc": {
                "lat": 32.797544,
                "lng": -117.249093,
                "levelId": 0
            },
            "lrrt": 3,
            "siteId": "1001"
        },
        {
            "mac": ...
            ...
        }
    ],
    "nodeNotifications": [
        {
            "node": "AC8674022A38",
            "stations": [
                {
                    "mac": "00237698BDEC",
                    "lrrt": 3,
                    "rss": -33
                },
                {
                    "mac": "AC867401EF03",
                    "lrrt": 3,
                    "rss": -43
                }
            ]
        }
    ]
}

The data posted by the server contains a JSON with 3 fields:

The time field contains the UTC timestamp (Unix epoch) in milliseconds. The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00:00:00Z). You can find an Epoch & Unix Timestamp Conversion Tool at this link
The siteNotifications array contains an array with all the BLE beacons registered in the callback list of a site. The positions of such BLE beacons are computed using the measurements originated by all the BLE nodes in the site. For each BLE device you have the following fields:
- mac: pseudo MAC address of the BLE device.
- loc: the BLE device location.
- lrrt (Last Report Relative Time): measures the seconds elapsed between the time the device was last seen active and the time the server was queried. For example, a value lrtt=4 means that the BLE device was active four seconds before its location was queried.
- siteId: site identifier.
The nodeNotifications array contains an array with all the BLE nodes for which a specific callback list has been created (as described in the section Low-level callback mechanism). For each BLE node you have a list of BLE beacons detected, and for each BLE device you have the following fields:
- mac: pseudo MAC address of the BLE device.
- lrrt (Last Report Relative Time): measures the seconds elapsed between the time the device was last seen active and the time the server was queried. For example, a value lrtt=4 means that the BLE device was active four seconds before its location was queried.
- rss: signal strength measured by all the BLE nodes that saw the BLE device. Click here to get more information about the RSS.