Non-technical or don't want to use code? Start here!

Troubles? Try Pachube with one line of code

Developer, happy to code or use a terminal? Start here!

If you are comfortable with coding then you can use the guidelines below to get going. It would be good, though not essential, that you understand what an HTTP request, a RESTful interface and the Internet of Things are.

1. To use Pachube first signup here: http://www.pachube.com/signup. Please note that registering for Pachube, the service, is different from registering here to post in the community/forum/tutorials/comments.
2. Once you have signed up and activated your account, you will receive an email to say "Your account has been activated!", which will contain details of your username and Master API key. Your username (and the password you supplied during signup) are used for accessing various features on the Pachube website including adding and editing feeds via the web interface. Your API key is what you need in your code to authenticate your application's access to the Pachube service. Don't share this with anyone: it's just like any other password. Pachube’s API enables both real-time and historical data access, but for the purposes of this Quickstart we will only be using real-time data. Remember that if you want to do anything sophisticated, the Pachube API is much more powerful than the website interface!
3. Decide whether you will be making inputs to (i.e. getting data into) or using outputs from (i.e. pulling data out of) Pachube (or both). If you have a microcontroller and sensors and you want to make real time data available to others, this would be considered creating an input to Pachube. If you want to make visualisations from other people's real time data or have remote sensor data trigger things in your microcontroller this would make use of an output from Pachube.

For a quick way to check that its all working correctly, have a look here: http://community.pachube.com/?q=node/9#commandline.

Feed updates and feed requests are limited (server-side) to once every 5 seconds, and API keys are rate limited (depending on account type) so there is no point in requesting data more frequently.

NOTE: The quickstart below has not been updated since 2009 and does not take account of any of the v2 Pachube API. Quickstart to be updated soon (by mid-February 2011)

Configuring an INPUT to Pachube

To create a new INPUT feed, you need to can either make a POST request to the API or login to Pachube and use the interface to create a new feed. For the purposes of this Quickstart, we will use the interface to create a new feed.

Using the Pachube interface to create a new feed

When logged in to Pachube, use this link to create a new feed: http://www.pachube.com/feeds/new

There are two ways to make your real time data available to Pachube and to other Pachube users: either by automatic update (i.e. if your device, sensor or environment can serve data automatically as and when Pachube requests it – that is, Pachube can ‘pull’ the data from you); or by manual update (i.e. by ‘pushing’ the data to Pachube, by making an HTTP PUT request, containing your latest data, as and when you want to -- this is particularly useful when you are behind a firewall).

If you are making an automatic feed, proceed to the next step, otherwise skip to the next step.

Update Pachube automatically, by serving data when requested (i.e. Pachube ‘pulls’ from you)

If your device, sensor or environment can serve data (i.e. so that it is accessible to Pachube via HTTP GET request) and you are not behind a firewall, this may be the simplest option for you.

You make your data available to Pachube via a static URL or IP address and Pachube then automatically ‘pulls’ it as necessary - up to once every 5 seconds if it is being remotely requested, or once every 15 minutes in the absence of any remote requests (in order to keep a historical record). For security reasons, Pachube never exposes your IP address or URL which means that your device, sensor or environment obscures its original location. Since Pachube limits also limits requests this means that even if 50,000 clients are trying to access its data at the same time, Pachube safely handles the load and your device only gets polled, at most, once every 5 seconds.

You can make data available to Pachube in one of three formats:

1. By serving data in XML format: EEML’s XML enables you to add a lot of contextual meta-data to your sensor stream (including GPS location, data tagging, units, user-defined taxonomies using machine tags etc). See Environment tags, machine tags and device classifications for more information on best practices for Datastream IDs, and tagging. EEML at its simplest looks like this:
   
   

   <?xml version="1.0" encoding="UTF-8"?>
   
     
       
         36.2
       
     
   
   

   
   
   However, it should ideally include full namespace information as detailed in this minimal example on the EEML website. A "complete" EEML xsd can be seen here. (A big advantage of EEML is the ability to define metadata including tags for each dat stream within your serving application). Also, see A note on units if you will be using units in your EEML.
   



2. By serving data in JSON format, which mirrors Pachube’s XML format in terms of attributes, but which is often more useful for people who work with web-based applications. Here is the minimum amount required in your JSON file:

{
  "version":"1.0.0",
  "datastreams":[
    {
      "id":"0"
    },
    {
      "id":"1"
    }
  ]
}

0, value1
1, value2
2, value3
	

The data format you choose depends upon your needs. If you want to be able to change meta-data on the fly, then use EEML or JSON. On the other hand if you are working with a microcontroller which needs low overheads then use CSV. In this last case, meta-data can be entered when you add the feed to the Pachube website. Either way, Pachube will make convert in real-time when the data if subsequently pulled from Pachube. That is, if your device is serving CSV and you have added meta-data via the web interface or API, then any device or application that pulls an XML feed from Pachube will get the full meta-data.

