1 – Available resources

Accuware Wi-Fi Location Monitor 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.

WiFi nodes and WiFi devices

WiFi nodes within a site are identified by their MAC addresses. The MAC address is printed on a small label on their bottom.

To comply with the EU GDPR desribed here, WiFi stations (Wi-Fi enabled devices) are identified by a unique ID which is an hash of the original MAC address (from now on hMAC address). The first 3 octets of the hMAC address are identical to the first 3 octets of the original MAC address, then there is the “H” letter and then the hash of the remaining part of the original MAC address:

  • EXAMPLE: original MAC address: 14:8F:C6:11:22:22 → hMAC: 14:8F:C6:H5:21:YD

MAC addresses 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 WiFi node:

The following URIs contain valid hMAC addresses that points to the same WiFi 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 Wi-Fi Location Monitor 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 nodes and station. Full control access is required to create and delete user accounts within a specific site.

Example

The access level for a particular site is returned by querying the site resource:

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

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 WiFi Location Monitor 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 node with MAC address AC867472CF2148F0 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 WiFi device with MAC 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 WiFi device with hMAC address 148FC6H521YD 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/40: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 Wi-Fi Location Monitor is designed to track/provide the locations to the stations 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 station within a specific site. The URI for the query is composed by combining the siteID with the MAC address of the station to track.

Example

the URI below provides access to the information available in site 1001 about the station with hMAC address 148FC6H521YD.

The API also allows the developer to retrieve the locations of all the stations 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 stations seen by all the nodes of the site 1001.

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

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

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

The station’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 station was seen active. The loc field will be present only if the station was active in the site in the last two hours.

Querying a station 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 station was active four seconds before its location was queried. If the station remains not active and its location is queried again after 10 seconds, the lrrt field will be 14 seconds.

Accuware WiFI Location Monitor - LRRT

4.2 – Asynchronous access (callback mechanism) at site level

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

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

Create and delete a callback list

Steps to enable the callback service:

  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 Wi-Fi Location Monitor 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 stations in a callback list

  • Register a station to the callbacks list
    To register the hMAC address of any station you want to be notified about:
  • Retrieve stations registered in a callback list
    To retrieve the hMAC addresses of the stations registered in the callback list:
 

  • Delete stations registered in a callback list:
    To remove a station 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 stations is detected by any of the nodes of the site.

In addition to this service, Accuware Wi-Fi Location Monitor also provides a lower level mechanism that operates at node level. The asynchronous interface allows the user to define, for specific nodes, a list of stations to monitor and a callback URL that will be invoked whenever any of the stations (registered in the callback list of a node) is detected by the specific node of the site.

Create and delete a callback list

Steps to enable the callback service:

  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 Wi-Fi Location Monitor 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 stations in a callback list of a node

  • Register a station to the callbacks list of a node
    To register the hMAC address of any station you want to be notified about, to the callback list of a node:
 

  • Retrieve stations registered in a callback list of a node
    To retrieve the hMAC addresses of the stations registered in the callback list of a node:

 

  • Delete a station registered in a callback list of a node
    To remove a station from the callback list:

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 stations registered in the callback list of a site. The positions of such stations are computed using the measurements originated by all the nodes in the site. For each station you have the following fields:
    • mac: hMAC address of the station.
    • loc: station 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 station was active four seconds before its location was queried.
    • siteId: site identification.
  • The nodeNotifications array contains an array with all the nodes for which a specific callback list has been created (as described in the section Low-level callback mechanism). For each node you have a list of stations detected, and for each station you have the following fields:
    • mac: hMAC address of the station.
    • 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 station was active four seconds before its location was queried.
    • rss: signal strength measured by all the nodes able to see the station. Click here to get more information about the RSS.