API Documentation

Introduction

Pachube provides most of its functionality via its Application Programming Interface (API), rather than via the website itself.

Below is the reference documentation for that functionality which will aid developers, designers and makers in building tools, applications, devices and environments that use Pachube.

Environment feeds fall into one of two categories. "Manual" feeds are those where the environment or device manually updates Pachube, usually via a PUT request - this is often done on a timed interval, on value-change or at some other significant moment (e.g. upon button press). These tend to be environments that sit behind a firewall or that are too low-powered to sustain a fully functioning server. "Automatic" feeds are those where the environment or device is able to serve data on request: Pachube automatically requests data from them either every 15 minutes or whenever another client requests it (whichever is the more frequent).

Basic concepts

RESTful interface

The Pachube API attempts to conform to the design principles of Representational State Transfer (REST). In most cases you can simply change the file extension on a request to get results in the data format you require.

Data formats

In general requests are available in the following formats: XML (in Extended Environments Markup Language (EEML) format), JSON, CSV, and the syndication formats, RSS and Atom. Not all request methods serve in all formats -- these are detailed in each method. EEML contains the most complete data (though JSON contains everything an EEML document does) and CSV contains the least (in most cases just comma-separated values for each datastreams at last update). In general RSS and Atom results contain feed titles, IDs and geolocation.

When requesting XML (i.e. EEML), the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range may be translated to HTML entities.

Authentication

Some Pachube API methods don't require authentication (primarily those involving syndication and those that contain no realtime data, for example 24-hour history CSV and graphs). This enables them to be used in third-party websites or mashups that require public access.

However, most real time data methods do require a Pachube API key. The API key can be passed either as custom header in the HTTP request (X-PachubeApiKey) or as a parameter ("key") in the URL. This former method is more desirable for both speed and security reasons.

Thus, sample GET requests may look like either:

or

If you would like to use real time data to interact with a web page (for example in Javascript) and you (obviously) don't want to include your API key anywhere publicly visible, the person accessing the web page will need to authenticate with Pachube (a login box should automatically appear). You might also try using Flash and embedding your API key but you must make sure that script code is protected from import in case someone tries to capture your API key that way.

Security

Putting your API key in the URL (as described above) is generally a bad idea since it's much easier for malicious parties to capture it. Placing it in a custom header is slightly better.

However, Pachube also supports SSL connections - a mechanism of verifying the identity of the entity you are communicating with. So if you are security conscious then premium users (i.e. most beta-testers) can access website and API features much more securely by using 'https://' rather than 'http://'.

Parameters

Some API methods take optional parameters and these are documented below as applicable.

Complex string parameters should be converted to UTF-8 and URL encoded.

Note that the 'page' parameter begins at 1, not 0.

JSON callback: this is used only when requesting JSON formatted responses. Including this parameter will enable the response to be wrapped in the callback method of your choice (particularly useful with Javascript and for creating AJAX applications). For example, 'http://www.pachube.com/api/feeds/504.json?callback=myCallbackFunction' will result in a response body of: 'myCallbackFunction({...})' rather than just '{...}'. Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped. This conforms to the implementation discussed here: http://developer.yahoo.com/common/json.html#callbackparam.

HTTP Requests

Methods to retrieve data from the Pachube API require a GET request.

Methods that update or edit feed data require a PUT (though see below for how to do this in clients that are unable to PUT).

Methods that create new feeds require a POST, and must be submitted as EEML, with a required "title" element.

To delete a feed, a DELETE request is used.

HTTP Status Codes

The Pachube API attempts to return appropriate HTTP status codes for every request. Common status codes include:

