DataView¶

This endpoint provides access to filtered data from submitted XForm data.

Where:

pk - is the dataview id

Definition¶

xform - source XForm. It cannot be changed after creation.
project - project containing the DataView. It may differ from the source XForm’s project.
columns - Json list of columns to be included in the data
query - Json list of dicts with filter information.

Each dict contains:

column - The column the filter will be applied to.
filter - The filter that will be used.
value - The value to filter with.
condition - (optional) This indicates which logical conjuction to use. Either AND/OR Default is AND

Current Supported Filters

Filter	Description
=	Equal to
>	Greater than
<	Less than
<=	Less or Equal to
>=	Great or Equal to
<>	Not Equal to
!=	Not Equal to

Example:

{
    "column":"age",
    "filter":">",
    "value":"20",
    "condition":"or"
}

Create a new DataView¶

Authentication is required. The requester must be a manager of the source xform and selected project. The XForm and project may belong to different projects.

POST /api/v1/dataviews

Example¶

{
    'name': "My DataView",
    'xform': 'https://api.ona.io/api/v1/forms/12',
    'project':  'https://api.ona.io/api/v1/projects/13',
    'columns': '["name", "age", "gender"]',
    'query': '[{"column":"age", "filter":">", "value":"20"}]'
}

Response¶

{
    name: "My DataView",
    url: "https://api.ona.io/api/v1/dataviews/1",
    xform: "https://api.ona.io/api/v1/forms/12",
    project: "https://api.ona.io/api/v1/projects/13",
    columns: [
        "name",
        "age",
        "gender"
    ],
    query: [
        {
            filter: ">",
            column: "age",
            value: "20"
        }
    ]
}

Retrieve a DataView¶

Users who can access the DataView through its project but cannot view the source XForm data receive an empty query value. Data responses still apply the saved filter and the configured column projection.

Authorization to DataView rows, exports, and selected media is governed by the project containing the DataView. Source-XForm meta-permissions continue to apply to source-XForm endpoints, but do not further narrow a project-authorized DataView. The DataView’s saved row filter and column or media-field projection remain in effect.

GET /api/v1/dataviews/{pk}

Response¶

{
    name: "My DataView",
    url: "https://api.ona.io/api/v1/dataviews/1",
    xform: "https://api.ona.io/api/v1/forms/12",
    project: "https://api.ona.io/api/v1/projects/13",
    columns: [
        "name",
        "age",
        "gender"
    ],
    query: [
        {
            filter: ">",
            column: "age",
            value: "20"
        }
    ]
}

List all DataView¶

GET /api/v1/dataviews

Response¶

[
    {
        name: "My DataView",
        url: "https://api.ona.io/api/v1/dataviews/1",
        xform: "https://api.ona.io/api/v1/forms/12",
        project: "https://api.ona.io/api/v1/projects/13",
        columns: [
            "name",
            "age",
            "gender"
        ],
        query: [
            {
                filter: ">",
                column: "age",
                value: "20"
            }
        ]
    },
    {
        name: "My DataView2",
        url: "https://api.ona.io/api/v1/dataviews/2",
        xform: "https://api.ona.io/api/v1/forms/12",
        project: "https://api.ona.io/api/v1/projects/13",
        columns: [
            "name",
            "age",
            "gender"
        ],
        query: [
            {
                filter: ">",
                column: "age",
                value: "30"
            }
        ]
    }
]

Update a DataView¶

The xform value must identify the existing source XForm. To use a different source XForm, create a new DataView. The project, columns, and query values can be changed by a manager of both the source XForm and selected project.

PUT /api/v1/dataviews/{pk}

Example¶

{
    'name': "My DataView updated",
    'xform': 'https://api.ona.io/api/v1/forms/12',
    'project':  'https://api.ona.io/api/v1/projects/13',
    'columns': '["name", "age", "gender"]',
    'query': '[{"col":"age", "filter":">", "value":"30"}]'
}

Response¶

{
    name: "My DataView updated",
    url: "https://api.ona.io/api/v1/dataviews/1",
    xform: "https://api.ona.io/api/v1/forms/12",
    project: "https://api.ona.io/api/v1/projects/13",
    columns: [
        "name",
        "age",
        "gender"
    ],
    query: [
        {
            filter: ">",
            column: "age",
            value: "30"
        }
    ]
}

