Introduction


To use the examples you will need to enter a user id and password. However if you are already logged on to the server you should see your own data.

  • user: api
  • password: api

Data


This API gives you access to data that has been submitted to the server

Service Format Description Version Example
/api/v1/data JSON Get a list of services to retrieve form data 15.12+ https://sg.smap.com.au/api/v1/data
/api/v1/data/{key} JSON Get submitted data from a form. {key} is the survey id which can be found in the list of services. 15.12+ https://sg.smap.com.au/api/v1/data/1778
/api/v1/data.csv CSV Get a list of services to retrieve form data 15.12+ https://sg.smap.com.au/api/v1/data.csv
/api/v1/data.csv/{key} CSV Get submitted data from the specified form in a CSV file. 15.12+ https://sg.smap.com.au/api/v1/data.csv/1778

Parameters

Parameter Description Version Example
start Retrieve data from the specified primary key 15.12+ https://sg.smap.com.au/api/v1/data.csv?start=2
limit The number of records to retrieve 15.12+ https://sg.smap.com.au/api/v1/data.csv?start=2&limit=1
form Retrieve data for a subform. The available forms will be shown when you call /api/v1/data. This call will return the key for the parent form (parkey) so that its data can be combined with that of the main form 17.06+ https://sg.smap.com.au/api/v1/data/1778?form=2246
start_parkey Parent key to start from. Only useful when working with subform data. 17.06+ https://sg.smap.com.au/api/v1/data/1778?form=2246&start_parkey=200
bad Set to "yes" to include records marked as bad in the results. Set to "only" to only return records marked as bad. The default is "none" which will exclude records marked as bad. These include records that have been replaced by editing of the original data. 17.06+ https://sg.smap.com.au/api/v1/data/1778?bad=yes
filename CSV only. If not set the default is csv.data (forms.csv when retrieving the list of services) 17.06+ https://sg.smap.com.au/api/v1/data.csv/1778?filename=my_data.csv
audit Set to "yes" to include audit data. This data is the time in milliseconds that the user took to answer each question 17.07+ https://sg.smap.com.au/api/v1/data.csv/7019?audit=yes
And for the sub form
https://sg.smap.com.au/api/v1/data.csv/7019?form=11770&audit=yes

Resources


Resources are files used by forms. The following types of resources can be managed through the API:

  1. Media: For example a CSV file that contains choices or a photograph that is used to illustrate a choice in a select one question.

Media

Service Request Type / Format Description Version Example
/surveyKPI/upload/media GET JSON Get a list of the media available in the users current organisation. The response includes URLs to:
  • download the file
  • download a thumb nail
  • delete the file
17.10+ https://sg.smap.com.au/surveyKPI/upload/media
/surveyKPI/upload/media POST Upload a new file to the organisation. 17.10+ curl -u xxxx -i -X POST -H "Content-Type: multipart/form-data" -F "data=@phone.jpg" https://sg.smap.com.au/surveyKPI/upload/media

Parameters

Parameter Description Version Example
survey_id Retrieve a list of files or upload media only for the survey with specified id. You can also use the form field survey_id when posting media. 17.10+ https://sg.smap.com.au/surveyKPI/upload/media?survey_id=1778

Task List


Service Format Description Version Example
/api/v1/tasks JSON Get a list of tasks 16.03+ https://sg.smap.com.au/api/v1/tasks

Parameters

Filter Description Version Example
user The user id. (optional) 16.03+ https://sg.smap.com.au/api/v1/tasks/stats?x=scheduled&group=status&user=2

Task Statistics


This service is a Smap specific extension to the kobo api

Service Format Description Version Example
/api/v1/tasks/stats JSON Get statistics on tasks. In version 16.03 and below of the Smap server this only returns data on tasks that have been assigned to a user. 16.03+ https://sg.smap.com.au/api/v1/tasks/stats?x=scheduled&group=status

Filters

Filter Description Version Example
x X axis value. (Required) Alternatives:
  • scheduled
16.03+ https://sg.smap.com.au/api/v1/tasks/stats?x=scheduled&group=status
group Group results by this parameter. (Required) Alternatives:
  • status
16.03+ https://sg.smap.com.au/api/v1/tasks/stats?x=scheduled&group=status
user The user id. (optional) 16.03+ https://sg.smap.com.au/api/v1/tasks/stats?x=scheduled&group=status&user=2
period Group results by this time interval. (Optional) Alternatives:
  • day
  • month
  • year
  • week
16.03+ https://sg.smap.com.au/api/v1/tasks/stats?x=scheduled&group=status&period=month