1 – Available resources

Accuware 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. The available resources are:

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 Accuware 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 Accuware 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 Accuware server during the upload of the floor plan image through the Accuware 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 devices

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 devices within a site are identified by their pseudo MAC address (pMAC) which is a unique ID generated by the Accuware 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

Example

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

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

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. Accuware 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 devices. Full control access is required to create and delete user accounts within a specific site.

Example

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

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

2 – 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.

Performances of the API: the Accuware 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:

More information in this page.

3 – Accessing the API

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

Example

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

3.1 – Browser access

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

After you have installed the plugin, simply:

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

Using the browser access you can only invoke GET methods.

Example

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

Accuware Wi-Fi Location Monitor API - browser access

3.2 – 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:

  1. Download cURL.
  2. Unzip cURL in a folder on your PC (e.g. C:\curl).
  3. 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:

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

3.3 – 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.

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:

  1. 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.
  2. 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.
  3. Choose GET from the drop-down menu.
  4. Click on the button URL params.
  5. Click on the Basic Auth tab.
    • Username: your_username.
    • Password: your_password.
  6. Click on the Refresh Header button.
  7. Click on Send.

Additional REST clients for your browser:

4 – Access to location Information

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

4.1 – 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.

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.

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

Example

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

Since the number of BLE devices active within a site can be potentially large, it is possible to filter the results by only querying those BLE devices 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:

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.

4.2 – Asynchronous access (callback mechanism) at site level

The asynchronous interface allows the user to define a list of BLE devices to monitor and a callback URI that will be invoked whenever any of these BLE devices is detected by any of the BLE nodes of the site. Basically whenever one of the BLE devices (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 devices detected by any of the BLE nodes of the site.

Create and delete a callback list

To activate the callback service you need to:

  1. 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:
  2. Associate the callback URI to your Accuware Bluetooth Beacon Tracker site:
    And you will get this message:

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

Manage the BLE devices 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:
  • Retrieve the BLE devices registered in a callback list
    To retrieve the pMAC addresses of all the BLE devices registered in the callback list:
 

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

 

4.3 – 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 devices is detected by any of the BLE nodes of the site.

In addition to this service, Accuware 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 devices to monitor and a callback URL that will be invoked whenever any of the BLE devices (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:

  1. 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:
  2. Associate the callback URL to your Accuware Bluetooth Beacon Tracker site:
    And you will get this message:

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

Manage the BLE devices 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:
 

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

 

  • 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:

JSON representation of the data POSTED to the callback URL

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 devices registered in the callback list of a site. The positions of such BLE devices 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 devices 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.