> For the complete documentation index, see [llms.txt](https://docs.dataclearinghouse.org/dch-2.0-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dataclearinghouse.org/dch-2.0-documentation/walkthroughs/onboarding-building-data/rest-api.md).

# 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](https://dataclearinghouse.org/api/chronos/v1/swagger#/observations/post_observations_upload).

## Uploading data via DCH REST API <a href="#walkthrough-uploadingpointdata-uploadingdataviachronosapi" id="walkthrough-uploadingpointdata-uploadingdataviachronosapi"></a>

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](/dch-2.0-documentation/walkthroughs/finding-points.md)):

```json
...
{
    "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](https://dataclearinghouse.org/api/chronos/v1/swagger#/observations/post_observations_upload), 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](/dch-2.0-documentation/changelog.md) 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](https://en.wikipedia.org/wiki/ISO_8601)) 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]"'
```