DataView¶

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

Where:

pk - is the dataview id

Definition¶

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¶

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¶

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¶

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