We're in the process of getting real documentation and examples up, but we're so excited about the API that we wanted to get something out as soon as we could. As an added bonus, putting this in the forums also means that we have a place for developers to talk about what they're up to and how they're using our API. As a warning: this is all bleeding edge, and pretty new. But, besides that, welcome!

First off, you're going to need an API key. Anybody can get one, just got to your account settings page, and click on the "API key" link. You'll be asked to take a look at our license agreement (it's pretty standard, but let us know if you have a problem), and then request a key. From then on, whenever you go back to that page, you're will be displayed.

The WattzOn API is a REST-ful one. Everything is currently read-only and only responds to HTTP GETs. All responses from WattzOn are JSON objects, except in the case of errors. If something goes wrong while you are making a request, the API will return an error by setting the HTTP status code to something other than 200. Every call you make needs to have a "key" parameter in the URL that is set to your API key. We're currently requiring that you use your API key as it gives us a way to track down reported issues.

General organization

All the URLs for the API are versioned with two numbers: a date as the major number, and a number as the minor number. For example, currently all our API end points are at

If we ever make an incompatible change to the API, then we will create another URL structure with a new date (while doing our best to maintain the older dates as well). If we need to make an improvement or correction to the API, and we do it in a compatible way, then we'll just bump up the minor number. Basically -- bug fixes will mean minor numbers, and new features and fundamental changes will mean major numbers.

For convenience sake, we also put up a shortcut in the form of

which we will have set up to pass through to the latest minor number -- so it's probably safest to just use that.

Remember, like we were mentioning above, please add a "key=" parameter at the end of your URLs. This would mean that a full end point will take the form of

Anything else, and the platform will probably complain at you.

For the rest of this post, I'll assume you're prefixing everything with

and appending your "key" to the end of each URL.

Getting profile data

To get access to a summary of your profile data (the data that makes up your pie chart), then make a request to

In response, you should get a JSON object that looks like

The most noteworthy thing is that we rarely just put "numbers" in our JSON response objects. WattzOn strives to be fairly precise in everything we say and represent, so to that end, we make sure that everything that should have a unit, does have a unit. For example,

represents a total power of 8015.97 watts.

Similarly, you can request another user's summary data by putting their username in the URL in place of "me"

That request will allow you to fetch my (@raffi's) data.

Getting the description of an item from the EED

Item summaries

Take a moment to browse through the EED. While you do that, take a look at the URL. If you navigated through and found the iPhone (it's important to actually navigate through the tree), you'll see that your browser is parked at a URL that looks like

"What's that garbage string?", you may ask. The last segment, the "kateul1aiv26yqzm9qifapx6t1" is the UUID for the iPhone itself. The "k9fmwte14tuxxadzktgj1baucj" (the one before it and the second to last segment overall) is the UUID for the category that the iPhone is currently residing in.

If you want to access the iPhone's summary information(the information you see on its energy label), then use the following end point

That will return a block that looks something like this (abbreviated)

As you can see, it provides everything that is in the energy label itself (and a bit more). As before, all numbers that are supposed to have units, do have units: mass is reported in kilograms, and energy is reported in mega-joules. The returned object also provides the user names of those who have contributed to this entry.

Also, do notice that material objects have both a "name" and a "key". The "name" is the displayable name of that material, and "key" is there for future use.

Item details

If you want to delve further into an item beyond what is displayed in the energy label, then use the following end point instead

This will return you details a la what is visible on the editable page of an item in the EED (this is the iPhone's page). The JSON is very similar to summary one above, but a few more objects may appear in it. For example

This describes the item's categorization -- this is a path through the category tree to this object. Currently it is represented as an array of arrays because items can belong to multiple categories.

Also appearing in the detailed JSON, you may see the following block

All of those are rather self-descriptive. Both the manufacturing sector and the made-in key's are represented by objects having a "name" and a "key" -- the name is the displayable name, and, again, the key is there for future expansion.

As you have noticed when editing objects in the web application, some key/value pairs are optional (eg. you may not have set the MSRP). If a key/value pair is not set in the database, then it will not appear in the JSON.

The materials in the detailed list contain only the materials for this particular item. Subcomponents are displayed in an array keyed by "components". Objects in that array include a "name", a "key" (so you can query that object directly), and a "count" for each subcomponent.

Finally, in the detailed view, the "discussion" is also available.

Category tree exploration

Recurse the category tree

To explore the category tree using the API, use the following end point

That will list out every category in the EED and give you the individual keys to each category. The response will be in one large array, and every single node in the category tree listed out as such

This example is for the "Packaging" category. Its key is "k5cu09a2o9fpki6agasykdfvmm". It also has four children whose keys are listed in the "children" array.

You can also just explore a portion of the tree. Say, you wanted to explore only the Packaging sub-tree. Then use the end point

That will do precisely the same as the aforementioned end point, but start the recursive exploration at that point node.

Looking at a single level for both items and categories

If you wanted to look only a particular level, but, in additional, know what items are there, then use an end point that looks like this

This explores the category tree at the "Electronics and Computers" node. As mentioned above, this will not only list out the direct children categories, but it will also list out the items at this level in the tree. For example, objects of the array may look like

The first JSON object represents an item in the EED (as noted by the key "type" having a value of "item"). You can use the "key" to query that object directly. The second JSON object is a "category" -- which, in turn, has a child category underneath it.

Recursing the tree for both items and categories

Finally, the mix of the two -- if you wanted to see recuse both for items and categories, use the end point that looks like

This too works at the top level with a

And that's it! Please leave comments on this thread. As I said above, we're working on getting full documents out there, but we wanted to give people a way to start using it now (and so that people can stop screen-scraping -- we know who you are!). Also, if you do use our API, just drop us a line at us@wattzon.com so we can work with you to make sure you have what you want and need.