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