1 – Available resources

Accuware provides the Wearabouts 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.

Devices

Android devices, iOS devices and Smart Tags within a site are identified using the deviceID:

  • Wearabouts App for Android: the deviceID is the pseudo-MAC addresses (or pMAC) which is a unique ID generated by the Accuware Indoor Tracking engine. The pMAC address can be found inside the main screen of the Wearabouts App running on the device and contains a total of 12 characters beginning with a “W”.
  • Wearabouts App for iOS: the deviceID is the pseudo-MAC addresses (or pMAC) which is a unique ID generated by the Accuware Indoor Tracking engine. The pMAC address can be found inside the main screen of the Wearabouts App running on the device and contains a total of 12 characters beginning with a “X”.
  • Accuware Smart Tags: the deviceID is the MAC address printed on a label on the back of the Accuware Smart Tag and begins with 54:FB:58….

The pMAC and the MAC address can 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 identifiers that points to the same resource:

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

PLEASE READ: inside the Accuware dashboard you will find a special user called navimote@navizon.com with Read-Write access. This user is required by the Wearabouts engine and MUST not be deleted!

Fingerprints

A fingerprint is a collection of radio signal identifiers and their corresponding Received Signal Strength (RSS) detected at specific, known physical location (identified by latitude, longitude and level) of a specific site. Each fingerprint is identified by an integer, positive and progressive ID (the fingerprintID). Inside each fingerprints, the radio signal indentifiers can be of two types:

  • Wi-Fi access points – identified by the MAC address of their network interface
  • iBeacons – identified by the pMAC (pseudo MAC address) which is a unique ID generated by the Accuware Indoor Tracking engine using the UUID, Major and Minor of the iBeacon.

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: creates or modifies a resource.
  • DELETE: removes a resource.

Performances of the API:  the Accuware server supports HTTPS data compression allowing thus a better use of available bandwidth between your client and our server and providing in the end 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 point to the resource to be manipulated.

Example

The URI below refers to all the device within Site 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.

3.2 – cURL (command line)

Another way to access the API is via the command line tool cURL freely available at https://curl.haxx.se/. cURL is a command line tool for transferring 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 HTTPS method GET is invoked on the resource. Other methods can be called with the –X option:

3.3 – RESTful client (for Chrome)

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

To retrieve the location of the all the devices 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://navimote2.navizon.com/api/v1/sites/1001/devices/?with=status
  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

Wearabouts is designed to track the locations of Android devices, iOS devices and Smart Tags active within a site. Locations can be accessed synchronously by issuing the following call. The Accuware server will retrieve the status of all the devices registered within the site. This is a call typically issued by web or mobile applications.

/api/v1/sites/{siteID}/devices/?with=udo,status

GET

Retrieves status information about all the devices (Android, iOS and Smart Tags) registered within a site

Resource-wide template parameters:

  • {siteId}: site identification string.

Available response representations:

  • 200 OK – application/json
  • JSON representation of the devices’ status

Query parameters:

  • udo: user defined objects will be returned (see JSON below)
  • status: a list of DeviceStatusResult objects is returned (see JSON below)

Example:

Retrieve the status of all the devices registered within site 1001:

The result is a JSON Object. If the status is available, it will be returned with the response:

JSON fields:

  • mac: for Andorid Device this is the pMac provided by the Wearabouts App. For Smart Tags this is the MAC address that can be found on the back of the Smart Tag.
  • device status:
    • battery: estimated battery percentage. Value with minus (-) means that the battery is charging.
    • device_events:
      • panic (only for Smart Tags): timestamp of the last button press
      • moving: timestamp of the last movement.
      • pwr_up (only for Smart Tags): timestamp of the last activation of the Smart Tag.
    • fw_version: firmware version.
    • received_at: timestamp of the last status.
    • type_of_device: the device capabilities are wifi (Smart Tag), or wifi,gsm,gps (for Android devices).
    • gps_timestamp (only for Android devices): timestamp of the last location computed by the Android location manager
    • gps_latitude (only for Android devices): latitude of the last location computed by the Android location manager
    • gps_longitude (only for Android devices): longitude of the last location computed by the Android location manager
  • position:
    • siteID: site identification.
    • levelID: last level identification
    • source: source location type:
      • N3 – this location is computed by using the database of fingerprints available if an indoor fingerprinting has been performed.
      • N1 – this location is computed by using the Navizon global database of Wi-Fi APs and Cell-IDs throughout the world. More information available here.
      • Core – this location is provided by the Android or iOS location manager.
    • fixed_at: last location fix.
    • lat/lng: a pair of latitude/longitude coordinates.
    • precision: an estimated radius of confidence where the device can be found.
  • device_type:
    • NZ002.2 are the Smart Tags
    • NWA1 are Android devices.
    • NWA2 are iOS devices.
  • udo:
    • name: device name assigned using the Accuware dashboard
    • desc: device description assigned using the Accuware dashboard
  • current_server_time: server timestamp when the query was made.

Timestamps: the timestamps are UTC Unix epoch timestamps 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