Data Document
The data documents are JSON representations of each table of Submission data. They follow the corresponding specification, but apart from the representation of geospatial data as GeoJSON rather than the ODK proprietary format, the output here should not be surprising. If you are looking for JSON output of Submission data, this is the best place to look.
The $top and $skip querystring parameters, specified by OData, apply limit and offset operations to the data, respectively. The $count parameter, also an OData standard, will annotate the response data with the total row count, regardless of the scoping requested by $top and $skip. If $top parameter is provided in the request then the response will include @odata.nextLink that you can use as is to fetch the next set of data. As of ODK Central v2023.4, @odata.nextLink contains a $skiptoken (an opaque cursor), which allows you to page through Submissions with a consistent offset, even while new Submissions are being created.
While paging is possible through these parameters, it will not greatly improve the performance of exporting data. ODK Central prefers to bulk-export all of its data at once if possible.
As of ODK Central v1.1, the $filter querystring parameter is partially supported. In OData, you can use $filter to filter by certain data fields in the schema. The operators lt, le, eq, ne, ge, gt, not, and, and or are supported. The built-in functions now, year, month, day, hour, minute, second are supported. These supported elements may be combined in any way, but all other $filter features will cause an error.
The fields you can query against are as follows:
| Submission Metadata | REST API Name | OData Field Name |
|---|---|---|
| Submission ID | instanceId | __id |
| Submitter Actor ID | submitterId | __system/submitterId |
| Submission Timestamp | createdAt | __system/submissionDate |
| Submission Update Timestamp | updatedAt | __system/updatedAt |
| Review State | reviewState | __system/reviewState |
| Submission Delete Timestamp (v2024.3) | deletedAt | __system/deletedAt |
You can use $root expression to filter subtables (repeats) by Submission Metadata, you'll have to prefix above fields by $root/Submissions/ in the filter criteria. For example, to filter a repeat table by Submission Timestamp you can pass $filter=$root/Submissions/__system/submissionDate ge 2020-02-01T00:00:00.000Z in the query parameter.
Note that the submissionDate has a time component. This means that any comparisons you make need to account for the full time of the submission. It might seem like $filter=__system/submissionDate le 2020-01-31 would return all results on or before 31 Jan 2020, but in fact only submissions made before midnight of that day would be accepted. To include all of the month of January, you need to filter by either $filter=__system/submissionDate lt 2020-02-01T00:00:00.000Z or $filter=__system/submissionDate lt 2020-02-01. Remember also that you can query by a specific timezone.
Please see the OData documentation on $filter operations and functions for more information.
As of ODK Central v1.2, you can use $expand=* to expand all repeat repetitions. This is helpful if you'd rather get one nested JSON data payload of all hierarchical data, rather than retrieve each of repeat as a separate flat table with references.
The nonstandard $wkt querystring parameter may be set to true to request that geospatial data is returned as a Well-Known Text (WKT) string rather than a GeoJSON structure. This exists primarily to support Tableau, which cannot yet read GeoJSON, but you may find it useful as well depending on your mapping software. Please note that both GeoJSON and WKT follow a (lon, lat, alt) coördinate ordering rather than the ODK-proprietary lat lon alt. This is so that the values map neatly to (x, y, z). GPS accuracy information is not a part of either standards specification, and so is presently omitted from OData output entirely. GeoJSON support may come in a future version.
As of ODK Central v2022.3, the $select query parameter is supported with some limitations:
-
$select and $expand can't be used together.
-
Child properties of repeats can't be requested using $select
As of ODK Central v2024.1, the $orderby query parameter is now supported, and can sort on the same fields as $filter, noted above. The order can be specified as ASC (ascending) or DESC (descending), which are case-insensitive. Multiple sort expressions can be used together, separated by commas, e.g. $orderby=__system/submitterId ASC, __system/reviewState DESC.
As the vast majority of clients only support the JSON OData format, that is the only format ODK Central offers.
Path parameters
The numeric ID of the Project
The xmlFormId of the Form whose OData service you wish to access.
The name of the table to be returned. These names can be found in the output of the Service Document.
Query parameters
If supplied, the first $skip rows will be omitted from the results.
If supplied, only up to $top rows will be returned in the results.
If set to true, an @odata.count property will be added to the result indicating the total number of rows, ignoring the above paging parameters.
If set to true, geospatial data will be returned as Well-Known Text (WKT) strings rather than GeoJSON structures.
If provided, will filter responses to those matching the query. Only certain fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second.
If provided, will sort responses according to specified order expression. Only the same fields as $filter above can be used to sort. Multiple expressions can be used together.
Repetitions, which should get expanded. Currently, only * is implemented, which expands all repetitions.
If provided, will return only the selected fields.
Opaque cursor from @odata.nextLink used for paging.
Response
OK
Example response
{
"@odata.context": "https://your.odk.server/v1/projects/7/forms/simple.svc/$metadata#Submissions",
"value": [
{
"__id": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
"age": 25,
"meta": {
"instanceID": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44"
},
"name": "Bob"
},
{
"__id": "uuid:297000fd-8eb2-4232-8863-d25f82521b87",
"age": 30,
"meta": {
"instanceID": "uuid:297000fd-8eb2-4232-8863-d25f82521b87"
},
"name": "Alice"
}
]
}