# Data points

{{% notice style="warning" title="Deprecated — superseded by Time series" icon="triangle-exclamation" %}}
Data points are **superseded by [time series](../time_series/)**, and their availability in future versions
of OpenGate is **not guaranteed**.

Do not build new integrations on this API. If you are querying data points today, plan the move: define a
time series with the columns and aggregation you need, and query that instead.
{{% /notice %}}

## What a data point is

A **data point** is one instance of a data stream at one instant. Its `at` attribute is when the measurement
was taken, and the whole set of data points for a data stream is the raw history of that measurement.

## Why time series replaces it

Both hold history, but they answer differently:

| | Data points | [Time series](../time_series/) |
|---|---|---|
| Granularity | Every raw value | Values aggregated per time bucket |
| Aggregation | You fetch everything and compute it | Computed on ingestion |
| Cost of a month of data | Every value crosses the wire | One row per device per bucket |
| Future support | **Not guaranteed** | The supported path |

The practical difference shows up at fleet scale: asking a month of readings for ten thousand devices means
millions of data points to transfer and reduce yourself, versus a pre-aggregated table that answers in one
request.

## Querying data points

While the API remains available, it is a standard [Data Lake](../data_lake/) search:

```bash
POST /north/v80/search/datapoints
```

```bash
curl --request POST \
     --header "X-ApiKey: <your-api-key>" \
     --header "Content-Type: application/json" \
     --data '{"filter": {"and": [{"like": {"datapoints.datastreamId": "batteryPercentage"}}]}}' \
     https://api.opengate.es/north/v80/search/datapoints
```

```json
{
  "datapoints": [
    {
      "organization": "battery_organization",
      "channel": "battery_channel",
      "datastreamId": "batteryPercentage",
      "entityIdentifier": "device_1ADA8F",
      "_current": {
        "value": 82,
        "date": "2018-06-04T12:18:11.147+02:00",
        "at": "2018-06-04T12:18:10+02:00",
        "source": "DEVICE_SIGFOX"
      }
    }
  ],
  "page": { "number": 1 }
}
```

Filter fields are prefixed `datapoints.`, so `datapoints.datastreamId`, `datapoints.entityIdentifier` and
the `_current` fields of the value.

## Response format

Results come back as JSON by default or as CSV through header options. A `flattened` parameter returns each
data point flat instead of nested, which is easier to feed into a table — see the datapoint parameters in the
specification below.

## API specification

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