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. An introduction to the API and an explanation about all the available resources can be found in this pageThe list of resources and the supported methods is summarized in the following tables along with examples of usages with cURL.

Synchronous Access

ResourceURIAvailable HTTPS Methods
Siteshttps://its.accuware.com/api/v1/sites/GET
Siteshttps://its.accuware.com/api/v1/sites/{siteId}/GET
BLE nodeshttps://its.accuware.com/api/v1/sites/{siteId}/nodes/GET
BLE nodeshttps://its.accuware.com/api/v1/sites/{siteId}/nodes/{mac}/GET, PUT, DELETE
BLE deviceshttps://its.accuware.com/api/v1/sites/{siteId}/stations/GET
BLE deviceshttps://its.accuware.com/api/v1/sites/{siteId}/stations/{mac}/GET, PUT, DELETE
User Accountshttps://its.accuware.com/api/v1/sites/{siteId}/accounts/GET
Levelshttps://its.accuware.com/api/v1/sites/{siteId}/levels/GET
Levelshttps://its.accuware.com/api/v1/sites/{siteId}/levels/{levelId}/GET, PUT, DELETE
Floor planshttps://its.accuware.com/api/v1/sites/{siteId}/floorplans/GET, POST
Floor planshttps://its.accuware.com/api/v1/sites/{siteId}/floorplans/{fpId}/GET
Geo-fenceshttps://its.accuware.com/api/v1/sites/{siteId}/levels/{levelId}/metadata/GET
Geo-fenceshttps://its.accuware.com/api/v1/sites/{siteId}/metadata/POST, DELETE
Geo-fenceshttps://its.accuware.com/api/v1/sites/{siteId}/metadata/{metadataId}/PUT, DELETE

Asynchronous Access (Callback Mechanism)

ResourceURIAvailable HTTPS Methods
Callback list Managementhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/GET, PUT, DELETE
Site levelhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/stations/GET
Site levelhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/stations/{mac}/PUT, DELETE
Node levelhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/GET
Node levelhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/GET
Node levelhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/stations/GET
Node levelhttps://its.accuware.com/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/stations/{mac}/PUT, DELETE

Synchronous Access

/api/v1/sites/

GET

Retrieves the list of sites registered with an user account

Available response representations:

  • 200 OK – application/json.
  • JSON array of site descriptors.

Example:

Query the list of sites registered with the account “username”:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • desc: expiration day of your site along with the type of account.
  • siteId: site identification.
  • address: used to point to the map on the area of interest in to the Accuware Bluetooth Beacon Tracker dashboard.
  • company: company name provided inside the Accuware Site Creation form.
  • name: site name.
  • access: access levels for each account registered.

/api/v1/sites/{siteId}/

GET

Retrieves information about a specific site

Resource-wide template parameters:

  • {siteId}: site identification string.

Available response representations:

  • 200 OK – application/json.
  • JSON representation of the site.

Example:

Retrieve information about the site with siteId=”1001″:

The result is a JSON object:

JSON fields:

  • desc: expiration day of your site along with the type of account.
  • siteId: site identification.
  • address: used to point to the map on the area of interest in to the Accuware Bluetooth Beacon Tracker dashboard.
  • company: company name provided inside the Accuware Site Creation form.
  • name: site name.
  • access: access levels for each account registered

/api/v1/sites/{siteId}/nodes/

GET

Retrieves the information of all the BLE nodes registered within a specific site.

Resource-wide template parameters:

  • {siteId}: site identification string

Available response representations:

  • 200 OK – application/json.
  • JSON array of BLE nodes descriptors.

Example:

Retrieve the list of BLE nodes registered with siteId=”1001″:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • mac: MAC address of the BLE node.
  • name: BLE node’s name.
  • desc: BLE node description (e.g. penthouse).
  • levelId: level identification.
  • lrrt (Last Report Relative Time): difference in seconds between the last report transmitted by the BLE node and the time the request was issued.
  • lrne (Last Report Number of Entries): number of unique stations transmitted by the BLE node in its last report.

/api/v1/sites/{siteId}/nodes/{mac}/

GET

Retrieves the information of a specific BLE node registered within a specific site.

Resource-wide template parameters:

  • {siteId}: site identification string
  • {mac}: the BLE node’s MAC address

