Adafruit_IO_Documentation/source/includes/http/_data.md.erb

# Data

Data is at the heart of Adafruit IO. Everything your device measures and records becomes a data point on an Adafruit IO <a href="#feeds">Feed</a>.

You can create, read, update, or delete data records. Every **CREATE**, **UPDATE**, or **DELETE** action on a data record counts against your rate limit.

Data points belong to feeds, so every Data API call starts with a Feed URL.

Note that there are endpoints for submitting multiple data points to a feed, and multiple feed values to a group, see **feeds/{feed_key}/batch** and **groups/{groupname}/data** endpoints.

## Create Data

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data</code></div>

```shell
# Send new data with a value of 42
$ curl -F 'value=42' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data

# Send new data with a value of 42 and include optional location metadata
curl -H "Content-Type: application/json" -d '{"value": 42, "lat": 23.1, "lon": "-73.3"}'  -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data
```

```python
# Adafruit IO Python

# Send data to feed feed_name with a value of 42
io.send_data(location_feed.key, '42')

# Send data to feed `feed_name` with a value of 42 and include optional location metadata
metadata = {'lat': 40.726190,
            'lon': -74.005334,
            'ele': -6,
            'created_at': None}
io.send_data(feed_name.key, data_value, metadata)

# Adafruit IO CircuitPython
# Send data to feed feed_name with a value of 42
io.send_data(location_feed['key'], '42')

# Send data to feed `feed_name` with a value of 42 and include optional location metadata
metadata = {'lat': 40.726190,
            'lon': -74.005334,
            'ele': -6,
            'created_at': None}
io.send_data(feed_name['key'], data_value, metadata)
```

```cpp
// Send data to Feed `feedName` with value of 42
feedName->save(42);

// Send data to Feed `feedName` with value 42 and include optional location metadata
feedName->save(42, latValue, lonValue, eleValue);
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>

New data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key


### Body Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
<b>Request Body</b> | object | true | Data record (datum) including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).



## Get Feed Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data</code></div>

```shell
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data

# get the most recent value
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?limit=1

# get the most recent value before a particular time
$ curl -H "X-AIO-Key: {io_key}" "https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?limit=1&end_time=2019-05-05T00:00Z"

# get all values in a date range
$ curl -H "X-AIO-Key: {io_key}" "https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?start_time=2019-05-04T00:00Z&end_time=2019-05-05T00:00Z"
```

```cpp
// Not implemented in Adafruit IO Arduino
```

```python
# Not implemented in Adafruit IO Python

# Not implemented in Adafruit IO CircuitPython
```

> Response Sample:

<%= partial 'responses/data' %>


### Response Parameters

An array of zero or more data points.

This API is paginated.


### Path Parameters

Parameter | Type    | Required  | Description
--------- | ------- | --------- | -----------------------
username  | string  | true      | a valid username string
feed_key  | string  | true      | a valid feed key


### Query Parameters

Parameter  | Type       | Required  | Description
---------  | -------    | --------- | -----------------------
start_time | string     | false     | Start time for filtering, returns records created after given time. Use [ISO8601 formatted dates](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
end_time   | string     | false     | End time for filtering, returns records created before give time. Use [ISO8601 formatted dates](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
limit      | integer    | false     | Limit the number of records returned.
include    | csv string | false     | List of Data record fields to include in response records. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.
before     | string     | false     | System generated token used to produce the next page of data. See [The Link Header](#the-link-header) for details.





## Chart Feed Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/chart</code></div>

```shell
# Query the chart API for the previous hour.
$ curl -H "X-AIO-Key: {io_key}" 'https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data/chart?hours=1'
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

```json
{
  "feed": {
    "id": 0,
    "key": "string",
    "name": "string"
  },
  "parameters": {
    "start_time": "2019-02-28T16:17:09Z",
    "end_time": "2019-04-29T16:17:09Z",
    "resolution": 120,
    "hours": 1440,
    "field": "avg"
  },
  "columns": ["date", "avg"],
  "data": [
    [ "2019-03-01T14:00:00Z", "62.579827586206896" ],
    [ "2019-03-02T18:00:00Z", "64.94642857142857" ],
    [ "...", "..."]
  ]
}
```

A JSON record containing chart data and the parameters used to generate it. This API will automatically calculate `resolution` based on the optimal time slice for the given `start_time` to `end_time` range or `hours` value given.

Charts on io.adafruit.com use this API with only the `hours` parameter to render charts on dashboards and feed pages.


### Path Parameters

Parameter | Type    | Required  | Description
--------- | ------- | --------- | -----------------------
username  | string  | true      | a valid username string
feed_key  | string  | true      | a valid feed key


### Query Parameters

Parameter  | Type    | Required  | Description
---------  | ------- | --------- | -----------------------
start_time | string  | false     | Start time for filtering, returns records created after given time. Use [ISO8601 formatted dates](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
end_time   | string  | false     | End time for filtering, returns records created before give time. Use [ISO8601 formatted dates](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
resolution | int     | false     | Size of aggregation slice in minutes. Must be one of: `1`, `5`, `10`, `30`, `60`, `120`, `240`, `480`, or `960`
hours      | int     | false     | Number of hours to include in the chart. This value is ignored if `start_time` and `end_time` are given.
field      | string  | false     | Aggregate field to return. Must be one of: `avg`, `sum`, `val`, `min`, `max`, `val_count`
raw        | boolean | false     | Force raw chart data to be returned. Not compatible with `field` or `resolution` parameters. Use `1` or `true` for boolean true value.



## Create Multiple Data Records

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/batch</code></div>

```shell
$ curl -H "Content-Type: application/json" -d @batch.json -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data/batch
```

```python
# Adafruit IO Python
data_list = [Data(value=50), Data(value=33)]
aio.send_batch_data(feed_name.key, data_list)

# Not implemented in Adafruit IO CircuitPython
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/data' %>


New data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key


### Body Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
data | array | true | A collection of data records including `value` (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).


## Get Previous Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/previous</code></div>

```shell
```

```python
# Adafruit IO Python
data = aio.receive_previous(feed.key)
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


Data response




### Path Parameters


Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key





### Query Parameters


Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
include | string | false | List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.


## Get Next Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/next</code></div>

```shell
```

```python
# Adafruit IO Python
data = aio.receive_next(feed.key)
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>

Data response




### Path Parameters


Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key





### Query Parameters


Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
include | string | false | List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.



## Get Last Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/last</code></div>

```shell
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


Data response


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key


### Query Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
include | string | false | List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.



## Get First Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/first</code></div>

```shell
```

```python
# Adafruit IO Python
data = aio.receive(feed.key)
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>

Data response.


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key


### Query Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
include | string | false | List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.




## Get Most Recent Data

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/retain</code></div>

```shell
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

```csv
"string",0.0,0.0,0.0
```

CSV string in `value,lat,lon,ele` format. The lat, lon, and ele values are left blank if they are not set.


### Path Parameters

Parameter | Type    | Required  | Description
--------- | ------- | --------- | -----------------------
username  | string  | true      | a valid username string
feed_key  | string  | true      | a valid feed key




## Get Data Point

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div>

```shell
```

```python
# Adafruit IO Python
data = aio.receive(feed_name.key)

# Adafruit IO CircuitPython
data = aio.receive(feed_name['key'])
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


Data response


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key
id | string | true |


### Query Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
include | string | false | List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.




## Update Data Point

> HTTP Request
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div>

```shell
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


Updated Data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key
id | string | true |


### Body Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
<b>Request Body</b> | object | true | Data record (datum) including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).



## Delete Data Point

> HTTP Request
> <div class="http"><span class="method-delete">DELETE</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div>

```shell
```

```python
# Adafruit IO Python
aio.delete(feed_name.key, data_id)

# Adafruit IO CircuitPython
aio.delete_data(feed_name['key'], data_id)
```

```cpp
```

```ruby
```

> Response Sample:

```json
```

Deleted Group successfully


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key
id | string | true |



## Create Group Data

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups/{group_key}/data</code></div>

```shell
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


New data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |


### Body Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
group_feed_data | object | true | A record with the `feeds` property, containing a collection of records with `key` and `value` properties.

Example for `group_feed_data` in the body is as follows: `{ feeds: [ { key: string, value: string }, ... ], created_at: string (optional), location: { lat: number, lon: number, ele: number } (optional)}`



## Get Data for Group's Feed

> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data</code></div>

```shell
# Send new data with a value of 42 to the group's feeds as json
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/data.json -d '{"feeds":[{"key":"{feed_key}","value":42}]}'
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


An array of data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
feed_key | string | true | a valid feed key



## Create Data in a Group's Feed

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data</code></div>

```shell
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum' %>


New data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
feed_key | string | true | a valid feed key


### Body Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
<b>Request Body</b> | object | true | Data record (datum) including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).



## Create Data in a Group's Feed

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data/batch</code></div>

```shell
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/data' %>


New data


### Path Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
feed_key | string | true | a valid feed key


### Body Parameters

Parameter |   Type  |  Required |       Description
--------- | ------- | --------- | -----------------------
data | array | true | A collection of data records including `value` (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).