NAV Navbar
HTTP Python
  • Introduction
  • Rate Limiting
  • Changes to this API
  • Authentication
  • Writing Data
  • Reading Data
  • Image API
  • Responses
  • 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

    Parameter Optional Type Description
    api-key Required HTTP header HTTP header containing a valid API key for the feed you are attempting to edit.
    value Required JSON variable Inside the list of datapoints for a particular graph -- The numerical value to apply to the graph.
    epoch Optional JSON variable Inside the list of datapoints for a particular graph -- The epoch (UNIX Timestamp) value to apply to this datapoint.

    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

    Parameter Optional Type Description
    api-key Required HTTP header HTTP header containing a valid API key for the feed you are attempting to edit.
    epoch Required CSV (1st) The epoch (UNIX Timestamp) for the data on this line. 0 = Current time.
    graph_name Required CSV (2nd) The name of the graph this data applies to.
    value Required CSV (3rd) The numerical value to apply to the graph.

    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

    Parameter Optional Type Description
    epoch Optional URL Parameter The epoch of the day to get; any epoch within a 24-hour period will select that date for retrieval. Do not send to indicate 'now'.
    offset Optional URL Parameter The epoch offset (in seconds) to be subtracted from epoch.

    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

    Parameter Optional Type Description
    epoch Optional URL Parameter The epoch of the day to get; any epoch within a 24-hour period will select that date for retrieval. Do not send to indicate 'now'.
    offset Optional URL Parameter The epoch offset (in seconds) to be subtracted from epoch.

    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.

    Image API

    Returning a Graph as Image

    import requests
    
    req = requests.get("http://iotplotter.com/api/v2/img/FEED_ID/DATASTREAM_NAMES/TIMESCALE.png")
    if req.status_code == 200:
      with open('image.png', 'wb') as filewriter:
        filewriter.write(req.content)
    
    GET http://iotplotter.com/api/v2/img/FEED_ID/DATASTREAM_NAMES/TIMESCALE.png
    Connection: Close
    Content-Length: 0
    Host: iotplotter.com
    

    Returns a graph as either a PNG file, or an SVG file. This is primarily designed for embedding graphs in other websites using <img> in HTML or similar methods.

    Parameters

    Parameter Optional Type Description
    FEED_ID Required URL (1st) The ID of the feed to access.
    DATASTREAM_NAMES Required URL (2nd) The names of specific graphs you want to include on the graph plot, seperated by a + character. (View examples below).
    TIMESCALE Required URL (3rd) How many seconds of data you want your graph to contain. Between 300-86400. Always includes latest data and goes back this number of seconds.
    EXTENTION Required URL (3rd, extension) Either .png, or .svg to switch between .png/.svg file formats.

    HTTP Request Examples

    GET http://iotplotter.com/api/v2/img/1234/temperature/3600.png

    GET http://iotplotter.com/api/v2/img/1234/temperature+humidity/86400.svg

    Responses

    Error Codes

    HTTP error code Description Action
    200 Everything worked correctly Continue
    400 Your data or request contained something we didn't understand Check the data you are submitting is formatted correctly. Check all the HTTP headers you have sent are valid.
    401 Your API key is missing or invalid Ensure your API key is sent along with the request and check it belongs to the feed you are accessing.
    403 You do not have permission to do that Ensure your API key belongs to the feed you are accessing. Ensure you are attempting to access the correct feed.
    404 The feed or API endpoint doesn't exist Check the URL you are accessing is valid.
    406 We either don't understand the data you have provided or the request you are making. Check you are making the correct type of HTTP request (POST and GET are the most common).
    410 This API has been removed Upgrade your code to conform to the latest API version.
    429 You have made too many requests in this period of time Slow down your requests. Wait a while and resend this request.
    500 We had an unexpected error Wait a while and resend this request.
    503 IoTPlotter is currently offline Wait a while and resend this request.