Introduction
This API is based on version 1 of the Kobo API with some significant extensions.
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 the services that retrieve form data | 15.12+ | https://sg.smap.com.au/api/v1/data |
| /api/v1/data/{survey ident} | JSON | Get submitted data from a form. Replace {survey ident} with the survey ident which can be found in the list of services. | 15.12+ | https://sg.smap.com.au/api/v1/data/s193_18502 |
| /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/{survey ident} | CSV | Get submitted data from the specified form in a CSV file. | 15.12+ | https://sg.smap.com.au/api/v1/data.csv/s1313_16851 |
Parameters
| Parameter | Description | Version | Example |
|---|---|---|---|
| start | Retrieve data starting 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/s193_18568?form=q2 |
| start_parkey | Parent key to start from. Only useful when working with subform data. | 17.06+ | https://sg.smap.com.au/api/v1/data/s193_18568?form=q2&start_parkey=2 |
| parkey | Use to get a data in a subform that is part of a single record from a parent form. | 17.06+ | https://sg.smap.com.au/api/v1/data/s193_18568?form=q2&parkey=1 |
| 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/s193_18568?form=q2&bad=yes |
| filename | CSV only. If not set the default name is csv.data (forms.csv when retrieving the list of services) | 17.06+ | https://sg.smap.com.au/api/v1/data.csv/s193_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. 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. | 17.07+ | https://sg.smap.com.au/api/v1/data/s193_18569?audit=yes |
| merge_select_multiple | Set to "yes" to combine all the selected choices for a select multiple into a single column / Json text property. This parameter only applies to surveys created after version 18.03 which use the compressed format for storing select answers | 18.04+ | https://sg.smap.com.au/api/v1/data.csv/7019?form=11770&merge_select_multiple=yes |
| geojson | Set to "yes" for the data to be returned in geoJson format rather than the kobo api format. | 18.07+ | https://sg.smap.com.au/api/v1/data.csv/7019?form=11770&geojson=yes |
| links | If set to "true", when getting the data as JSON, then links to additional services that return alternate views of the data are included in the output. For example a link to get the data as a PDF or edit in a webform. | 18.07+ | https://sg.smap.com.au/api/v1/data/7019?links=true |
Single Record
This API returns data for a single record in a survey
| Service | Format | Description | Version | Example |
|---|---|---|---|---|
| /api/v1/data/{survey ident}/{instance key} | JSON | Get data for the specified instance | 15.12+ | https://sg.smap.com.au/api/v1/data/s1313_16851/uuid:dce538eb-ea90-44f1-b022-7481fad8fe47 |