; rel="last"
**JSON Response:** ::
[
{
"_id":1,"_tags":[],"_uuid":"78afb566-8293-4f42-a83f-99d5ba0061e2",
"_notes":[]"_edited":false,"_status":"submitted_via_web",
"_version":"202010260841","_duration":"","_xform_id":2,
"plot_count":"1","_attachments":[],"_geolocation":[null,null],
"_media_count":0,"_total_media":0,"formhub/uuid":"281845ab2d214ff6ac08526c0484fe34",
"_submitted_by":null,"meta/instanceID":"uuid:78afb566-8293-4f42-a83f-99d5ba0061e2",
"_submission_time":"2020-10-26T08:49:06","_xform_id_string":"nested_repea",
"_bamboo_dataset_id":"","_media_all_received":true
}
]
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``
.. raw:: html
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"
}
Fetch data on select columns for a given form
---------------------------------------------------
Returns a list of the selected columns from the submitted data. Use the ``fields`` parameter to specify the column data that should be returned.
- ``fields`` - a comma separated list of columns on the given form.
.. raw:: html
GET /api/v1/data/{form_pk}.json?fields=["field1", "field2"]
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/513322.json?fields=["_id", "_last_edited"]
Response
^^^^^^^^^
::
[
{
"_id": 64999942,
"_last_edited": null
},
{
"_id": 64999819,
"_last_edited": null
},
{
"_id": 64999278,
"_last_edited": null
},
{
"_id": 64999082,
"_last_edited": null
},
{
"_id": 60549177,
"_last_edited": null
},
{
"_id": 60549136,
"_last_edited": null
}
]
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``
.. raw:: html
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.
When quering a date time field whose value is in ISO format such as ``2020-12-18T09:36:19.767455+00:00``, it is important to ensure the ``+`` (plus) is encoded to ``%2b``.
``+`` without encoding is parsed as whitespace. So ``2020-12-18T09:36:19.767455+00:00`` should be converted to ``2020-12-18T09:36:19.767455%2b00:00``.
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"}}
Example V
^^^^^^^^^^
Query submissions collected before specific date
::
curl -X GET https://api.ona.io/api/v1/data/22845.json?query={"_submission_time":{"$lte": "2020-08-31"}}
Example VI
^^^^^^^^^^
Query submissions collected within specific dates
::
curl -X GET https://api.ona.io/api/v1/data/22845.json?query={"_submission_time":{"$gte": "2020-01-01", "$lte": "2020-08-31"}}
Example VII
^^^^^^^^^^^
Query submissions where age is 21 or name is hosee
::
curl -X GET https://api.ona.io/api/v1/data/22845?query={"$or": [{"age": "21", "name": "hosee"}]}
Example VIII
^^^^^^^^^^^^
Query submissions with APPROVED submission review status
::
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status" : "1"}
Example IX
^^^^^^^^^^^^
Query submissions with REJECTED submission review status
::
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status" : "2"}
Example X
^^^^^^^^^^
Query submissions with PENDING submission review status
::
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status" : "3"}
Example XI
^^^^^^^^^^
Query submissions with pending submission review status or NULL
::
curl -X GET https://api.ona.io/api/v1/data/22845?query={"$or": [{"_review_status": "3"}, {"_review_status": null}]}
Example XII
^^^^^^^^^^^
Query submissions with `NULL` submission review status
::
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status": null}
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
**$or** Or
==================================================
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.
.. raw:: html
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
.. raw:: html
POST /api/v1/data/{pk}/{dataid}/labels
**Payload**
::
{"tags": "tag1, tag2"}
Delete a specific tag from a submission
----------------------------------------
.. raw:: html
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
----------------------------------
.. raw:: html
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
-----------------------------------------------
.. raw:: html
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**
.. raw:: html
DELETE /api/v1/data/{pk}/{dataid}
Example
^^^^^^^^^
::
curl -X DELETE https://api.ona.io/api/v1/data/28058/20
Response
^^^^^^^^^
::
HTTP 204 No Content
Delete a subset of submissions
-------------------------------
**Delete multiple submissions in a form**
.. raw:: html
DELETE /api/v1/data/{pk}
A POST payload of parameter `instance_ids` with a comma separated list of submission ids.
**Payload**
::
instance_ids = '101425,108428,1974624'
Example
^^^^^^^^^
::
'curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'instance_ids=101425,108428,1974624'
Response
^^^^^^^^^
::
{"status_code": 200, "message": "3 records were deleted"}
Delete all submissions in a form
---------------------------------
**Delete all submissions in a form**
.. raw:: html
DELETE /api/v1/data/{pk}
A POST payload of parameter `delete_all` with the value 'True'. The value is 'False' by default.
**Payload**
::
delete_all = 'True'
Example
^^^^^^^^^
::
'curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'delete_all="True"'
Response
^^^^^^^^^
::
{"status_code": 200, "message": "3 records were deleted"}
Permanent Deletion of Submissions
------------------------------------
**Permanently Delete a specific submission instance**
`DELETE /api/v1/data/{pk}/{dataid}`
A POST payload of parameter `permanent_delete` with the value 'True'. The value is 'False' by default.
Note: This functionality is only enabled when the ``ENABLE_SUBMISSION_PERMANENT_DELETE`` setting is set to `True` within the application
**Payload**
::
permanent_delete = 'True'
Example
^^^^^^^^^
::
`curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'permanent_delete=True'`
Response
^^^^^^^^^
::
HTTP 204 No Content
**Permanently Delete a subset of submissions**
`DELETE /api/v1/data/{pk}`
Example
^^^^^^^^^
::
`curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'permanent_delete=True' -d 'instance_ids=101425,108428,1974624'`
Response
^^^^^^^^^
::
{
"status_code": "200",
"message": "3 records were deleted"
}
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
- ``simple_style`` - boolean to enable or disable Mapbox Geojson simplestyle spec
- ``title`` - adds a title field and value to geojson properties section
**List all the geojson values for a submission**
.. raw:: html
GET /api/v1/data/{form_pk}/{dataid}.geojson
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 all the geojson values for a given form**
.. raw:: html
GET /api/v1/data/{form_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
}
}]
}
**List the geojson data, for a polygon field, for a given submission**
.. raw:: html
GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={name_of_field_on_form}
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?geo_field=my_geoshape
Response
^^^^^^^^^
**HTTP 200 OK**
Response
^^^^^^^^^
::
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
36.747679,
-1.300717
],
[
36.752386,
-1.305222
],
[
36.751879,
-1.300642
],
[
36.747679,
-1.300717
]
]
]
},
"properties": {
"id": 60549136,
"xform": 513322
}
}
**List the geojson data, for a geotrace field, for a given submission. Add fields to the properties attribute**
.. raw:: html
GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={name_of_field_on_form}
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?geo_field=my_geotrace
Response
^^^^^^^^^
**HTTP 200 OK**
Response
^^^^^^^^^
::
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
36.745623,
-1.302819
],
[
36.750326,
-1.299129
]
]
},
"properties": {
"id": 60549136,
"xform": 513322
}
}
**Fetch geojson values for a submission with populated properties attribute**
.. raw:: html
GET /api/v1/data/{pk}/{dataid}.geojson?fields={_id,_last_edited}
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?fields=_id,_last_edited
Response
^^^^^^^^^
**HTTP 200 OK**
Response
^^^^^^^^^
::
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"coordinates": [
36.744421,
-1.29943
]
}
]
},
"properties": {
"id": 60549136,
"xform": 513322,
"_id": 60549136,
"_last_edited": null
}
}
**List all the geojson values for a given form with simplestyle-spec enabled and title prop set**
.. raw:: html
GET /api/v1/data/{form_pk}.geojson?geo_field={name_of_field_on_form}&simple_style=true&title={name_of_title_field_on_form}
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/28058.geojson?geo_field=my_geoshape&style_spec=true
Response
^^^^^^^^^
**HTTP 200 OK**
Response
^^^^^^^^^
::
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [36.787219, -1.294197]
},
"properties": {
"id": 6448,
"xform": 65,
"title": "my_field"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [36.7872606, -1.2942131]
},
"properties": {
"id": 6447,
"xform": 65,
"title": "my_field"
}
}]
}
**Paginate geojson data for a given form**
Returns a list of geojson features 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 to set the custom page size.
- ``page`` - Integer representing the page.
- ``page_size`` - Integer representing the number of features that should be returned in a single page.
.. raw:: html
GET /api/v1/data/{form_pk}.geojson?page={page_number}&page_size={page_size_number}
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/28058.geojson?page=1&page_size=2
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. raw:: html
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. raw:: html
GET /api/v1/data/{pk}/{data_id}.osm
Example
^^^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/data/28058/20.osm