Data¶

This endpoint provides access to submitted data in JSON format. Where:

pk - the form unique identifier
dataid - submission data unique identifier
owner - username of the owner(user/organization) of the data point

GET JSON List of data end points¶

Lists the data endpoints accessible to requesting user, for anonymous access

a list of public data endpoints is returned.

GET /api/v1/data

Example¶

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

Response¶

[
    {
        "id": 4240,
        "id_string": "dhis2form",
        "title": "dhis2form",
        "description": "dhis2form",
        "url": "https://api.ona.io/api/v1/data/4240"
    },
    ...
]

GET JSON List of data end points using limit operators¶

Lists the data endpoints accesible 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/data/{pk}?start=start_value

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

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

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

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

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

Download data in csv format¶

GET /api/v1/data.csv

curl -O https://api.ona.io/api/v1/data.csv

GET JSON List of data end points filter by owner¶

Lists the data endpoints accessible to requesting user, for the specified owner as a query parameter.

GET /api/v1/data?owner=owner_username

Example¶

curl -X GET https://api.ona.io/api/v1/data?owner=ona

Get Submitted data for a specific form¶

Provides a list of json submitted data for a specific form.

GET /api/v1/data/{pk}

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845

Response¶

[
     {
         "_id": 4503,
         "_bamboo_dataset_id": "",
         "_deleted_at": null,
         "expense_type": "service",
         "_xform_id_string": "exp",
         "_geolocation": [
             null,
             null
         ],
         "end": "2013-01-03T10:26:25.674+03",
         "start": "2013-01-03T10:25:17.409+03",
         "expense_date": "2011-12-23",
         "_status": "submitted_via_web",
         "today": "2013-01-03",
         "_uuid": "2e599f6fe0de42d3a1417fb7d821c859",
         "imei": "351746052013466",
         "formhub/uuid": "46ea15e2b8134624a47e2c4b77eef0d4",
         "kind": "monthly",
         "_submission_time": "2013-01-03T02:27:19",
         "required": "yes",
         "_attachments": [],
         "item": "Rent",
         "amount": "35000.0",
         "deviceid": "351746052013466",
         "subscriberid": "639027...60317"
     },
     ....
 ]

Paginate data of a specific form¶

Returns a list of json submitted data for a specific form using page number and the number of items per page. Use the page parameter to specify page number and page_size parameter is used to set the custom page size.

Example¶

curl -X GET https://api.ona.io/api/v1/data/328.json?page=1&page_size=4

Sort submitted data of a specific form using existing fields¶

Provides a sorted list of json submitted data for a specific form by specifing the order in which the query returns matching data. Use the sort parameter to filter the list of submissions.The sort parameter has field and value pairs.

{"field":value}

Query sorted by the age field ascending.

{"age":1}

Descending sort query using the age field:

{"age":-1}

Example of Ascending Sort¶

curl -X GET https://api.ona.io/api/v1/data/328.json?sort={"age":1}

Example of Descending sort¶

curl -X GET https://api.ona.io/api/v1/data/328.json?sort={"age":-1}

Get a single data submission for a given form¶

Get a single specific submission json data providing pk

and dataid as url path parameters, where:

pk - is the identifying number for a specific form
dataid - is the unique id of the data, the value of _id or _uuid

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

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845/4503

Response¶

{
    "_id": 4503,
    "_bamboo_dataset_id": "",
    "_deleted_at": null,
    "expense_type": "service",
    "_xform_id_string": "exp",
    "_geolocation": [
        null,
        null
    ],
    "end": "2013-01-03T10:26:25.674+03",
    "start": "2013-01-03T10:25:17.409+03",
    "expense_date": "2011-12-23",
    "_status": "submitted_via_web",
    "today": "2013-01-03",
    "_uuid": "2e599f6fe0de42d3a1417fb7d821c859",
    "imei": "351746052013466",
    "formhub/uuid": "46ea15e2b8134624a47e2c4b77eef0d4",
    "kind": "monthly",
    "_submission_time": "2013-01-03T02:27:19",
    "required": "yes",
    "_attachments": [],
    "item": "Rent",
    "amount": "35000.0",
    "deviceid": "351746052013466",
    "subscriberid": "639027...60317"
}

Get the history of edits made to a submission¶

Get a single specific submission json data providing pk

and dataid as url path parameters, where:

pk - is the identifying number for a specific form
dataid - is the unique id of the data, the value of _id or _uuid

GET /api/v1/data/{pk}/{dataid}/history

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845/4503/history

Response¶