If you are building your own server application, remember that you'll need to include HTTP headers depending on what type of data you're serving:

• HTTP/1.1 200 OK\n
  Content-Type: application/xml\n\n
  

  or

• HTTP/1.1 200 OK\n
  Content-Type: text/csv\n\n
  

When your data feed is ready and you know both the URL or IP address and port that you are serving on, login to Pachube, and register an input feed and skip the next step.

Update Pachube manually, by uploading data when necessary (i.e. you ‘push’ to Pachube

This method may be more appropriate if your device, sensor or environment is behind a firewall; or if its processing capacity or power limitations are such that frequent updates would be undesirable; or if it is unable to serve data for any other reason. In this case you would simply make an authenticated PUT to Pachube with either EEML, JSON or CSV as necessary. (See above for a discussion on the benefits of each data format).

Here is a sample PUT request:

PUT /v2/feeds/18842.csv HTTP/1.1
Host: api.pachube.com  
X-PachubeApiKey: ENTER_YOUR_PACHUBE_API_KEY_HERE
Content-Length: 28
Connection: close

0,value1
1,value2
2,value3

NOTE: You must use the ID of the feed you created above, when you first selected “manual” feed. Also don’t forget to use your own API key, and to update the “Content-length” with the appropriate number.

After making this PUT request, you will receive a response code (200 means that the resource was updated successfully; 404 means that the resource could not be found). For a complete list or status codes, see here: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

Note, if you are unable to set custom headers you can also authenticate by putting your Pachube API key in the URL as a parameter, though there may be a small impact on performance. A complete request might look something like:

PUT /v2/feeds/18834.csv?key=ENTER_YOUR_PACHUBE_API_KEY_HERE HTTP/1.1
Host: api.pachube.com  
Content-Length: 28
Connection: close

0,value1
1,value2
2,value3

For example, in LSL for coding in Second Life, where custom headers are not currently possible, the PUT request might look something like this:

requestid = llHTTPRequest("http:api.pachube.com/v1/feeds/76.csv?key=ENTER_YOUR_PACHUBE_API_KEY_HERE", [ HTTP_METHOD, "PUT"], "12,14,66,23.03,text");

Having successfully updated Pachube via a PUT, you would then need to script your device, sensor or environment to update at certain times - for example, once a minute, or on-change-of-value, or only when certain datastream values have exceeded specified amounts.

Connecting to an OUTPUT from Pachube (i.e. ‘pulling’ data from Pachube)

If you are making use of an output from Pachube then you need to be able either to parse XML, JSON or CSV.

JSON and EEML, Pachube’s XML format, enable you to make use of contextual information about a feed, for example its geolocation, units, owner and machine tags.

Go to the Pachube website, to find a Pachube output. Copy its feed url which will look something like one of these two:

http://api.pachube.com/v2/feeds/504.xml

http://api.pachube.com/v2/feeds/504.json

http://api.pachube.com/v2/feeds/504.csv

When you request the feed data, you need to authenticate your request. This is achieved in one of three ways. You can either:

1. Use a header (preferred) - If your code is capable of setting and sending standard HTTP headers, then you can include the key as an HTTP header, separating authentication from the URL request. For example,

   GET /v2/feeds/504.xml
   X-PachubeApiKey: ENTER_YOUR_PACHUBE_KEY_HERE
   

   
   

2. Use a URL parameter - Add your API key to the URL using the ‘key’ parameter. Your request URL would look therefore something like this:

http://api.pachube.com/v2/feeds/504.xml?key=ENTER_YOUR_PACHUBE_KEY_HERE

(where, of course, you supply your own API key).


3. Or, finally, if your client software can send HTTP basic authentication requests, then you can submit your normal login and password to authenticate yourself once; this starts a new session on the server, and while you remain connected, you would not need to keep sending credentials. This is less desirable, but sometimes necessary when building applications where you want people to be able to use their login and password to access their data.

Full documentation is available for the API here: http://api.pachube.com/ where the v2 API contains the most advanced feature set.

Troubles? Try Pachube with one line of code

If you think something's not working, one of the quickest ways to check is using 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):
  curl --request GET --header "X-PachubeApiKey: YOUR_API_KEY" "http://www.pachube.com/api/feeds/504.csv"
• And to update the values from a feed, try this (assuming you've set up a manual feed, e.g. at /api/feeds/504):
  curl --request PUT --header "X-PachubeApiKey: YOUR_API_KEY" --data "test" "http://www.pachube.com/api/feeds/504.csv"