Available response representations:

  • 200 OK – application/json.
  • JSON representation of the BLE node.

Example:

Retrieve information about the BLE node with MAC address 7072CF2148F0 from siteId=”1001″:

The result is a JSON object:

JSON fields:

  • name: BLE node’s name.
  • desc: BLE node description (e.g. penthouse node).
  • levelId: level identification.
  • lrrt (Last Report Relative Time): difference in seconds between the last report transmitted by the BLE node and the time the request was issued.
  • lrne (Last Report Number of Entries): number of unique stations detected and transmitted by the BLE node in its last report.

PUT

Register a BLE node within a selected site

Resource-wide template parameters:

  • {siteId}: site identification string
  • {mac}: the BLE node’s MAC address

Accepted representations:

  • application/x-www-form-urlencoded

BLE node information:

  • Required fields are lat and lng.
  • Optional fields are name, desc, and  levelId.
If the BLE node is new, it will be created. If the BLE node was already registered, its information will be overwritten.

Example:

Register a BLE node with MAC address 000011112222 in siteId=”1001″:

The result is a JSON object that describes the BLE node just registered:

DELETE

Remove a BLE node from the selected site

Resource-wide template parameters:

  • {siteId}: site identification string
  • {mac}: the BLE node’s MAC address

Accepted representations:

  • none.
  • No information is passed along with the request

Example:

Remove the BLE node with MAC address 000011112222 from siteId 1001:

The result is a confirmation message:

Querying for a BLE node just removed will return an HTTP 404 – Not found status code:

/api/v1/sites/{siteId}/stations/?loc=[yes|no]&type=[known|all]&lrrt=maxValue&rss=[yes|no]&ble=yes&areas=[yes|no]

GET

Retrieves the list of stations active (or previously active) within the selected site. Since the number of active stations might be large, it is possible to control the amount of returned data by setting the query parameters.

Resource-wide template parameters:

  • {siteId}: site identification string.

Query parameters:

  • loc [ yes | no ]: a flag that determines if the server will return location data in the response (default: loc=no).
  • type [ known | all ]: the type of stations to query (default: type=known).
  • lrrt (Last Report Relative Time): the maximum value for the lrrt field of the stations returned. The lrrt measures the seconds elapsed between the time the station was last seen active and the time the server was queried. (default: lrrt=600 which is equal to 10 minutes).
  • rss [ yes | no ]: a flag that determines if the server will return RSS data for each BLE node in the response (default: rss=no). Click here to get more information about the RSS.
  • ble [ yes | no ]: a flag that determines if the server will return additional data related to the BLE beacons in the response (default: ble=no).
  • areas [ yes | no ]:  a flag that determines if the server will return the list of geo-fences in which the device is located (default: areas=no). This parameter requires the loc parameter to be equal to yes.
  • The “Known stations” are always included in the returned response regardless the value of the lrrt parameter.
  • Keep in mind that it will not be possible to see the location and the RSS for the “Known stations” just added into the “known devices” list but never seen by the BLE nodes (even if loc=yes and rss=yes).

Available response representations:

  • 200 OK – application/json
  • JSON array of station descriptors

Example 1:

Retrieve the list of stations active within siteId=1001. If the query parameters are not specified, the default values will be used:

The result is a JSON object:

JSON fields:

  • mac: 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.
  • name: station’s name.
  • desc: station description.
  • 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.

 

Example 2:

Retrieve all the stations active in the last 15 seconds, and request location information and RSS in the response:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • mac: 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.
  • name: station’s name.
  • desc: station description.
  • loc: station location.
    • lat: latitude.
    • lng: longitude.
    • levelID: ID of the level.
    • prec: (not relevant).
  • 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.
  • areas: the list of geo-fences in which the device is located.
  • rss: signal strength measured by all the BLE nodes able to see the station. Click here to get more information about the RSS.
  • ble: additional data related to the BLE beacons
    • uuid: the UUID of the BLE beacon
    • major: the major of the BLE beacon
    • minor: the minor of the BLE beacon
    • power: the Measured Power advertised by the BLE beacon. This the dBm that is transmitted by the BLE beacon when it is at 1 meter of distance. This value is a constant that can be set using the App of the BLE beacon vendor.
    • battery: the battery level of the BLE beacon (at present it should not be taken into account because the value returned is always 255 or 0).
    • mv: the movement status of the BLE beacon:
      • 0 if it is not moving.
      • 1 if it is moving.
      • 2 if it does not have the movement sensor.

