Legacy API

Note: the v1 API is deprecated

Please use the v2 API where possible. The v1 API documentation is maintained for legacy applications only.

For an overview of data formats, authentication, rate limits, etc. please see the API overview.

Note: if following tutorials or examples that use URLs of the format http://www.pachube.com/api/ these should be replaced by http://api.pachube.com/v1, which, from August 2010 is the preferred URL format.

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 http://api.pachube.com/v1 (e.g. http://api.pachube.com/v1/feeds/504.xml) and require authentication.

Feeds

/v1/feeds/[environment ID]
Example http://api.pachube.com/v1/feeds/504.xml
Formats xml, json, csv
Methods 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 and Pachube is 'pulling') 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.

/v1/feeds/[environment ID]
Example http://api.pachube.com/v1/feeds/504.xml
Formats xml, csv
Methods 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://api.pachube.com/v1/feeds/504.xml?_method=put

/v1/feeds
Example http://api.pachube.com/v1/feeds
Formats xml
Methods 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.

/v1/feeds/[environment ID]
Example http://api.pachube.com/v1/feeds/504
Formats n/a
Methods DELETE
Returns n/a

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

Datastreams

feeds/[environment ID]/datastreams/[datastream ID]
Example http://api.pachube.com/v1/feeds/504/datastreams/0.xml
Formats xml, json, csv
Methods 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://api.pachube.com/v1/feeds/504/datastreams/0.xml
Formats xml, csv
Methods 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://api.pachube.com/v1/feeds/504/datastreams/0.xml?_method=put

feeds/[environment ID]/datastreams
Example http://api.pachube.com/v1/feeds/504/datastreams/
Formats xml
Methods 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://api.pachube.com/v1/feeds/504
Formats n/a
Methods 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:

{
  "environment": {
    "description": "",
    "feed": "http:\/\/api.pachube.com\/v1\/feeds\/343",
    "id": 343,
    "location": {
      "lat": 55.74479,
      "lng": -3.18157,
      "name": "location description"
    },
    "title": "test feed yes"
  },
  "id": 1,
  "threshold_value": 9.0,
  "timestamp": "2009-09-07T12:16:02Z",
  "triggering_datastream": {
    "id": "0",
    "url": "http:\/\/api.pachube.com\/v1\/feeds\/343\/datastreams\/0",
    "value": {
      "current_value": "9.07624035140473",
      "max_value": 9.99650150341,
      "min_value": 0.00471012639984
  }
},
 "type": "gte",
 "url": "http:\/\/api.pachube.com\/v1\/triggers\/1"
}

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

/v1/triggers
Example http://api.pachube.com/v1/triggers
Formats data encoded as simple HTTP form encoded variables
Methods 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://api.pachube.com/v1/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.

/v1/triggers
Example http://api.pachube.com/v1/triggers
Formats xml,json
Methods 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
}
]
/v1/triggers/[trigger ID]
Example http://api.pachube.com/v1/triggers/0
Formats xml,json
Methods 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.

/v1/triggers/[trigger ID]
Example http://api.pachube.com/v1/triggers/0
Formats data encoded as simple HTTP form encoded variables
Methods 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.

/v1/triggers/[trigger ID]
Example http://api.pachube.com/v1/triggers/0
Formats n/a
Methods DELETE
Returns n/a

Deletes the specified trigger object.

Historical data - accessible without authentication

History

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

/feeds/[environment ID]/datastreams/[datastream ID]/history
Example http://www.pachube.com/feeds/504/datastreams/0/history.csv
Formats csv
Methods 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.

/feeds/[environment ID]/datastreams/[datastream ID]/history.png

Please note that images via this API are now deprecated in favour of the more flexible and customisable V2 datastream images API

Example http://www.pachube.com/feeds/504/datastreams/0/history.png
Formats png
Methods 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:

Parameter Description Example
w width 600
h height 400
c colour FFCC33
t title My Favourite Graph
l legend Legend For My Graph
s strokesize 4
b axis labels true
g detailed grid true
r resolution 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:

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

Archive

[environment ID]/datastreams/[datastream ID]/archive
Example http://www.pachube.com/feeds/504/datastreams/0/archive.csv
Formats csv
Methods 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

Feeds

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
Methods GET
Returns RSS or Atom document

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

Tags

/tag/[tag name]
Example http://www.pachube.com/tag/celsius.rss
Formats rss, atom
Methods 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.

User feeds

/users/[user ID]/feeds
Example http://www.pachube.com/users/pachube/feeds.rss
Formats rss, atom
Methods GET
Returns RSS or Atom document

Returns an RSS or Atom document containing the last 30 environment feeds published (i.e. created) by the specified user.

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://api.pachube.com/v1/feeds.xml
Formats xml, json
Methods 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:

All of these parameters can be combined, for example:

http://api.pachube.com/v1/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>