Patch a DataView¶

PATCH /api/v1/dataviews/{pk}

Example¶

{
    'columns': '["name", "age", "gender", "date"]'
}

Response¶

{
    name: "My DataView updated",
    url: "https://api.ona.io/api/v1/dataviews/1",
    xform: "https://api.ona.io/api/v1/forms/12",
    project: "https://api.ona.io/api/v1/projects/13",
    columns: [
        "name",
        "age",
        "gender",
        "date"
    ],
    query: [
        {
            filter: ">",
            column: "age",
            value: "30"
        }
    ]
}

Delete a DataView¶

DELETE /api/v1/dataviews/{pk}

Response¶

HTTP 204 NO CONTENT

Retrieving Data from the DataView¶

Returns the data using the dataview filters

GET /api/v1/dataviews/{pk}/data

curl -X GET 'https://api.ona.io/api/v1/dataviews/1/data'

Example Response¶

[
        {"date": "2015-05-19", "gender": "male", "age": 32, "name": "Kendy"},
        {"date": "2015-05-19", "gender": "female", "age": 41, "name": "Maasai"},
        {"date": "2015-05-19", "gender": "male", "age": 21, "name": "Tom"}
]

Retrieving Data using limit operators¶

Returns the data to the requesting user based on ‘start’ and/or ‘limit’ query parameters. Use the start parameter to skip a number of records and the limit parameter to limit the number of records returned.

GET /api/v1/dataviews/{pk}/data?start=start_value

curl -X GET 'https://api.ona.io/api/v1/dataviews/2/data?start=5'

GET /api/v1/dataviews/{pk}/data?start=start_value &limit=limit_value

curl -X GET 'https://api.ona.io/api/v1/dataviews/2/data?limit=2'

GET /api/v1/dataviews/{pk}/data?start=start_value&limit=limit_value

curl -X GET 'https://api.ona.io/api/v1/dataviews/2/data?start=3&limit=4'

Counting the Data in the DataView¶

GET /api/v1/dataviews/{pk}/data?count=true

curl -X GET 'https://api.ona.io/api/v1/dataviews/2/data?count=true'

Example Response¶

[
    {"count":36}
]

Export Dataview Data Asynchronously¶

GET /api/v1/dataviews/{pk}/export_async

Example¶

curl -X GET https://api.ona.io/api/v1/dataviews/28058/export_async?format=xls

Response¶

HTTP 202 Accepted
{"job_uuid": "d1559e9e-5bab-480d-9804-e32111e8b2b8"}

Check progress of exporting form data asynchronously¶

GET /api/v1/dataviews/{pk}/export_async?job_uuid=UUID

Example¶

curl -X GET https://api.ona.io/api/v1/dataviews/28058/export_async?job_uuid=d1559e9e-5bab-480d-9804-e32111e8b2b8

Response¶

If the job is done:

HTTP 202 Accepted
{
    "job_status": "SUCCESS",
    "export_url": "https://api.ona.io/api/v1/dataviews/28058/data.xls"
}

Export Dataview Data Synchronously¶

GET /api/v1/dataviews/{pk}/data.{format}

Example¶

curl -X GET https://api.ona.io/api/v1/dataviews/28058/data.xls

Response¶

File is downloaded

Get a list of chart field endpoints for a specific dataview.¶

GET /api/v1/dataviews/{dataview_pk}/charts

Example¶

curl -X GET https://api.ona.io/api/v1/dataviews/4240/charts

Response¶

{
    "id": 4240,
    "url": "https://api.ona.io/api/v1/dataviews/4240",
    "fields": {
        "uuid": "https://api.ona.io/api/v1/dataviews/4240/charts?field_name=age",
        "num": "https://api.ona.io/api/v1/dataviews/4240/charts?field_name=gender",
        ...
    }
}

Get a chart for a specific field in a dataview¶

field_name - a field name in the dataview
format - json

GET /api/v1/dataviews/{dataview_id}/charts.{format}?field_name=field_name

Example¶

curl -X GET https://api.ona.io/api/v1/dataviews/4240/charts.json?field_name=age

Response¶

html format response is a html, javascript and css to the chart

json format response is the JSON data that can be passed to a charting library