Audit API

Audit Data End Points

GET /api/v1/audit
Synposis:get a list of services to retrieve audit data

Example response:

https://sg.smap.com.au/api/v1/audit

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
        {
                "id": 20361,
                "id_string": "s1554_20361",
                "title": "street light",
                "description": "street light",
                "url": "https://sg.smap.com.au/api/v1/audit/s1554_20361"
        }
]
Request Headers:
 
Status Codes:

Per Question Audit Data

GET /api/v1/audit/(survey ident)
Synposis:Get per question audit data from a survey. (survey ident) is the survey identifier which can be found in the list of services retrieved above. A GeoJson object is returned for each question and includes the time it took for the data collector to answer the question and the gps coordinates of where the question was answered. This data is only returned if “Timing Data” and “Record Location” were enabled for the survey.`

Example response:

https://sg.smap.com.au/api/v1/audit/s1554_20361

Data is returned as GeoJSON

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "type": "FeatureCollection",
  "features": [
        {
          "type": "Feature",
          "properties": {
                "question": "occupation",
                "value": "Builder",
                "time_spent": 8404,
                "prikey": 1,
                "user": "neil",
                "start": "2019-11-09 09:24:07.837+00",
                "end": "2019-11-09 09:24:37.296+00",
                "device": "863914040631978"
          },
          "geometry": {
                "type": "Point",
                "coordinates": [
                  153.0120208,
                  -27.4465832
                ]
          }
        },
        {
          "type": "Feature",
          "properties": {
                "question": "name",
                "value": "Bob",
                "time_spent": 11493,
                "prikey": 1,
                "user": "neil",
                "start": "2019-11-09 09:24:07.837+00",
                "end": "2019-11-09 09:24:37.296+00",
                "device": "863914040631978"
          },
          "geometry": {
                "type": "Point",
                "coordinates": [
                  153.0120208,
                  -27.4465832
                ]
          }
        },
        {
          "type": "Feature",
          "properties": {
                "question": "age",
                "value": "25",
                "time_spent": 6310,
                "prikey": 1,
                "user": "neil",
                "start": "2019-11-09 09:24:07.837+00",
                "end": "2019-11-09 09:24:37.296+00",
                "device": "863914040631978"
          },
          "geometry": {
                "type": "Point",
                "coordinates": [
                  153.0120208,
                  -27.4465832
                ]
          }
        }
  ]
}
Query Parameters:
 
  • start – The primary key to start from
  • limit – The number of records to return
  • sort – The column name to sort on
  • dirn – One of asc or desc, the sort direction
  • form – Form name of a sub form, to retrieve the audit data for the sub form
  • start_parkey – The parent key to start from. This is only useful if you are getting the audit data for a subform and you want to limit the data to only one or more submissions
  • parkey – Get audit data for a subform that corresponds to a single submission
  • hrk – Restrict records to a specific key
  • bad – One of yes, only or none. none is the default. If set to yes then audit data for records that have been marked bad (deleted) will be retrieved.
  • tz – Timezone
Request Headers:
 
Status Codes:

Viewing Per Question Audit Locations in a GIS

Because this service returns data in GeoJSON format it can easily be analyzed in a GIS. For example if you use QGIS the steps are:

  1. Start QGIS (Assumes version 3.6+)
  2. Select Layer, Add Layer, then Add Vector Layer
  3. Select Source type as HTTP(s)
  4. Select the encoding as UTF-8
  5. In the protocol section set the type to GeoJSON
  6. Paste the URL that returns your audit data into the URI field
  7. Select the basic authentication tab and enter your username and password
  8. Press the Add button
  9. Press Close. Your layer should have been added.

Once you have a vector layer in your GIS you can analyse by, for example, setting the size of the point proportional to the time taken to answer the question.

Audit data in QGIS

Audit data in QGIS

Raw Audit Log File

GET /api/v1/audit/(survey ident)
Synposis:Download the audit file that contains the original audit data before it is processed by the server

Example response:

The URL’s to the log file can be found by calling the data API with the links=yes query parameter.

The downloaded file is in CSV format.

Raw audit log file

Raw audit log file

If auditing of changes to questions is enabled then the raw audit log includes that information. In the above image the user initially set the name of the interviewee to Tom, they then went back and changed it to Bob. The GPS coordinates of each changed along with the times are recorded.

Audit Log Times

All times are in milli seconds since 1st January 1970 and are in the UTC timezone. Spreadsheets store date/time values as a numnber of days. Hence to convert to a spreadsheet date time in your time zone you can use the following formula:

=C2/(1000*3600*24) + DATE(1970,1,1) + (timezone difference)/24

C2 is the cell containing the time in the log CSV file
Divide this by (1000*3600*24) to get the number of days
Add the number of days value for 1st January 1970
Then add the timezone effect which is the number of hours difference from UTC divided by 24