• 200 OK: request processed successfully.
• 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren't valid.
• 403 Forbidden: Pachube understands your request, but refuses to fulfill it. An accompanying error message should explain why.
• 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (eg. no such feed).
• 422 Unprocessable Entity: Pachube was unable to create a feed because the EEML was not complete/valid (e.g. it didn't include a "title" element).
• 500 Internal Server Error: Something went wrong... Please post to the forum about it and we will investigate.
• 503 No server error: usually occurs when there are too many requests coming into Pachube - if you get this from an /api request then the error message will be returned in XML in the response.

Error Messages

Pachube is currently not very good at returning error messages when things go wrong. We're working on it...

Data resolution

Depending on the type of Pachube account you hold, you will have different temporal resolutions of data available. During the beta period, most beta-testers have "premium" accounts that enable a maximum data-refresh period of 5 seconds. This means that there is no point in requesting or updating feeds any faster than that. (The intention is to decrease this threshold at a later date as system stability is proven).

Rate limit

The default rate limit for calls to Pachube's API is 50 requests every 3 minutes. If your application exceeds this rate, it will be unable to make any successful requests, whether to access feed data or to post new data, and will receive a 503 error for every request until the rate has diminished. Once the rate has diminished service will return to normal, so you don't have to do anything other than reducing the rate of requests.

Note that this means that you can either make requests regularly, to a maximum of one every 3.6 seconds; or you can make a burst of requests, say 50 requests in one minute -- but then you will need to prevent any further requests for another two minutes. Therefore, if you are consistently making requests more frequently than once every 3.6 seconds, then none of your requests will ever be successful. If you would like to enquire about having your API key whitelisted in order to attain higher rates, then please contact us with details of your proposed application.

Getting Started

If your system has curl (and most do!), the quickest way to get going with Pachube (and to test it when you think something is wrong) is to use the command line (Linux & Mac OS X's Terminal, Windows' cmd.exe):

To retrieve values from a feed try this (make sure it's all one line):

And to update the values from a feed, try this (assuming you've set up a manual feed, e.g. at /api/feeds/504):

Working with individual feeds and datastreams

Real time data - accessible only with authentication

All methods that deal with real time data from single feeds are accessible from /api/ (e.g. http://www.pachube.com/api/feeds/504.xml) and require authentication.

Feeds

• feeds/[environment ID]

  Example: http://www.pachube.com/api/feeds/504.xml
  Formats: xml, json, csv
  Method(s): GET
  Returns: environment

  Returns the most recent datastreams from environment ID [number]. If that environment is an "automatic" environment (i.e. it is serving data on request) then requesting data via Pachube will also trigger a request to refresh the data, so that the next request (after the 5 second threshold) should return the updated data. The attribute "updated" (in EEML and JSON format) indicates when this data was last stored by Pachube. The "status" element indicates slightly different things depending on what type of feed it is ("manual" or "automatic"):

  • manual: 'live' means that the remote environment or device manually updated Pachube (usually by PUT) with its data in the last 15 minutes; 'frozen' means that it was last updated more than 15 minutes ago
  • automatic: 'live' means that Pachube has successfully retrieved data from the remote environment or device in the last 15 minutes; 'frozen' means that either it has not retrieved data in the last 15 minutes or that the last time it attempted to retrieve data (within the last 15 minutes) it was unsuccessful.
• feeds/[environment ID]

  Example: http://www.pachube.com/api/feeds/504.xml
  Formats: xml, csv
  Method(s): PUT
  Returns: n/a

  Updates [environment ID]'s environment and datastreams. If successful, the current datastream values are stored and any changes in environment metadata overwrite previous values (including number of datastreams, tags, geolocation, etc.). Pachube stores a server-side timestamp in the "updated" attribute and sets the feed to "live" if it wasn't before. If the feed contains datastreams that conflict with what Pachube has stored, then Pachube overwrites its record and creates/deletes datastreams as necessary. The PUT request requires the body to contain the EEML or CSV to be stored/recorded.

  If your client is unable to make PUT requests, then this can be simulated by a POST request and a "_method=put" parameter, e.g. by POSTing to http://www.pachube.com/api/feeds/504.xml?_method=put

• /feeds

  Example: http://www.pachube.com/api/feeds
  Formats: xml
  Method(s): POST
  Returns: URL of the newly created feed

  Creates a new 'manual' type feed. The body of the request should contain EEML of the environment to be created and it requires at the very least a "title" element.

• feeds/[environment ID]

  Example: http://www.pachube.com/api/feeds/504
  Formats: n/a
  Method(s): DELETE
  Returns: n/a

  Deletes environment ID [number]. This is final and cannot be undone.

Datastreams

• feeds/[environment ID]/datastreams/[datastream ID]

  Example: http://www.pachube.com/api/feeds/504/datastreams/0.xml
  Formats: xml, json, csv
  Method(s): GET
  Returns: environment, with only the requested datastream

  Just like feeds above, but only returns the requested datastream.

• feeds/[environment ID]/datastreams/[datastream ID]

  Example: http://www.pachube.com/api/feeds/504/datastreams/0.xml
  Formats: xml, csv
  Method(s): PUT
  Returns: n/a

  Just like feeds above, but updates just the single datastream [datastream ID] of [environment ID]'s environment.

  Again, if your client is unable to make PUT requests, then this can be simulated by a POST request and a "_method=put" parameter, e.g. by POSTing to http://www.pachube.com/api/feeds/504/datastreams/0.xml?_method=put

• feeds/[environment ID]/datastreams

  Example: http://www.pachube.com/api/feeds/504/datastreams/
  Formats: xml
  Method(s): POST
  Returns: URL of the newly created feed

  Creates a new datastream in environment [environment ID]. The body of the request should contain EEML of the environment to be created and at least one datastream.

• feeds/[environment ID]/datastreams/[datastream ID]

  Example: http://www.pachube.com/api/feeds/504
  Formats: n/a
  Method(s): DELETE
  Returns: n/a

  Deletes datastream [datastream ID] of environment ID [number]. This is final and cannot be undone.

Triggers (aka webhooks, notifications) - accessible only with authentication

Triggers bring 'push' capabilities to Pachube and send HTTP POST requests to a URL of your choice when conditions that you set up on a datastream have been satisfied (e.g. value change, value exceeds threshold, value equals, etc.). They can be created via the web interface or using the API as described below, in which case they are accessible from /api/ and authentication is required.

The minimum interval between sending out two of the same notifications is 300 seconds.

The trigger makes an HTTP POST request to the URL provided at the time of trigger creation and includes a parameter "body" that consists of JSON that looks like this:

Possible values for trigger "type" are:

• gt: greater than
• gte: greater than or equal to
• lt: less than
• lte: less than or equal to
• eq: equal to
• change: any change

Trigger API methods

• triggers

  Example: http://www.pachube.com/api/triggers
  Formats: data encoded as simple HTTP form encoded variables
  Method(s): POST
  Returns: HTTP headers

  Use this method to create a trigger. Data for creating the trigger is encoded as simple HTTP form encoded variables (see above for trigger types):
  

  trigger[url]=http://webhook.com&
trigger[trigger_type]=gt&
trigger[threshold_value]=12&
trigger[environment_id]=123&
trigger[stream_id]=0

  This will create a new notification attached to the datastream identified by the environment and stream ids and return the following:

  HTTP/1.1 201 Created
Server: nginx/0.6.34
Date: Thu, 10 Sep 2009 01:10:49 GMT
Content-Type: application/xml; charset=utf-8
Connection: keep-alive
X-Runtime: 0.08245
Location: http://www.pachube.com/api/notifications/3
Cache-Control: no-cache
Set-Cookie: _pachube_session_id=9e51634c9437f25d0d1ab257156a3376; path=/
Content-Length: 1

  The location header contains the url of the newly created resource.

• triggers

  Example: http://www.pachube.com/api/triggers
  Formats: xml,json
  Method(s): GET
  Returns: XML or JSON representation of triggers

  Use this method to retrieve a list of all triggers for the authenticated account. The XML returned will look like:

  <?xml version="1.0" encoding="UTF-8"?>
<datastream-triggers type="array">
  <datastream-trigger>
    <id type="integer">13</id>
    <url>http://www.postbin.org/1ijyltn</url>
    <trigger-type>gt</trigger-type>
    <threshold-value type="float">20.0</threshold-value>
    <notified-at type="datetime"></notified-at>
    <user>pachube</user>
    <environment-id type="integer">1233</environment-id>
    <stream-id>0</stream-id>
  </datastream-trigger>
  <datastream-trigger>
    <id type="integer">14</id>
    <url>http://www.postbin.org/1ijyltn</url>
    <trigger-type>lt</trigger-type>
    <threshold-value type="float">15.0</threshold-value>
    <notified-at type="datetime"></notified-at>
    <user>pachube</user>
    <environment-id type="integer">1233</environment-id>
    <stream-id>0</stream-id>
  </datastream-trigger>
</datastream-triggers>

  And if JSON is requested it will look like:

  [
{
"trigger_type":"gt",
"stream_id":"0",
"url":"http:\/\/www.postbin.org\/1ijyltn",
"environment_id":1233,
"user":"pachube",
"threshold_value":"20.0",
"notified_at":"",
"id":13
}
,
{
"trigger_type":"lt",
"stream_id":"0",
"url":"http:\/\/www.postbin.org\/1ijyltn",
"environment_id":1233,
"user":"pachube",
"threshold_value":"15.0",
"notified_at":"",
"id":14
}
]

• triggers/[trigger ID]

  Example: http://www.pachube.com/api/triggers/0
  Formats: xml,json
  Method(s): GET
  Returns: XML or JSON representation of a single trigger

  Use this method to retrieve the XML or JSON representation of a single trigger. See above for sample formats.

• triggers/[trigger ID]

  Example: http://www.pachube.com/api/triggers/0
  Formats: data encoded as simple HTTP form encoded variables
  Method(s): PUT
  Returns: HTTP headers

  To update an existing trigger object, the input data is exactly as above, except any attempt to change the environment_id or stream_id is ignored.

• triggers/[trigger ID]

  Example: http://www.pachube.com/api/triggers/0
  Formats: n/a
  Method(s): DELETE
  Returns: n/a

  Deletes the specified trigger object.

Historical data - accessible without authentication

All methods that deal with the last 24 hours of historical data from single feeds are accessible from /feeds/ (e.g. http://www.pachube.com/feeds/504/datastreams/0/history.csv) and DO NOT require authentication.

• [environment ID]/datastreams/[datastream ID]/history

  Example: http://www.pachube.com/feeds/504/datastreams/0/history.csv
  Formats: csv
  Method(s): GET
  Returns: historical values from the last 24 hours

  Returns the last 24 hours of data from the referenced datastream in 15 minute increments, comma-separated without timestamps. (Use archive for timestamped data).

  The data returned contains no header information about the values -- only the 96 values themselves (24 times 4 times per hour) starting with data from 24 hours ago.

• [environment ID]/datastreams/[datastream ID]/history

Example: http://www.pachube.com/feeds/504/datastreams/0/history.csv
Formats: png
Method(s): GET
Returns: historical graph of datastream values, time period depending on requested resolution

Returns historical data from the referenced datastream as a PNG image graph.

The following parameters may be used to configure the styling of the image:

w: width                 (e.g. 600)
h: height                (e.g. 400)
c: colour                (e.g. FFCC33)
t: title                 (e.g. My Favourite Graph)
l: legend                (e.g. Legend For My Graph)
s: strokesize            (e.g. 4)
b: axis labels           (e.g. true)
g: detailed grid         (e.g. true)
r: resolution            (e.g. 1, 2, 3 or 4, where 1 => 1 hour @ 1 minute; 2 => 24 hrs @ 15 mins; 3 => 4 days @ 1 hr; 4 => 3 months @ 1 day)

For example:

http://www.pachube.com/feeds/504/datastreams/2/history.png?w=600&h=300&c=33cc66&b=true&g=true&t=My%20configurable%20graph&l=My%20datastream&s=6&r=3

would return a graph that looks like:



• [environment ID]/datastreams/[datastream ID]/archive

Example: http://www.pachube.com/feeds/504/datastreams/0/archive.csv
Formats: csv
Method(s): GET
Returns: historical values since initial creation of the datastream in CSV format

Returns all data from the referenced datastream since it was initially created, in 15 minute increments. Individual datapoints are separated by newlines, and each line contains a timestamp and the value at that timestamp. This function is only updated once per day, so there may be datapoints missing from it at any particular time. For example:

2009-05-21T06:45:51Z,320
2009-05-21T07:00:04Z,324
2009-05-21T07:15:03Z,311
2009-05-21T07:30:05Z,320
2009-05-21T07:45:03Z,325
2009-05-21T08:00:06Z,320
...

Working with multiple feeds (collections)

Multiple feeds: data available without authentication

All methods that deal with unauthenticated data from collections of feeds are accessible only in RSS and Atom format.

• /feeds

  Example: http://www.pachube.com/feeds.rss
  Formats: rss, atom
  Method(s): GET
  Returns: RSS or Atom document

  Returns an RSS or Atom document containing the last 30 environment feeds published (i.e. created) on Pachube.

• /tag/[tag name]

  Example: http://www.pachube.com/tag/celsius.rss
  Formats: rss, atom
  Method(s): GET
  Returns: RSS or Atom document

  Returns an RSS or Atom document containing the last 30 environment feeds published (i.e. created) on Pachube that have datastreams with the given tag name.

Multiple feeds: data available with authentication

All methods that deal with authenticated data from collections of feeds are accessible in XML (EEML) and JSON format and are available via /api/.

Available methods available are listed below.

• /feeds

  Example: http://www.pachube.com/api/feeds.xml
  Formats: xml, json
  Method(s): GET
  Returns: XML or JSON list

  Returns a paged list of Pachube's feeds with a default page size of 50 feeds.

  The following parameters can be applied to limit or refine the returned feeds:

  • page: Integer indicating which page of results you are requesting. e.g. http://www.pachube.com/api/feeds?page=2
  • per_page: Integer defining how many results to return per page (1 to 1000), e.g. http://www.pachube.com/api/feeds?per_page=5
  • content: String parameter ('full|summary') describing whether we want full or summary results. Full results means all datastream values are returned, summary just returns the environment meta data for each feed. e.g. http://www.pachube.com/api/feeds?content=summary
  • q: Full text search parameter. Should return any feeds matching this string. e.g. http://www.pachube.com/api/feeds?q=arduino
  • tag: Returns feeds containing datastreams tagged with the search query, e.g. http://www.pachube.com/api/feeds?tag=temperature
  • user: Returns feeds created by the user specified, e.g. http://www.pachube.com/api/feeds.xml?user=pachube
  • units: Returns feeds containing datastreams with units specified by the search query, e.g. http://www.pachube.com/api/feeds.xml?units=celsius
  • status: Possible values ('live|frozen|all'). Whether to search for only live feeds, only frozen feeds, or all feeds. Defaults to all. e.g. http://www.pachube.com/api/feeds.xml?status=frozen
  • order: Order of returned feeds. Possible values ('created_at|retrieved_at|relevance'). e.g. http://www.pachube.com/api/feeds.xml?order=created_at

  All of these parameters can be combined, for example:

  http://www.pachube.com/api/feeds?user=dhunter&page=1&per_page=3&content=summary&q=ship&status=live&order=created_at

  Documents returned in XML format have been extended to include Open Search response elements in the following form:

    <opensearch:totalResults>53</opensearch:totalResults>
  <opensearch:startIndex>2</opensearch:startIndex>
  <opensearch:itemsPerPage>10</opensearch:itemsPerPage>

Getting Help

Best is to post a question or comment here in the forums so that other people can pitch in with suggestions or benefit later from things discussed. However, we also try to be very responsive via the "Contact Us" link off of http://www.pachube.com. Failing that, http://twitter.com/pachube is a great way to catch our attention.

Author(s)

This document was created by uh@pachube and will be maintained by several of us going forward. The basic structure of the documentation, and some of the phrases herein, come from Twitter's API documentation which is so clear that it seemed like a good model to build on. (Well Twitter's documentation, the documentation this document was structured on used to be clear, but that link is no longer functional. The new Twitter documentation is not quite as clear as it used to be).