Wearabouts API Reference

Transcription

1 Wearabouts API Reference Accuware Wearabouts exposes a RESTful web API that can be used to access and manipulate the state of set of resources registered with a site. The list of resources and the supported methods is summarized in the following table along with examples of usages with curl. An introduction to the Wearabouts API and an explanation about all the available resources can be found in this page. For examples of usage of the Wearabouts API with different program languages, please take a look at this page. Resource URI Available HTTPS Methods Sites Sites Levels Levels PUT, DELETE Floor plans POST Floor plans Devices Devices Devices - Status User Accounts Radio Fingerprints DELETE, PUT, DELETE, DELETE Radio Fingerprints DELETE /api/v1/sites/ Retrieves the list of sites registered with an user account

2 Available response representations: 200 OK application/json. JSON array of site descriptors. Query the list of sites registered with the account username : [crayon-5bc698e9be /] The result is an array [{ }, { }, ] of JSON objects: [crayon-5bc698e9be /] 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 dashboard. name: site name. access: access levels for each account registered /api/v1/sites/{siteid}/ Retrieves information about a specific site Available response representations: 200 OK application/json.

3 JSON representation of the site. Retrieve information about the site with siteid= 1001 : [crayon-5bc698e9be09b /] The result is a JSON object: [crayon-5bc698e9be0a /] 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 dashboard. name: site name. access: access levels for each account registered /api/v1/sites/{siteid}/levels/ Returns all the levels for the current site Available response representations: 200 OK application/json JSON array of levels associated to a site.

4 Returns a JSON representation of all the levels for site with siteid= 1001 : [crayon-5bc698e9be0a /] The result is an array [{ }, { }, ] of JSON objects: [crayon-5bc698e9be0ab /] /api/v1/sites/{siteid}/levels/{leve lid}/ Returns a specific level for the current site {levelid}: level identification string. Available response representations: 200 OK application/json. JSON representation of a level. Returns a JSON representation of the level 1 for site with siteid= 1001 : [crayon-5bc698e9be0b /] The result is an array [{ }, { }, ] of JSON objects: [crayon-5bc698e9be0b /]

5 PUT Create a new level for the site. {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 Create level with LevelID 11 in siteid 1001 : [crayon-5bc698e9be0bf /] The result is a JSON that describes the level just registered: [crayon-5bc698e9be0c /] DELETE Remove a level from the selected site {siteid}: site identification string {levelid}: level identification string Accepted representations: none No information is passed along with the request

6 Remove the level with levelid 11 from siteid 1001: [crayon-5bc698e9be0c /] The result is a confirmation message: [crayon-5bc698e9be0cd /] /api/v1/sites/{siteid}/floorplans/ Returns all the floor plans for the current site Available response representations: 200 OK application/json JSON array of floor plans Returns a JSON representation of all the levels for site with siteid= 1001 : [crayon-5bc698e9be0d /] The result is an array [{ }, { }, ] of JSON objects: [crayon-5bc698e9be0e /] JSON fields: desc:floor plan s description. levelid: level associated to the floor plan.

7 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 in the current site. {siteid}: site identification string Accepted representations: form-data Upload the floor plan of the Fourth Floor on the level 4 in the site with siteid= 1001 : [crayon-5bc698e9be0f /] At the end of the upload process, you should display: [crayon-5bc698e9be /] /api/v1/sites/{siteid}/floorplans/{ fpid}/ Returns a specific floor plan for the current site

8 {fpid}: floor plan identification string. Available response representations: 200 OK application/json JSON representation of a floor plan Returns a JSON representation of the floor plan aaa1111 for site with siteid= 1001 : [crayon-5bc698e9be /] The result is an array [{ }, { }, ] of JSON objects: [crayon-5bc698e9be /] 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}/- devices/?with=udo,status,config Retrieves several information about all the devices (Android,

9 ios and Smart Tags) registered within a site. Additional information can be obtained by varying query string parameters. HTTP Request Header: Content-Type: application/json HTTP Query String Parameter: udo: get back the user defined objects (see JSON below) status: get back the status objects (see JSON below) config: get back ONLY the list of devices with a devicespecific configuration (do not use it in conjunction with udo and/or status) Available response representations: 200: Array of Device List Object 400: Error Object 401: Not authenticated Retrieve the user defined objects and the status objects of all the devices registered within site 1001: [crayon-5bc698e9be /] The result is a JSON like this one: [crayon-5bc698e9be /] JSON fields: mac: deprecated use deviceid! deviceid:

