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:

• Implicit creation of Datasets via Forms

• Link a Dataset to a Form Attachment

• Get a Form's Related Datasets

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

Example

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

Schema

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

Example

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

Schema

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.0

HTTP Status: 403

Content Type: application/json

Example

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

Schema

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

Example

{
  "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"
        }
      ]
    }
  ]
}

Schema

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

Example

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

Schema

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

Example

{
  "approvalRequired": true
}

Schema

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

Example

{
  "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"
        }
      ]
    }
  ]
}

Schema

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

Example

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

Schema

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.

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

Response

HTTP Status: 200

Content Type: text/csv

Example

__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

Schema

string

HTTP Status: 403

Content Type: text/csv

Example

No Example

Schema

string

HTTP Status: 403

Content Type: application/json

Example

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

Schema

object code string message string