[
    {
        "_id": 3,
        "_bamboo_dataset_id": "",
        "_deleted_at": null,
        "expense_type": "service",
        "_xform_id_string": "exp",
        "_geolocation": [
            null,
            null
        ],
        "end": "2013-01-03T10:26:25.674+03",
        "start": "2013-01-03T10:25:17.409+03",
        "expense_date": "2011-12-23",
        "_status": "submitted_via_web",
        "today": "2013-01-03",
        "_uuid": "2e599f6fe0de42d3a1417fb7d821c859",
        "imei": "351746052013466",
        "formhub/uuid": "46ea15e2b8134624a47e2c4b77eef0d4",
        "kind": "monthly",
        "_submission_time": "2013-01-03T02:27:19",
        "_attachments": [],
        "_notes": [],
        "item": "Rent",
        "amount": "35000.0",
        "deviceid": "351746052013466",
        "subscriberid": "639027...60317"
    },
    ....
]

Query submitted data of a specific form¶

Use the query or data parameter to pass in a JSON key/value query.

Example I¶

Query submissions where name is tom

curl -X GET https://api.ona.io/api/v1/data/22845?query={"name":"tom"}

Example II¶

Query submissions where age is greater than 21

curl -X GET https://api.ona.io/api/v1/data/22845?query={"age":{"$gt":"21"}}

Example III¶

Query submissions where age is less than or equal to 21

curl -X GET https://api.ona.io/api/v1/data/22845?query={"age":{"$lte":"21"}}

Example IV¶

Query submissions with case insensitive and partial search

curl -X GET https://api.ona.io/api/v1/data/22845?query={"name":{"$i":"hosee"}}

All Filters Options

Filter	Description
$gt	Greater than
$gte	Greater than or Equal to
$lt	Less than
$lte	Less or Equal to
$i	Case insensitive or partial search

Query submitted data of a specific form using date_created¶

Filter submissions using the date_created field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?date_created__year=2017

All Filters Options

Filter	Description
date_created__year	Exact year e.g. 2017
date_created__year__lt	Year Less than
date_created__year__lte	Year Less than or Equal to
date_created__year__gt	Year Greater than
date_created__year__gte	Year Greater than or Equal to
date_created__month	Exact month e.g. 11
date_created__month__lt	Month Less than
date_created__month__lte	Month Less than or Equal to
date_created__month__gt	Month Greater than
date_created__month__gte	Month Greater than or Equal to
date_created__day	Exact day e.g. 13
date_created__day__lt	Day Less than
date_created__day__lte	Day Less than or Equal to
date_created__day__gt	Day Greater than
date_created__day__gte	Day Greater than or Equal to

Filter options can be chained to narrow results even further.

Query submitted data of a specific form using date_modified¶

Filter submissions using the date_modified field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?date_modified__month=11

All Filters Options

Filter	Description
date_modified__year	Exact year e.g. 2017
date_modified__year__lt	Year Less than
date_modified__year__lte	Year Less than or Equal to
date_modified__year__gt	Year Greater than
date_modified__year__gte	Year Greater than or Equal to
date_modified__month	Exact month e.g. 11
date_modified__month__lt	Month Less than
date_modified__month__lte	Month Less than or Equal to
date_modified__month__gt	Month Greater than
date_modified__month__gte	Month Greater than or Equal to
date_modified__day	Exact day e.g. 13
date_modified__day__lt	Day Less than
date_modified__day__lte	Day Less than or Equal to
date_modified__day__gt	Day Greater than
date_modified__day__gte	Day Greater than or Equal to

Filter options can be chained to narrow results even further.

Query submitted data of a specific form using last_edited¶

Filter submissions using the last_edited field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?last_edited__year=2017&last_edited__month=2

All Filters Options

Filter	Description
last_edited__year	Exact year e.g. 2017
last_edited__year__lt	Year Less than
last_edited__year__lte	Year Less than or Equal to
last_edited__year__gt	Year Greater than
last_edited__year__gte	Year Greater than or Equal to
last_edited__month	Exact month e.g. 11
last_edited__month__lt	Month Less than
last_edited__month__lte	Month Less than or Equal to
last_edited__month__gt	Month Greater than
last_edited__month__gte	Month Greater than or Equal to
last_edited__day	Exact day e.g. 13
last_edited__day__lt	Day Less than
last_edited__day__lte	Day Less than or Equal to
last_edited__day__gt	Day Greater than
last_edited__day__gte	Day Greater than or Equal to

Filter options can be chained to narrow results even further.

Query submitted data of a specific form using version¶

Filter submissions using the version field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?version=2324243

Query submitted data of a specific form using status¶

Filter submissions using the status field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?status=submitted_via_web

Query submitted data of a specific form using uuid¶

Filter submissions using the uuid field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?uuid=9c6f3468-cfda-46e8-84c1-75458e72805d

