Dataset Management#

(introduced: version 2022.3)

⚠️ In this API and in the related ODK XForms specification, collections of Entities are referred to as Datasets. The term "Entity List" is used for this concept in the Central frontend UI, user documentation, and all other text intended for end users who are not developers.

A Dataset is a named collection of Entities that have the same properties.

A Dataset can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.

Related APIs:

Datasets#

GET /projects/{projectId}/datasets

The Dataset listing endpoint returns all published Datasets in a Project. If a Draft Form defines a new Dataset, that Dataset will not be included in this list until the Form is published.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

Response

HTTP Status: 200

Content Type: application/json

[
  {
    "name": "people",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "projectId": 1,
    "approvalRequired": true
  }
]

array

name

string

The name of the Dataset

Example: people

createdAt

string

ISO date format.

Example: 2018-01-19 23:58:03.395000+00:00

projectId

number

The numerical ID of the Project that the Dataset belongs to.

Example: 1

approvalRequired

boolean

Control whether a Submission should be approved before an Entity is created from it.

Example: true

HTTP Status: 200

Content Type: application/json; extended

[
  {
    "name": "people",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "projectId": 1,
    "approvalRequired": true,
    "lastEntity": "2018-04-18T03:04:51.695Z",
    "entities": 10,
    "conflicts": 2
  }
]

array

name

string

The name of the Dataset

Example: people

createdAt

string

ISO date format.

Example: 2018-01-19 23:58:03.395000+00:00

projectId

number

The numerical ID of the Project that the Dataset belongs to.

Example: 1

approvalRequired

boolean

Control whether a Submission should be approved before an Entity is created from it.

Example: true

lastEntity

string

ISO date format. The timestamp of the most recent entity, if any.

Example: 2018-04-18 03:04:51.695000+00:00

entities

number

The number of Entities in the Dataset.

Example: 10

conflicts

number

The number of Entities that have conflicts.

Example: 10.0

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Dataset Metadata#

GET /projects/{projectId}/datasets/{name}

Returns the metadata of a published Dataset including properties and forms that create and consume the Dataset.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

Response

HTTP Status: 200

Content Type: application/json

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": true,
  "sourceForms": [
    {
      "xmlFormId": "treeRegistration",
      "name": "Tree Registration"
    }
  ],
  "linkedForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "properties": [
    {
      "name": "the.age",
      "odataName": "the_age",
      "publishedAt": "2018-01-21T00:04:11.153Z",
      "forms": [
        {
          "xmlFormId": "simple",
          "name": "Simple"
        }
      ]
    }
  ]
}

array

linkedForms

array

Forms that consume data from the Dataset

expand

xmlFormId

string

The id of this form as given in its XForms XML definition

Example: simple

name

string

The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition.

Example: Simple

sourceForms

array

Forms that create Entities in the Dataset

expand

xmlFormId

string

The id of this form as given in its XForms XML definition

Example: simple

name

string

The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition.

Example: Simple

properties

array

All properties of the Dataset

expand

name

string

The name of the Property.

Example: the.age

odataName

string

The name of the property as it will appear in OData. OData property names can only contain alphanumeric characters and underscores.

Example: the_age

publishedAt

string

Publishing timestamp of the form that defined this property for the first time.

Example: 2018-01-21T00:04:11.153Z

forms

array

List of forms that create the property

expand

xmlFormId

string

The id of this form as given in its XForms XML definition

Example: simple

name

string

The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition.

Example: Simple

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Update Dataset Metadata#

PATCH /projects/{projectId}/datasets/{name}

You can only update approvalRequired using this endpoint. approvalRequired flag controls the Entity creation flow; if it is true then the Submission must be approved before an Entity can be created from it and if it is false then an Entity is created as soon as the Submission is received by the ODK Central.

By default approvalRequired is false for the Datasets created after v2023.3. Datasets created prior to that will have approvalRequired set to true.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

Request body

{
  "approvalRequired": true
}

object

approvalRequired

boolean

Control whether a Submission should be approved before an Entity is created from it.

Example: true

Response

HTTP Status: 200

Content Type: application/json

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": true,
  "sourceForms": [
    {
      "xmlFormId": "treeRegistration",
      "name": "Tree Registration"
    }
  ],
  "linkedForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "properties": [
    {
      "name": "the.age",
      "odataName": "the_age",
      "publishedAt": "2018-01-21T00:04:11.153Z",
      "forms": [
        {
          "xmlFormId": "simple",
          "name": "Simple"
        }
      ]
    }
  ]
}

array

linkedForms

array

Forms that consume data from the Dataset

expand

xmlFormId

string

The id of this form as given in its XForms XML definition

Example: simple

name

string

The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition.

Example: Simple

sourceForms

array

Forms that create Entities in the Dataset

expand

xmlFormId

string

The id of this form as given in its XForms XML definition

Example: simple

name

string

The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition.

Example: Simple

properties

array

All properties of the Dataset

expand

name

string

The name of the Property.

Example: the.age

odataName

string

The name of the property as it will appear in OData. OData property names can only contain alphanumeric characters and underscores.

Example: the_age

publishedAt

string

Publishing timestamp of the form that defined this property for the first time.

Example: 2018-01-21T00:04:11.153Z

forms

array

List of forms that create the property

expand

xmlFormId

string

The id of this form as given in its XForms XML definition

Example: simple

name

string

The friendly name of this form. It is given by the <title> in the XForms XML definition. Returns xmlFormId if there is no title in the form definition.

Example: Simple

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Download Dataset#

GET /projects/{projectId}/datasets/{name}/entities.csv

Datasets (collections of Entities) can be used as Attachments in other Forms, but they can also be downloaded directly as a CSV file.

The CSV format closely matches the OData Dataset Service format, with columns for system properties such as __id (the Entity UUID), __createdAt, __creatorName, etc., the Entity Label label, and the Dataset/Entity Properties themselves. If any Property for an given Entity is blank (e.g. it was not captured by that Form or was left blank), that field of the CSV is blank.

The $filter querystring parameter can be used to filter on system-level properties, similar to how filtering in the OData Dataset Service works.

This endpoint supports ETag header, which can be used to avoid downloading the same content more than once. When an API consumer calls this endpoint, the endpoint returns a value in the ETag header. If you pass that value in the If-None-Match header of a subsequent request, then if the Dataset has not been changed since the previous request, you will receive 304 Not Modified response; otherwise you'll get the new data.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

$filter

(query)

string

If provided, will filter responses to those matching the query. Only system-level Entity 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.

Example: __system/conflict eq \'hard\'

Response

HTTP Status: 200

Content Type: text/csv

__id,label,geometry,species,circumference_cm,__createdAt,__creatorId,__creatorName,__updates,__updatedAt,__version
2c1ee90b-dde8-434b-9985-2eefd8465339,666cm purpleheart,-29.281608 -67.624883 0 0,purpleheart,667,2023-05-31T19:49:28.902Z,22,Alice,1,2023-05-31T19:52:34.467Z,1
84ac3a03-9980-4098-93a5-b81fdc6ea749,555cm wallaba,18.921876 77.309451 0 0,wallaba,555,2023-05-31T19:49:20.152Z,22,Alice,0,,1

string

HTTP Status: 403

Content Type: text/csv

No Example

string

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No