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 dataquery- 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. EitherAND/ORDefault isAND
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}/chartsExample¶
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 dataviewformat-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¶
htmlformat response is a html, javascript and css to the chart
jsonformat response is theJSONdata that can be passed to a charting library