# Data collection

## Introduction 

API to send raw IoT data to OpenGate.

## HTTP data collection

This section shows how to use OpenGate HTTP connector for data collection.

The endpoint allows devices to send raw data to OpenGate.

It can be done by:

- sending data points with their respective timestamps in different datastreams in a single request
- sending data points without timestamp in different datastreams in a single request

## Note about data streams with special platform processing

Besides the spec info you can find below, it's worth considering that there are two data streams with special platform processing rules: `device.identifier` and `device.topology.path`.

These data streams match fields outside the list of data streams in the collection JSON. Due to this special treatment, these data streams will never be collected from the list of data streams; they will be collected from their fields in the collection JSON.

If you want to collect the data stream `device.topology.path` you have to fill in the field `path` of the collection JSON. Or, in case of the device is directly behind a gateway, you can remove the field `path` and fill in the field `device` in the collection JSON, OpenGate will collect the data stream `device.topology.path` with the gateway identifier.

Also, if you want to collect the data stream `device.identifier` you have to fill in the field `device` of the collection JSON. If you don't fill in this field, OpenGate will collect the data stream `device.identifier` from the `device_id` (that is, the gateway) in the URI, and all the data in the data streams array will be stored in the gateway collected info.

## Usage examples

Send the latest value of each data stream (no timestamp):

```bash
curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/collect/iot' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "1.0.0",
    "datastreams": [
      { "id": "example", "feed": "feed_1", "datapoints": [{ "value": 333 }] },
      { "id": "key", "feed": "feed_2", "datapoints": [{ "value": "value" }] },
      { "id": "datastream", "datapoints": [{ "value": 1337 }] }
    ]
  }'
```

Send one data stream with several timestamped data points:

```bash
curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/collect/iot' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "1.0.0",
    "datastreams": [
      {
        "id": "temperature",
        "feed": "feed_1",
        "datapoints": [
          { "at": 1431602523123, "value": 25 },
          { "at": 1431602523123, "value": 26 }
        ]
      }
    ]
  }'
```

A valid request returns HTTP `201`.

## API specification

{{< openapi src="data_collection_merged.yaml" >}}