/api/v1/sites/{siteId}/stations/{mac}/?rss=[yes|no]&ble=[yes|no]&areas=[yes|no]

GET

Retrieves information about a specific station.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {mac}: the station’s pMAC address. The pseudo MAC address (pMAC) is a unique ID generated by the Accuware Bluetooth Beacon Tracker dashboard starting from the UUID, Major and Minor.

Query parameters:

  • rss [yes|no]: a flag that determines if the server will return RSS data for each BLE node in the response (default: rss=no).
  • ble [yes|no]: a flag that determines if the server will return additional data related to the BLE beacons in the response (default: ble=no).
  • areas [ yes | no ]:  a flag that determines if the server will return the list of geo-fences in which the device is located (default: areas=no).

Available response representations:

  • 200 OK – application/json
  • JSON representation of the station

Example:

Retrieve location and RSS information about the station with MAC address IAHXUH9AAZJ4 from siteId=”1001″:

The result is a JSON Object. If the location of the station is available, it will be returned with the response. Additionally, if the station has been previously registered in the list of known stations, its name and description will be returned in the representation as well:

JSON fields:

  • mac: 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.
  • name: station’s name.
  • desc: station description.
  • loc: station location.
    • lat: latitude.
    • lng: longitude.
    • levelID: ID of the level.
    • prec: (not relevant).
  • 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 BLE nodes able to see the station. Click here to get more information about the RSS.
  • ble: additional data related to the BLE beacons
    • uuid: the UUID of the BLE beacon
    • major: the major of the BLE beacon
    • minor: the minor of the BLE beacon
    • power: the Measured Power advertised by the BLE beacon. This the dBm that is transmitted by the BLE beacon when it is at 1 meter of distance. This value is a constant that can be set using the App of the BLE beacon vendor.
    • battery: the battery level of the BLE beacon (at present it should not be taken into account because the value returned is always 255 or 0).
    • mv: the movement status of the BLE beacon:
      • 0 if it is not moving.
      • 1 if it is moving.
      • 2 if it does not have the movement sensor.
  • areas: the list of geo-fences in which the device is located.

PUT

Registers a station in the list of known devices.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {mac}: the station’s pMAC address. The pseudo MAC address (pMAC) is a unique ID generated by the Accuware Bluetooth Beacon Tracker dashboard starting from the UUID, Major and Minor.

Accepted representations:

  • application/x-www-form-urlencoded

Station information:

  • The fields name and desc can contain empty values

Example:

Register a station with MAC address I072CF173037 in siteId=”1001″:

The result is a JSON that describes the station just registered:

DELETE

Removes a station from the list of known devices

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {mac}: the station’s pMAC address. The pseudo MAC address (pMAC) is a unique ID generated by the Accuware Bluetooth Beacon Tracker dashboard starting from the UUID, Major and Minor.

Accepted representations:

  • No information is passed along with the request.

Example:

Remove the station with MAC address I072CF173037 from siteId=”1001″

The result is a confirmation message:

/api/v1/sites/{siteId}/accounts/

GET

Retrieves all the user accounts associated to a site

Resource-wide template parameters:

  • {siteId}: site identification string.

Available response representations:

  • 200 OK – application/json.
  • JSON representation of user accounts associated to a site.

Example:

Retrieves a JSON representation of all the user accounts associated with siteId=”1001″:

The result is a JSON Object:

JSON fields:

  • username: username associated with the site.
  • access: access levels for the username registered.

/api/v1/sites/{siteId}/levels/

GET

Returns all the levels for the current site

Resource-wide template parameters:

  • {siteId}: site identification string.

Available response representations:

  • 200 OK – application/json
  • JSON array of levels associated to a site.

Example:

Returns a JSON representation of all the levels for site  with siteId=”1001″:

The result is an array [{…}, {…}, …] of JSON objects:

/api/v1/sites/{siteId}/levels/{levelId}/

GET

Returns a specific level for the current site

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {levelId}: level identification string.