10 Wearabouts App for Android: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a W. Wearabouts App for ios: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a X. Accuware Smart Tags: the MAC address is printed on a label on the back of the Accuware Smart Tag and begins with 54FB58. 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.

11 source: source location type: INDOORS/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. device: see above. deviceid: see above. fixed_at: last location fix. lat: latitude. lng: longitude. precision: an estimated radius of confidence where the device can be found. device_type: NZ002.2 for the Smart Tags. NWA1 for Android devices. NWA2 for ios devices. udo: name: device name assigned using the Accuware dashboard. desc: device description assigned using the Accuware dashboard. type: not relevant. current_server_time: server timestamp when the query was made. Timestamps: the timestamps are UTC Unix epoch timestamps in seconds. The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds that have elapsed since

12 January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: T00:00:00Z). You can find an Epoch & Unix Timestamp Conversion Tool at this link DELETE Remove ALL the devices associated with a specific site (this is not reversible) {siteid}: site identification string Accepted representations: none No information is passed along with the request Remove all the devices associates with siteid 1001: [crayon-5bc698e9be17e /] The result is a confirmation message: [crayon-5bc698e9be /] /api/v1/sites/{siteid}/devices/{dev iceid}/ Retrieves the user defined object about a specific device (Android, ios and Smart Tags) registered within a site

13 {deviceid}: Wearabouts App for Android: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a W. Wearabouts App for ios: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a X. Accuware Smart Tags: the MAC address is printed on a label on the back of the Accuware Smart Tag and begins with 54FB58. Available response representations: 200 OK application/json. JSON representation of the user defined object. Retrieve the user defined object of device registered within site 1001: [crayon-5bc698e9be19e /] The result is a JSON like this one: [crayon-5bc698e9be1a /] JSON fields: name: device name assigned using the Accuware dashboard desc: device description assigned using the Accuware dashboard

14 PUT Associates a device (represented by it s MAC address) with a site. This is currently a one-to-one relation, i.e. if the given device is already associated with another site, an error is given. {deviceid}: Wearabouts App for Android: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a W. Wearabouts App for ios: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a X. Accuware Smart Tags: the MAC address is printed on a label on the back of the Accuware Smart Tag and begins with 54FB58. Accepted representations: JSON with the user defined information (e.g. name, desc, type..) Associate device with siteid 1001: [crayon-5bc698e9be1b /] The result is a confirmation message: [crayon-5bc698e9be1c /]

15 DELETE Remove a devices associated with a specific site (this is not reversible) {siteid}: site identification string {deviceid}: Wearabouts App for Android: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a W. Wearabouts App for ios: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a X. Accuware Smart Tags: the MAC address is printed on a label on the back of the Accuware Smart Tag and begins with 54FB58 Accepted representations: none (no information is passed along with the request) Remove device associates with siteid 1001: [crayon-5bc698e9be1cc /] The result is a confirmation message: [crayon-5bc698e9be1d /] /api/v1/sites/{siteid}/-

16 devices/{deviceid}/status/ Retrieves status information about one device (Android, ios and Smart Tags) registered within a site {deviceid}: Wearabouts App for Android: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a W. Wearabouts App for ios: the pseudo MAC address is assigned by the Wearabouts App running on the device and contains a total of 12 characters beginning with a X. Accuware Smart Tags: the MAC address is printed on a label on the back of the Accuware Smart Tag and begins with 54FB58. Available response representations: 200 OK application/json JSON representation of the devices status Retrieve the status of a device with pmac W2F4IHV9R5RA registered within site 1001 [crayon-5bc698e9be1f /] The result is a JSON Object. If the status is available, it will be returned with the response:

17 [crayon-5bc698e9be20d /] JSON fields: current_server_time: server time stamp when the query was made. device status: battery: estimated battery percentage. Value with minus (-) means that the battery is charging. device_events: panic (only for Smart Tags): time stamp of the last button press. moving: time stamp of the last movement. pwr_up (only for Smart Tags): time stamp 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. its_status: not relevant. n1_status: not relevant. position: siteid: site identification. levelid: last level identification. source: source location type: INDOORS/N3 this location is computed by using the database of fingerprints available

18 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. device: the pmac of the device. deviceid: the pmac of the device. fixed_at: last location fix. lat: latitude. lng: longitude. precision: an estimated radius of confidence where the device can be found. device_type: NZ002.2 for the Smart Tags. NWA1 for Android devices. NWA2 for ios devices. Timestamps: the timestamps are UTC Unix epoch timestamps in seconds. 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: T00:00:00Z). You can find an Epoch & Unix Timestamp Conversion Tool at this link /api/v1/sites/{siteid}/accounts/

19 Retrieves all the user accounts associated to a site Available response representations: 200 OK application/json. JSON representation of user accounts associated to a site. Retrieves a JSON representation of all the user accounts associated with siteid= 1001 : [crayon-5bc698e9be /] The result is a JSON Object: [crayon-5bc698e9be24a /] JSON fields: username: username associated with the site. access: access levels for the username registered. api/v1/sites/{siteid}/levels/{level Id}/fingerprints/?format=KML Retrieve all the fingerprints from a specific level of a specific site.

20 {levelid}: level identification string. Query parameters: (optional) format: format=kml will download a file with the data. Available response representations: 200 OK application/json. JSON or KML array of fingerprints. Download the KML of all the fingerprints for site 1001 and level 0: [crayon-5bc698e9be /] The result is a KML file like the one below: [crayon-5bc698e9be25b /] Download the JSON of all the fingerprints for site 1001 and level 0: [crayon-5bc698e9be /] The result is a JSON array like the one below: [crayon-5bc698e9be /] JSON fields: id: identifier of the fingerprint. station: pmac of the device that has been used to

21 DELETE collect the fingerprint (during the fingerprinting process). type: not relevant. lat and lng: coordinates of the fingerprint (these are the coordinates of the station when the fingerprint has been collected by the Accuware Indoor App). entries: ap: 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. rss: receives signal strength. Delete ALL fingerprints from a specific level of a specific site. {levelid}: level identification string. Accepted representations: none. No information is passed along with the request. Delete ALL the fingerprint from site 1001 and level 0: [crayon-5bc698e9be /]

22 The result is a JSON object: [crayon-5bc698e9be27a /] api/v1/sites/{siteid}/levels/{level Id}/fingerprints/{fingerprintId}/ Retrieve a specific fingerprints from a specific level of a specific site. {levelid}: level identification string. {fingerprintid}: level identification string. Query parameters: (optional) format: format=kml will download a file with the data. Available response representations: 200 OK application/json. JSON or KML with the chosen fingerprint. Download the KML of the fingeprint with ID 0 collected inside site 1001 and level 0: [crayon-5bc698e9be /] The result is a KML file like the one below: [crayon-5bc698e9be /]

23 Download the JSON of the fingeprint with ID 0 collected inside site 1001 and level 0: [crayon-5bc698e9be28e /] The result is a JSON array like the one below: [crayon-5bc698e9be /] JSON fields: id: identifier of the fingerprint. station: pmac of the device that has been used to collect the fingerprint (during the fingerprinting process). type: not relevant. lat and lng: coordinates of the fingerprint (these are the coordinates of the station when the fingerprint has been collected by the Accuware Indoor App). entries: ap: 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. rss: receives signal strength. DELETE Delete a specific fingerprints from a specific level of a specific site.

24 {levelid}: level identification string. {fingerprintid}: fingerprint identifier. Accepted representations: none. No information is passed along with the request. Delete the fingerprint with fingerprintid 44 from site 1001 and level 0: [crayon-5bc698e9be29b /] The result is a JSON object: [crayon-5bc698e9be2a /]