PLEASE READ: if you are looking for the API to manage the Dragonfly Java App then you need to look at this page.

Accuware provides the Dragonfly RESTful web API that can be used to access and manipulate the state of set of resources registered with a site. The available resources that can be manipulated using the API are:

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

Example 

The URI below refers to the site with ID 1001.

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.

Historical data: please keep in mind that we do not provide historical data and reports, therefore you have to develop the logic to collect real-time data using the API and store it in your database.

Performances of the API

The Accuware Dragonfly 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 include the following supported compression schema in the header of the HTTPS request:

More information in this page.

Accessing the API

cURL (command line)

The easiest 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 at this URL: https://curl.haxx.se/download.html
  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:

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

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

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 markers and stations. 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

Access to location information

Dragonfly is designed to track the locations of devices equipped with the Dragongly App or with an App compiled with the Dragonfly SDK. 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}/dragonfly/devices/

GET

Retrieves several information about all the devices that are running the Dragonfly App or an App compiled with the Dragonfly SDK.

HTTP Request Header:

  • Content-Type: application/json

HTTP Request Path Parameter:

  • {siteId}: site identification string.

Available response representations:

  • 200: Array of Device List Object
  • 400: Error Object
  • 401: “Not authenticated”

Example:

Retrieve the user defined objects and the status objects of all the devices registered within site 1001:

The result is a JSON like this one:

JSON fields:

  • mac: the device unique ID generated by the DragonflyApp. The pseudo MAC address contains a total of 12 characters beginning with a “D”.
  • device status:
    • battery: estimated battery percentage. Value with minus (-) means that the battery is charging.
    • fw_version: firmware version.
    • received_at: timestamp of the last status.
    • type_of_device: Dragonfly
  • position:
    • siteID: site identification.
    • levelID: last level identification
    • source: Dragonfly.
    • device: the device unique ID generated by the DragonflyApp. The pseudo MAC address contains a total of 12 characters beginning with a “D”.
    • fixed_at: last location fix.
    • lat/lng: a pair of latitude/longitude coordinates.
    • alt: the altitude in meters.
    • precision: an estimated radius of confidence where the device can be found.
  • device_type: “D”
  • udo:
    • name: the optional name automatically assigned by the Dragonfly App or assigned manually using the Edit button under the Action column.
    • desc: the optional description automatically assigned by the Dragonfly App or assigned manually using the Edit button under the Action column.
  • 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