Available response representations:

  • 200 OK – application/json.
  • JSON representation of a level.

Example:

Returns a JSON representation of the level “1” for site with siteId=”1001″:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • desc: level’s description.
  • levelID: level identification number.
  • name: level’s name.
  • alt: altitude – not used at present.

PUT

Create a new level for the site.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {levelId}: level identification string.

Accepted representations:

  • application/x-www-form-urlencoded

Level information:

  • The fields name, desc and alt can contain empty values.

Example:

Create level with LevelID 11 in siteId 1001″:

The result is a JSON that describes the level just registered:

DELETE

Remove a level from the selected site

Resource-wide template parameters:

  • {siteId}: site identification string
  • {levelId}: level identification string.

Accepted representations:

  • No information is passed along with the request

Example:

Remove the level with levelID 11 from siteId 1001:

The result is a confirmation message:

/api/v1/sites/{siteId}/floorplans/

GET

Returns all the floor plans for the current site

Resource-wide template parameters:

  • {siteId}: site identification string.

Available response representations:

  • 200 OK – application/json
  • JSON array of floor plans

Example:

Returns a JSON representation of all the floor plans for site with siteId=”1001″:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • desc:floor plan’s description.
  • levelID: level associated to the floor plan.
  • kmlAligned: link to the transformed KML file.
  • name: floor plan’s name.
  • kml: link to the original KML file.
  • access: private (not relevant)
  • fpID: floor plan identification string.

POST

Upload a floor plan within the current site.

Resource-wide template parameters:

  • {siteId}: site identification string.

Accepted representations:

  • form-data

Example:

Upload a floor planon the level 4 of site with siteId=”1001″:

At the end of the upload process, you should display:

/api/v1/sites/{siteId}/floorplans/{fpId}/

GET

Returns a specific floor plan for the current site

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {fpId}: floor plan identification string.

Available response representations:

  • 200 OK – application/json.
  • JSON representation of a floor plan

Example:

Returns a JSON representation of the floor plan “aaa1111″ for site with siteId=”1001”:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • desc:floor plan’s description.
  • levelID: level associated to the floor plan.
  • kmlAligned: link to the transformed KML file.
  • name: floor plan’s name.
  • kml: link to the original KML file
  • access: private (not relevant)
  • fpID: floor plan identification string.

/api/v1/sites/{siteId}/levels/{levelId}/metadata/

GET

Returns all the geo-fences for a specific level of a site

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {levelId}: level identification string.

Available response representations:

  • 200 OK – application/json.
  • JSON representation of one or multiple geo-fences.

Example:

Returns the JSON representation of the geo-fences related to level “1” of site “1001”:

The result is an array [{…}, {…}, …] of JSON objects:

JSON fields:

  • id: geo-fence identification number.
  • levelID: level identification number.
  • behavior: not relevant at present.
  • class:  not relevant at present.
  • type: not relevant at present.
  • vertex: array of coordinates that defines the area.
  • name: ge-fence name. If no name was specified when creating, will be set to “”.

/api/v1/sites/{siteId}/metadata/

POST

Create a new geo-fence for a specific level of a site.

Resource-wide template parameters:

  • {siteId}: site identification string.

Accepted representations:

  • application/json

Example:

Create a geo-fence on Level “1” of site “1001”:

The result is a JSON that describes the geo-fence just created:

JSON fields:

  • id: geo-fence identification number.
  • levelID: level identification number.
  • behavior: not relevant at present.
  • name: ge-fence name. If no name was specified when creating, will be set to “”.
  • class:  not relevant at present.
  • type: not relevant at present.
  • vertex: array of coordinates that defines the area.

DELETE

Delete all the geo-fences associated to a site.

Resource-wide template parameters:

  • {siteId}: site identification string.

Example:

Delete all the geo-fence inside site “1001”:

The result is a confirmation message:

/api/v1/sites/{siteId}/metadata/{metadataId}/

PUT

Update an existing geo-fence defined by its ID

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {metadataId}: geo-fence identification string.

Available response representations:

  • application/json.

Example:

Update an the geo-fence with ID “1” inside site “1001”:

The result is a JSON that describes the geo-fence just modified:

