Data

Introduction 

This API is based on the Kobo Version 1 API however it has had some significant extensions. To use the examples you will need to enter a user id and password. If you are already logged on to the server then you should see your own data otherwise you can access demo data using:

user: api
password: api

Data End Points in JSON 

GET /api/v1/data

GET /api/v2/data

Synopsis:: Returns available end points.

Example response:

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

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

[
  {
  "id": 1778,
  "id_string": "s193_1778",
        "title": "Basic Form",
        "description": "Basic Form",
        "url": "https://sg.smap.com.au/api/v1/data/s193_1778?links=true"
        },
        {
        "id": 18569,
        "id_string": "s193_18569",
        "title": "Form with audit data",
        "description": "Form with audit data",
        "url": "https://sg.smap.com.au/api/v1/data/s193_18569?links=true"
        },
        {
        "id": 18568,
        "id_string": "s193_18568",
        "title": "Form with repeats",
        "description": "Form with repeats",
        "url": "https://sg.smap.com.au/api/v1/data/s193_18568?links=true",
        "subforms": {
        "q2": "https://sg.smap.com.au/api/v1/data/s193_18568?form=q2"
        }
        },
        {
        "id": 18502,
        "id_string": "s193_18502",
        "title": "القراءة بحسب الباركود",
        "description": "القراءة بحسب الباركود",
        "url": "https://sg.smap.com.au/api/v1/data/s193_18502?links=true"
        }
]

Request Headers:

Authorization -- basic

Status Codes:

200 OK -- no error

Data End Points in CSV 

GET /api/v1/data.csv

Synopsis:: Returns available end points in a CSV file.

Example response:

https://sg.smap.com.au/api/v1/data.csv

Query Parameters:

filename -- The name of the file. Default is forms.csv.

Survey Data in JSON 

GET /api/v1/data/(survey ident)

GET /api/v2/data/(survey ident)

Synopsis:: Returns data for the specified survey. The example shows

Example response:

https://sg.smap.com.au/api/v1/data/s193_18568?links=true

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

[
        {
        "prikey": "1",
        "Key": "",
        "Survey Duration": "27.7929999999999993",
        "User": "api",
        "Upload Time": "2019-09-01 06:26:18+00",
        "Survey Name": "Form with repeats",
        "_scheduled_start": "",
        "Version": "2",
        "Complete": "t",
        "Survey Notes": "",
        "Location Trigger": "",
        "Instance Name": "",
        "start": "2019-09-01 06:25:50+00",
        "end": "2019-09-01 06:26:17+00",
        "deviceid": "deviceid not found",
        "uuid": "uuid:7d2b9a69-0cad-4e0c-8dd5-cb3e3c14eb14",
        "name": "Tom",
        "links": {
        "data": "https://sg.smap.com.au/api/v1/data/s193_18568/uuid:7d2b9a69-0cad-4e0c-8dd5-cb3e3c14eb14",
        "pdf": "https://sg.smap.com.au/surveyKPI/pdf/s193_18568?instance=uuid:7d2b9a69-0cad-4e0c-8dd5-cb3e3c14eb14&tz=UTC",
        "webform": "https://sg.smap.com.au/webForm/s193_18568?datakey=instanceid&datakeyvalue=uuid:7d2b9a69-0cad-4e0c-8dd5-cb3e3c14eb14",
        "audit_log": "https://sg.smap.com.au/api/v1/audit/log/s193_18568/uuid:7d2b9a69-0cad-4e0c-8dd5-cb3e3c14eb14"
        }
        },
        {
        "prikey": "2",
        "Key": "",
        "Survey Duration": "15.5079999999999991",
        "User": "api",
        "Upload Time": "2019-09-01 06:26:33+00",
        "Survey Name": "Form with repeats",
        "_scheduled_start": "",
        "Version": "2",
        "Complete": "t",
        "Survey Notes": "",
        "Location Trigger": "",
        "Instance Name": "",
        "start": "2019-09-01 06:26:17+00",
        "end": "2019-09-01 06:26:33+00",
        "deviceid": "deviceid not found",
        "uuid": "uuid:8bf658ad-33ab-4cfe-97c9-fad91406fb86",
        "name": "Sally",
        "links": {
        "data": "https://sg.smap.com.au/api/v1/data/s193_18568/uuid:8bf658ad-33ab-4cfe-97c9-fad91406fb86",
        "pdf": "https://sg.smap.com.au/surveyKPI/pdf/s193_18568?instance=uuid:8bf658ad-33ab-4cfe-97c9-fad91406fb86&tz=UTC",
        "webform": "https://sg.smap.com.au/webForm/s193_18568?datakey=instanceid&datakeyvalue=uuid:8bf658ad-33ab-4cfe-97c9-fad91406fb86",
        "audit_log": "https://sg.smap.com.au/api/v1/audit/log/s193_18568/uuid:8bf658ad-33ab-4cfe-97c9-fad91406fb86"
        }
        }
]

