REST API

Timeseries data can be connected to points within DCH, with the ability to upload and download this data via use of DCH's point data API. Multiple output and input formats are supported, including JSON and CSV. When uploading, a variety of formats are supported, including multiple point data upload and upload of multiple data types. For more information regarding configuring the upload endpoint, see the upload endpoint.

Uploading data via DCH REST API

Suppose we know of a point, based on the response of sending a GET request to DCH's /points endpoint (for more information about finding points, see Walkthrough: Finding points):

...
{
    "id": "dsapi-serious-orange-apartment-stream",
    "uid": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570",
    "organisationId": "csiro",
    "datapoolId": "csiro:managed_datapool",
    "name": "dsapi-serious-orange-apartment-stream",
    "type": "brick:Point",
    "unit": null,
    "compositeId": "csiro:managed_datapool:dsapi-serious-orange-apartment-stream"
},
...

We can then use either the composite identifier (csiro:managed_datapool:dsapi-big-funny-plant-stream1) or unique identifier (33b199a8-9eaa-4d75-b4dc-c70aa66a7570) to upload point data to DCH via REST API. To control the format of the payload uploaded to DCH's POST upload observations endpoint, the Content-Type header can be set to either application/json or text/csv.

As JSON

Point data, in the form of timeseries "observations" can be uploaded in JSON format. More detail on this format can be found within the Changelog page. The JSON payload consists of two parts:

• The metadata header (metadata): Mapping the point IDs to a brief point alias to reduce the size of point references within the data section of the payload

• Observations data (data): A list of observations, containing a timestamp (in ISO8601 format) and point alias, along with the observation data, which can be a numeric scalar (field n), vector (field v), or document (field d).

Using composite point identifier

Using the composite point identifier, of the form <organisation id>:<data pool id>:<point id>, users can refer to a point using a human-readable identifier, and map this to an alias in the metadata field of the payload, which is then used to refer to the point within the entries within the data field of the payload.

curl -X 'POST' \
  'https://dataclearinghouse.org/api/chronos/v1/observations/upload' \
  -H 'accept: */*' \
  -H 'X-Api-Key: <API KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "points": {
      "0": "csiro:managed_datapool:dsapi-serious-orange-apartment-stream"
    }
  },
  "data": [
    {
      "t": "2024-05-22T00:00:00Z",
      "p": "0",
      "n": 100
    }
  ]
}'

Using unique point identifier

Similarly, the unique identifier UUID for the point can be used to refer to the point.

curl -X 'POST' \
  'https://dataclearinghouse.org/api/chronos/v1/observations/upload' \
  -H 'accept: */*' \
  -H 'X-Api-Key: <API KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "points": {
      "0": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570"
    }
  },
  "data": [
    {
      "t": "2024-05-22T00:00:00Z",
      "p": "0",
      "n": 100
    }
  ]
}'

Uploading data for multiple points

DCH's upload format also allows for the user to upload data for multiple points.

curl -X 'POST' \
  'https://dataclearinghouse.org/api/chronos/v1/observations/upload' \
  -H 'accept: */*' \
  -H 'X-Api-Key: <API KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "points": {
      "0": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570",
      "1": "157164d9-e7b7-4c5d-89b6-c86f2ee68ad3"
     }
  },
  "data": [
    {
      "t": "2024-05-22T00:00:00Z",
      "p": "0",
      "n": 30
    },
    {
      "t": "2024-05-22T00:00:00Z",
      "p": "1",
      "v": [100.0, 40]
    }  
  ]
}'

As CSV

Additionally, using the Content-Type header, CSV data can be uploaded for multiple points

curl -X 'POST' \
  'https://dataclearinghouse.org/api/chronos/v1/observations/upload' \
  -H 'accept: */*' \
  -H 'X-Api-Key: <API KEY>' \
  -H 'Content-Type: text/csv' \
  -d 't,point,n,v
2024-05-28T00:00:00.000Z,19ba224f-20db-4f97-83db-6c41f17068ac,30.0,
2024-05-28T00:05:00.000Z,157164d9-e7b7-4c5d-89b6-c86f2ee68ad3,,"[100.0,40]"'