JSON fields:

  • id: geo-fence identification number.
  • levelID: level identification number.
  • behavior: not relevant at present.
  • class:  not relevant at present.
  • type: not relevant at present.
  • vertex: array of coordinates that defines the area.
  • name: ge-fence name. If no name was specified when creating, will be set to “”.

DELETE

Delete an existing geo-fence defined by its ID

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {metadataId}: geo-fence identification string.

Example:

Delete the geo-fence with ID “15” inside site “1001”:

The result is a confirmation message:

Asynchronous Access (Callback Mechanism)

/api/v1/sites/{siteId}/callbacks/

GET

Retrieve the callback URL.

Resource-wide template parameters:

  • {siteId}: site identification string.

Available response representations:

  • 200 OK – application/json.

Example:

Retrieve the callback URL registered with siteId=”1001″:

The result is a JSON Object:

PUT

Register a callback URL.

Resource-wide template parameters:

  • {siteId}: site identification string.

Accepted representations:

  • application/x-www-form-urlencoded.

The callback URL will be passed in the callback field.

Example:

Register “http://my.domain.com/ItsPost.php” as callback URL for siteId=”1001″.

DELETE

Remove the callback URL and disable the notification system

Resource-wide template parameters:

  • {siteId}: site identification string.

Accepted representations:

  • No information is passed along with the request.

Example:

Disable the callback system for siteId=1001:

/api/v1/sites/{siteId}/callbacks/stations/

GET

Retrieve the pseudo MAC addresses (or pMAC) of the stations registered in the callback list of a site.

Resource-wide template parameters:

  • {siteId}: site identification string

Available response representations:

  • 200 OK – application/json

Example:

Retrieve the pseudo MAC addresses of all the stations registered in the callback list of the  site 1001:

The result is a JSON Object:

/api/v1/sites/{siteId}/callbacks/stations/{mac}/

PUT

Register a station to the callbacks list of a site.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {mac}: the station’s pseudo MAC addresses.

Accepted representations:

  • application/x-www-form-urlencoded

The callback URL will be passed in the callback field

Example:

Register the station with MAC address I4:20:0C:27:E4:63 in the callback list of the site 1001:

The result is a JSON Object:

DELETE

Delete a station registered in a callback list of a site.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {mac}: the station’s pseudo MAC addresses.

Accepted representations:

  • No information is passed along with the request.

Example:

Delete the station with pseudo MAC addresses I4:20:0C:27:E4:63 from the callback list of the site 1001:

/api/v1/sites/{siteId}/callbacks/nodes/

GET

Retrieve the MAC addresses of the stations registered in the callback list of each BLE node.

Resource-wide template parameters:

  • {siteId}: site identification string

Available response representations:

  • 200 OK – application/json

Example:

Retrieve the MAC addresses of all the stations registered in the callback list of each BLE node of site 1001:

The result is a JSON Object:

/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/

GET

Retrieve the pseudo MAC addresses of the stations registered in the callback list of a specific BLE node.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {node_mac}: BLE node’s MAC address.

Available response representations:

  • 200 OK – application/json.

Example:

Retrieve the pseudo MAC addresses of the stations registered in the callback list of the BLE node with MAC address 70:72:CF:21:EB:13 in the site 1001:

The result is a JSON Object:

/api/v1/sites/{siteId}/callbacks/nodes/{node_mac}/stations/{mac}/

PUT

Register a station to the callbacks list of a specific BLE node.

Resource-wide template parameters:

  • {siteId}: site identification string.
  • {node_mac}: BLE node’s MAC address.
  • {mac}: the station’s pseudo MAC address.

Accepted representations:

  • No information is passed along with the request

Example:

Register the station with pseudo MAC address I4:20:0C:27:E4:63 in the callback list of the BLE node with MAC address 18:87:96:B7:34:D1 in the site 1001:

DELETE

Delete a station registered in a callback list of a specific BLE node.

Resource-wide template parameters:

  • {siteId}: site identification string
  • {node_mac}: node’s MAC address
  • {mac}: the station’s pseudo MAC address

Accepted representations:

  • No information is passed along with the request.

Example:

Delete the station with pseudo MAC address I4:20:0C:27:E4:63 from the callback list of the BLE node with MAC address 18:87:96:B7:34:D1 in the siteId=1001: