Introduction

Welcome to the API documentation for IoTPlotter.com.

This documentation shows the raw HTTP request that needs to be made in addition to a basic Python example.

Rate Limiting

We have yet to decide a specific value for our rate limiting. For now only heavy API users will be limited; anybody making less than 1 request per second will be safe.

Users without a confirmed email address are limited to 1 request per 15-second period (per API key).

Changes to this API

We will not change the API in a way which could break pre-existing code unless it is to fix a security issue. If we need to make changes, we will increment the API version number to allow users to continue using the old API. We will always avoid disabling old API versions, however, we will give at least six weeks notice prior to doing so.

Authentication

Every feed on IoTPlotter has a unique API key which should be kept secret. The API key allows you to make changes to the feed or update its data.

IoTPlotter expects an API key to be present in the HTTP headers for most requests (generally, read-only requests are the only ones that don't need it). Sending your API key during a request is as simple as appending this to your HTTP request headers:

api-key: KEY_HERE

See the examples below for demonstrations.

Writing Data

JSON Formatted

import requests
import json

headers = {'api-key': 'KEY_HERE'}
payload = {} #The variable to send to IoTPlotter
payload["data"] = {} #A dictionary containing the data to send to IoTPlotter
payload["data"]["GRAPH_NAME"] = [] #Creates a list for sending one or more values to IoTPlotter for the 'GRAPH_NAME' graph.

#Appends three values for the graph 'GRAPH_NAME': 
payload["data"]["GRAPH_NAME"].append({"value":25.05}) #'GRAPH_NAME' is set to 25.05
#Add some historical data to the graph:
payload["data"]["GRAPH_NAME"].append({"value":25.99, "epoch":1516195980})
payload["data"]["GRAPH_NAME"].append({"value":24.99, "epoch":1516195280})

requests.post("http://iotplotter.com/api/v2/feed/FEED_ID", headers=headers, data=json.dumps(payload))

POST http://iotplotter.com/api/v2/feed/FEED_ID HTTP/1.1
Connection: Close
api-key: KEY_HERE
Content-Type: application/x-www-form-urlencoded
Content-Length: 115
Host: iotplotter.com

{"data":{"GRAPH_NAME":[{"value":25.05}, {"value":25.99, "epoch":1516195980}, {"value":24.99, "epoch":1516195280}]}}

Make sure to replace FEED_ID with the feed ID belonging to your API key.

The structure of the JSON payload is shown below:

{
  "data": {
    "GRAPH_NAME": [
      {
        "value": 25.05
      },
      {
        "value": 25.99,
        "epoch": 1516195980
      },
      {
        "value": 24.99,
        "epoch": 1516195280
      }
    ],
    "ANY_GRAPH_NAME_HERE": [
      {
        "value": 123
      }
    ]
  }
}

This allows you to send data to a feed; graphs which do not currently exist will be created. You can update one or more graphs using a single request.

HTTP Request Example

POST http://iotplotter.com/api/v2/feed/FEED_ID

Parameters

CSV Formatted

import requests

headers = {'api-key': 'KEY_HERE'}
payload = "0,GRAPH_NAME,25.05" #A CSV string to send to IoTPlotter

requests.post("http://iotplotter.com/api/v2/feed/FEED_ID.csv", headers=headers, data=payload)

POST http://iotplotter.com/api/v2/feed/FEED_ID.csv HTTP/1.1
Connection: Close
api-key: KEY_HERE
Content-Type: application/x-www-form-urlencoded
Content-Length: 21
Host: iotplotter.com

0,GRAPH_NAME,25.05

HTTP Request Example

POST http://iotplotter.com/api/v2/feed/FEED_ID.csv

URL Parameters

Reading Data

JSON Formatted

import requests
import json

response = requests.get("http://iotplotter.com/api/v2/feed/FEED_ID").json() #Throws an error if no data is returned. Returns a dict which can be iterated.

GET http://iotplotter.com/api/v2/feed/FEED_ID HTTP/1.1
Connection: Close
Content-Length: 0
Host: iotplotter.com

Remember to replace FEED_ID with the numerical ID of the feed you want to retrive data from.

The structure of the JSON response is shown below:

{
  "1515544812.02": {
    "data": {
      "GRAPH_NAME": 0.26,
      "SECOND_GRAPH_NAME": 0
    }
  },
  "1515544923.23": {
    "data": {
      "GRAPH_NAME": 0.26,
      "SECOND_GRAPH_NAME": 0
    }
  },
  "1515545106.32": {
    "data": {
      "GRAPH_NAME": 0.25,
      "THIRD_GRAPH_NAME": 0
    }
  },
  "combinations": {
    "25c61c1344993": [
      "GRAPH_NAME",
      "THIRD_GRAPH_NAME"
    ]
  },
  "id": "201810151499732517276500"
}

Allows you to read data from a feed. Currently IoTPlotter will only return one day per request.

HTTP Request Examples

GET http://iotplotter.com/api/v2/feed/FEED_ID

GET http://iotplotter.com/api/v2/feed/FEED_ID?epoch=1516195980&offset=86400

GET http://iotplotter.com/api/v2/feed/FEED_ID?offset=3600

Parameters

CSV Formatted

import requests

response = requests.get("http://iotplotter.com/api/v2/feed/FEED_ID.csv").content
#response now contains the CSV data for the current day

GET http://iotplotter.com/api/v2/feed/FEED_ID.csv HTTP/1.1
Connection: Close
Content-Length: 0
Host: iotplotter.com

The structure of the CSV response is shown below:

1515544812.02,GRAPH_NAME,0.26
1515544812.02,SECOND_GRAPH_NAME,0
1515544923.23,GRAPH_NAME,0.26
1515544923.23,SECOND_GRAPH_NAME,0
1515545106.32,GRAPH_NAME,0.25
1515545106.32,SECOND_GRAPH_NAME,0

The returned data is not necessarily in any particular order. You should order it yourself once the data is received.

HTTP Request Examples

GET http://iotplotter.com/api/v2/feed/FEED_ID.csv

Parameters

Caveats

In this version of the IoTPlotter API only a single day of data can be returned at once. This means getting data for a specific timeframe requires getting a whole day and narrowing it down on your client.

Although you can provide an epoch (UNIX timestamp) value with millisecond precision, IoTPlotter only uses it to select the day, not the time.

We will not alter this behaviour from its currently documented state. Sometime in the future, an improved read API will be released allowing for a better formatted response and the ability to choose a specific timeframe.

Responses

Error Codes