# 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]"'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dataclearinghouse.org/dch-2.0-documentation/walkthroughs/onboarding-building-data/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.