Query Parameters:

links -- Return URL links to other API calls on the data
start -- Retrieve data starting from the specified key
limit -- The number of records to retrieve
form -- Retrieve data for a sub-form. The available subforms are shown in the returned data from the /api/v1/data call. This call will return the key for the parent form in the "parkey" attribute so that its data can be combined with that of the main form.
start_parkey -- Parent key to start from. Only useful when working with subform data.
parkey -- Parent key. return records in the subform that belong to the specified parent.
bad -- One of yes return deleted records, only Only return deleted records, none do not return deleted (default)
audit -- set to yes to return audit data. This data is the time in milliseconds that the user took to answer each question. You can also specify in the settings for the form that the GPS coordinates where each question was answered should be included. There is a thid level of audit where every change made to a question during the course of an interview is recorded. This information is available through the separate audit API.
meta -- set to yes to return meta data and preloads including prikey, instanceid, user, upload time. Set to no to not return this data. The default is yes
merge_select_multiple -- Set to yes to combine all the selected choices for a select multiple into a single column / Json text property.
sort -- question name to sort on
dirn -- Sort direction, either asc or desc
key -- The key to filter by. A key will need to have been specified for this survey.
tz -- The timezone for example Australia/Brisbane. All date time and date answers will be returned in this time zone.
geom_question -- When using geojson=yes, and if you have more than one geometry in the main form, then you can specify the name of the geometry question to use as the GeoJson geometry here.
filter -- Advanced filter. For example &filter=${q1} > 10

Request Headers:

Authorization -- basic

Status Codes:

200 OK -- no error
401 Unauthorized -- not authorised

Survey Data in CSV 

GET /api/v1/data.csv/(survey ident)

Synopsis:: Returns data for the specified survey. The example shows

Example response:

https://sg.smap.com.au/api/v1/data.csv/s193_18568?links=true

All parameters in Survey Data in JSON can be used.

Query Parameters:

filename -- The name of the file. Default is data.csv.

Single Record 

GET /api/v1/data/(survey ident)/(instance key)

GET /api/v2/data/(survey ident)/(instance key)

Synopsis:: Get data for the specified instance. The instance key can be found in the Survey Data in JSON API call. Two output formats are available. Probably the more useful format is the hierarchy view (Smap Server 21.05). In this format repeats are included inside their parent records. Specify the hierarchy parameter in order to get this format. In the alternate default format the values from repeating records are separated out from their parent.

Example response:

https://sg.smap.com.au/api/v1/data/s1313_16851/uuid:dce538eb-ea90-44f1-b022-7481fad8fe47

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

{
  "values": {
    "country": "Mozambique",
    "instanceid": "uuid:debf717e-99a0-4b87-994f-b90ef2339317"
  },
  "repeats": {
    "cities": [
          {
        "values": {
        "city": "Maputo"
        }
      },
      {
        "values": {
        "city": "Massinga"
        }
      }
    ]
  }
}

Example response with hierarchy parameter set:

https://sg.smap.com.au/api/v1/data/s1313_16851/uuid:dce538eb-ea90-44f1-b022-7481fad8fe47?hierarchy=yes

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

{
  "cities": [
    {
    "city": "Maputo"
    },
    {
    "city": "Massinga"
    }
  ],
  "instanceid": "uuid:debf717e-99a0-4b87-994f-b90ef2339317",
  "country": "Mozambique"
}

Query Parameters:

meta -- set to yes to return meta data and preloads including prikey, instanceid, user, upload time. The default is no
tz -- The timezone for example Australia/Brisbane. All date time and date answers will be returned in this time zone.
hierarchy -- set to yes to see the response as a hierarchy of json objects (Requires Smap Server 21.05)

Request Headers:

Authorization -- basic

Status Codes:

200 OK -- no error
401 Unauthorized -- not authorised
404 Not Found -- not found

Data

Introduction

Data End Points in JSON

Data End Points in CSV

Survey Data in JSON

Survey Data in CSV

Single Record

Introduction 

Data End Points in JSON 

Data End Points in CSV 

Survey Data in JSON 

Survey Data in CSV 

Single Record 