Datasets – Alida Help Center

Datasets are the basic container for a survey and its responses. Datasets endpoints return data about the structure of a survey.

Note:

Datasets resources currently do not return forum data.
The Batch Data Extract and Dataset V2 endpoints should be used instead of the Datasets endpoints. Batch Data Extract endpoints return a complete export of activity and profile variable data and the Datasets V2 endpoints allows you to select specific activities or profile variables. For more information, see Batch Data Extract endpoints and Dataset V2 endpoints.

Note:

Use the appropriate regional endpoint to ensure that you comply with your organization's privacy policy, and applicable laws and regulations. For details about the available regional endpoints, and how to identify your organization's region, see Shared responsibility.

Before you begin using datasets resources, you should familiarize yourself with the following terms as they relate to this API:

Columns

A column defines a place to store a single value. Think of a column as a variable. A column declares the type of data that it accepts. For example, a column might only store numbers, or strings, or dates. For a survey, a column is usually the place to store a value for a specific question, or another piece of data.

Columns example

A survey contains the following Single Choice question:

What is your gender?
Male Female

In your dataset, this column (question) would look something like this:


{
    "id": <GUID for the column>,
    "name": "Gender",
    "dataType": "string",
    "links": [],
    "href": "api.{region}.alida.com/v1/applications/{communityApiKeyName}/datasets/{datasetId}/columns/{columnId}"
}

Record

A record is a collection of values for the columns in a dataset. For a survey, a record corresponds to all of the data produced when a participant takes the entire survey one time.

Example record

			
{
    "id": <GUID of record>,
    "dataTimestamp": <date-time (UTC) of when this record was created>,
    "values": [
        {
          "columnId": <GUID of column>,
          "value": <value of column>
        },
        {
          "columnId": <GUID of column>,
          "value": <value of column>
        },
		      {
          "columnId": <GUID of column>,
          "value": <value of column>
        },
        {
          "columnId": <GUID of column>,
          "value": <value of column>
        }
      ]
}

Data type

A data type defines what kinds of values may be assigned to a column. All datasets support a standard set of primitive data types, such as number, string, and date. A dataset may also define custom data types, which precisely define the allowed values for particular columns.

For more information, see Data types.

Concepts

A concept is metadata about the structure of a survey. Concept metadata is hierarchical. There is a root concept for the survey itself, and a child concept for each question in the survey. Grid question types (such as Multiple Choice Grids), have child concepts for each row in the grid.

The following image identifies the concepts in a dataset.

Survey concept example

The following snippet shows the parent concept for an activity named Satisfaction. Looking at the data, you can determine the activity is a survey that was created on January 1, 2017.


... 
{
    "id": <GUID of concept&gt>,
    "name": "Satisfaction",
    "parentId": null,
        "tags": [
           "survey"
        ],
        "column": null,
        "orderInParent": 0,
        "extraData": {
           "Id": <GUID of extra data>;,
           "State": "Alive",
           "Name": "Satisfaction Survey",
           "CreatedAt": "2017-01-01T00:00:00Z",
           "LastUpdatedAt": "2017-12-02T04:17:07Z",
           "Version": 3
},
...

Multiple Choice Grid question concept example

The following snippet shows the concept metadata for a Multiple Choice Grid question.

From looking at the concept, you can see the:

Question name (Rate Value)
Question type (multichoicegrid)
Column labels (Not satisfied, Satisfied, Very satisfied)

      
...
{
    "id": <GUID of concept>,
    "name": "Rate Value",
    "parentId": <GUID of parent concept>,
    "tags": [
        "multichoicegrid",
        "grid"
    ],
    "column": null,
    "orderInParent": 1,
    "extraData": {
        "Id": <GUID of extra data>,
        "State": "Alive",
        "Name": "Multiple Choice Grid",
        "Text": <question text>,
        "GridType": "MultiChoiceGrid",
        "ExtensionType": "NotDefined",
        "Choices": [
            {
                "Id": <GUID of column>,
                "State": "Alive",
                "Text": "Not satisfied"
            },
            {
                "Id": <GUID of column>,
                "State": "Alive",
                "Text": "Satisfied"
            },
            {
                "Id": <GUID of column>,
                "State": "Alive",
                "Text": "Very satisfied"
            }
        ]
    },
        "datasetId": <GUID of dataset>,
        "links": [
            {
               "rel": "children",
               "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/datasets/{GUID of dataset}/concepts?{GUID of parent}"
},
...