Query submitted data of a specific form using user¶

Filter submissions using the user field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?user__id=260

All Filters Options

Filter	Description
user__id	user’s id
user__username	user’s username

Query submitted data of a specific form using submitted_by¶

Filter submissions using the submitted_by field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?submitted_by__username=hunter2

All Filters Options

Filter	Description
submitted_by__id	submitted_by user’s id
submitted_by__username	submitted_by user’s username

Query submitted data of a specific form using survey_type¶

Filter submissions using the survey_type field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?survey_type__slug=fortytwo

Query submitted data of a specific form using media_all_received¶

Filter submissions using the media_all_received field

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?media_all_received=true

Query submitted data of a specific form using Tags¶

Provides a list of json submitted data for a specific data/form matching specific tags. Use the tags query parameter to filter the list of forms, tags should be a comma separated list of tags.

You can use the not_tagged query parameter to exclude data/forms that is not tagged with the specific comma separated list of tags.

GET /api/v1/data?tags=tag1,tag2

GET /api/v1/data/{pk}?tags=tag1,tag2

GET /api/v1/data?not_tagged=tag1,tag2

GET /api/v1/data/{pk}?not_tagged=tag2

Example¶

curl -X GET https://api.ona.io/api/v1/data/22845?tags=monthly

Tag a submission data point¶

A POST payload of parameter tags with a comma separated list of tags.

Examples¶

animal fruit denim - space delimited, no commas
animal, fruit denim - comma delimited

POST /api/v1/data/{pk}/{dataid}/labels

Payload

{"tags": "tag1, tag2"}

Delete a specific tag from a submission¶

DELETE /api/v1/data/{pk}/{dataid}/labels/tag_name

Request¶

curl -X DELETE https://api.ona.io/api/v1/data/28058/20/labels/tag1

or to delete the tag “hello world”

curl -X DELETE https://api.ona.io/api/v1/data/28058/20/labels/hello%20world

Response¶

HTTP 200 OK

Get list of public data endpoints¶

GET /api/v1/data/public

Example¶

curl -X GET https://api.ona.io/api/v1/data/public

Response¶

[
    {
        "id": 4240,
        "id_string": "dhis2form",
        "title": "dhis2form",
        "description": "dhis2form",
        "url": "https://api.ona.io/api/v1/data/4240"
    },
    ...
]

Get enketo edit link for a submission instance¶

GET /api/v1/data/{pk}/{dataid}/enketo

Example¶

curl -X GET https://api.ona.io/api/v1/data/28058/20/enketo?return_url=url

Response¶

{"url": "https://hmh2a.enketo.formhub.org"}

Delete a specific submission instance¶

Delete a specific submission in a form

DELETE /api/v1/data/{pk}/{dataid}

Example¶

curl -X DELETE https://api.ona.io/api/v1/data/28058/20

Response¶

HTTP 204 No Content

GEOJSON¶

Get a valid geojson value from the submissions

Options

geo_field - valid field that can be converted to a geojson (Point, LineString, Polygon).
fields - additional comma separated values that are to be added to the properties section

GET /api/v1/data/{pk}/{dataid}.geojson

With options

GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={field_name}&fields={list,of,fields}

Example¶

curl -X GET https://api.ona.io/api/v1/data/28058/20.geojson

Response¶

HTTP 200 OK

Response¶

{
    "type": "Feature",
    "geometry": {
        "type": "GeometryCollection",
        "geometries": [{
            "type": "Point",
            "coordinates": [36.787219, -1.294197]
        }]
    },
    "properties": {
        "id": 6448,
        "xform": 65
    }
}

List the geojson values

GET /api/v1/data/{pk}.geojson

Example¶

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

Response¶

HTTP 200 OK

Response¶

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "GeometryCollection",
                "geometries": [{
                    "type": "Point",
                    "coordinates": [36.787219, -1.294197]
                }]
            },
                "properties": {
                    "id": 6448,
                    "xform": 65
                }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "GeometryCollection",
                "geometries": [{
                    "type": "Point",
                    "coordinates": [36.7872606, -1.2942131]
                }]
            },
            "properties": {
                "id": 6447,
                "xform": 65
            }
        }]
}

OSM¶

The .osm file format concatenates all the files for a form or individual submission. When the .json endpoint is accessed, the individual osm files are listed on the _attachments key.

OSM endpoint for all osm files uploaded to a form concatenated.¶

GET /api/v1/data/{pk}.osm

Example¶

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

OSM endpoint with all osm files for a specific submission concatenated.¶

GET /api/v1/data/{pk}/{data_id}.osm

Example¶

curl -X GET https://api.ona.io/api/v1/data/28058/20.osm