OData Endpoints¶

OData is a standard for sharing data and its schema between web services. It allows for interoperability with tools like Excel, Power BI or Tableau. If you want to use your data in a service that does not support the OData standard but does support JSON data sources, you can use the data document directly.

ODK Central implements the 4.0 Minimal Conformance level of the specification. Our goal is to enable data analysis and reporting through powerful third-party tools, sending them the data over OData, rather than attempt to create our own analysis tools. Our implementation primarily targets Microsoft Power BI and Tableau, two tools with reasonably robust free offerings that provide versatile analysis and visualization of data.

While OData itself supports data of any sort of structure, Power BI and Tableau both think in terms of relational tables. Our current solution for representing ODK's repeat structures in OData is to treat every repeat in the Form definition as its own relational table, and we compute stable join IDs to relate the tables together.

In general, the OData standard protocol consists of three API endpoints:

The Service Document describes the available resources in the service. We provide one of these for every Form in the system. As of version 2023.2, we also provide one for every Dataset.
The Metadata Document defines the data schema using an XML-based standard. It is linked in every OData response.
The data documents, linked from the Service Document, are a simple JSON representation of the Submission or Entity data, conforming to the schema we describe in our Metadata Document.

OData Form Service¶

ODK Central presents one OData service for every Form it knows about. To access the OData service, add .svc to the resource URL for the given Form.

Data Document¶

GET /v1/projects/{projectId}/forms/{xmlFormId}.svc/{table}

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. 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
Submitter Actor ID	`submitterId`	`__system/submitterId`
Submission Timestamp	`createdAt`	`__system/submissionDate`
Submission Update Timestamp	`updatedAt`	`__system/updatedAt`
Review State	`reviewState`	`__system/reviewState`

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 gt 2020-01-31T23:59:59.999Z 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 le 2020-01-31T23:59:59.999Z 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 %24expand=* 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.

Data Download Path¶

GET /#/dl/projects{projectId}/forms/{xmlFormId}/submissions/{instanceId}/attachments/{filename}

(introduced: version 1.2)

This route is a web browser oriented endpoint intended for user-interactive usage only. It's not part of the Central API, but is documented here as it can be useful.

If you are writing or configuring an OData client and have submission media files to deal with, you can run into authentication problems directly fetching or linking the media file URLs that are provided in the OData feed. This can be due to several reasons: if the user is not logged into the Central administration site (and thus has no valid cookie), if the request comes from a foreign origin (and thus cookies are not sent by the browser), and more.

To help manage this, the frontend provides a /#/dl path that allows file download. Just take a normal attachment download path and replace the /v1 near the beginning of the path with /#/dl, and the user will be taken to a page managed by the Central administration website that will ensure the user is logged in, and offer the file as a download.

Because this /#/dl path returns a web page that causes a file download rather than directly returning the media file in question, it cannot be used to directly embed or retrieve these files, for example in a <img> tag.

OData Dataset Service¶

ODK Central presents one OData service for every Dataset as a way to get an OData feed of Entities. To access the OData service, add .svc to the resource URL for the given Dataset.

Service Document¶

GET /v1/projects/{projectId}/datasets/{name}.svc

The Service Document provides a link to the main source of information in this OData service: the list of Entities in this Dataset, as well as the Metadata Document describing the schema of this information.

This document is available only in JSON format.

Data Document¶

GET /v1/projects/{projectId}/datasets/{name}.svc/Entities

A data document is the straightforward JSON representation of all the Entities in a Dataset.

The $filter querystring parameter can be used to filter certain data fields in the system-level schema, but not the Dataset properties. 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.

The fields you can query against are as follows:

Entity Metadata	OData Field Name
Entity Creator Actor ID	`__system/creatorId`
Entity Timestamp	`__system/createdAt`
Entity Update Timestamp	`__system/updatedAt`
Entity Conflict	`__system/conflict`

Note that createdAt and updatedAt are time components. This means that any comparisons you make need to account for the full time of the entity. It might seem like $filter=__system/createdAt le 2020-01-31 would return all results on or before 31 Jan 2020, but in fact only entities 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/createdAt le 2020-01-31T23:59:59.999Z or $filter=__system/createdAt 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.

The $select query parameter will return just the fields you specify and is supported on __id, __system, __system/creatorId, __system/createdAt and __system/updatedAt, as well as on user defined properties.

The $orderby query parameter will return Entities sorted by different fields, which come from the same list used by $filter, as 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/creatorId ASC, __system/conflict DESC.

As the vast majority of clients only support the JSON OData format, that is the only format ODK Central offers.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No

OData Endpoints¶

OData Form Service¶

Service Document¶

Metadata Document¶

Data Document¶

Data Download Path¶

OData Dataset Service¶

Service Document¶

Metadata Document¶

Data Document¶

Draft Testing¶

Service Document¶

Metadata Document¶

Data Document¶

projectId	`number` The numeric ID of the Project Example: `7`
xmlFormId	`string` The `xmlFormId` of the `Form` whose OData service you wish to access. Example: `simple`
instanceId	`string` The `instanceId` of the Submission being referenced. Example: `uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44`
filename	`string` The name of the file to be retrieved. Example: `file1.jpg`