API Documentation

1. Introduction
2. General organization
3. Getting profile data
4. Time-stamped power data
1. Reading power data
2. Uploading power data
5. Getting the description of an item from the EED
1. Item summaries
2. Item details
6. Category tree exploration
1. Recurse the category tree
2. Looking at a single level for both items and categories
7. Countries
1. List all countries
2. Country details

Introduction

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. The majority of the API is read-only and only responds to HTTP GETs, except for the time-stamped power data — that has a particular endpoint that responds to a HTTP POST for data upload. WattzOn deals with JSON objects, including 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 and return JSON with any additional details. Every call you make needs to have a "key" parameter in the URL that is set to your API key. In the case of time-stamped power data, HTTP-Auth may also be required. 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 the latest API endpoints 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.

Currently, this end point does not respect the account privacy settings. To be absolutely clear, no matter what your user settings are, this end point will return your summary data. This will be rectified as soon as possible.

Power Meter Data

Consumer level power meters are becoming increasingly popular as a way to measure the power usage of various appliances around your house. WattzOn has built-in support for collecting data from certain power meters such as UC Berkeley's ACmeter. WattzOn also provides an API for integrating with many other devices, such as the Tweet-a-watt. All the uploaded data, regardless of its source, is stored in the WattzOn database, is associated with your profile, can be graphed on the WattzOn site, and is downloadable via the API.

WattzOn stores power readings, indexed by time, separately for each power meter you are using. Each power meter must be associated with the appliance that it is monitoring (such as a TV or a refrigerator). To define your power meters and your appliances, go to the powermeters page under the housing section. Each power meter must have a unique name, and you use this name to identify the meter in the API calls. For meters such as the ACmeter, the name is auto-computed using a unique hardware identifier. For Tweet-a-watts and other similar devices, you must provide your own unique name for the meter.

Like the rest of the WattzOn API, an API key is required to upload or download power meter data. However, we do not consider an API key to be secure credentials. Consequently, an API key is not sufficient to upload or modify power meter data, nor is it sufficient to read power meter data that has been marked as private by the owner (via the Account Privacy settings). In those cases, WattzOn requires the use of HTTP-Basic-Auth, with your WattzOn username and password provided as credentials in the Authorization header. Because HTTP headers are passed in plain text over the network, the use of HTTPS is highly recommended when using HTTP-Basic-Auth in order to protect your password. Authentication via HTTP-Basic-Auth only grants you permission to modify your own data and to read your own private data, not that data of others.

Reading power data

For example, if user "adafruit" wants to grab data from her "tweetawatt" meter, she can simply use an end point that looks something like

The "timestamp" is formatted as an XML timestamp and "power" is an object with a magnitude and units in Watts. With the above query, all the data for that meter will be returned — that dataset may be quite large. To keep that under control, feel free to append "from" and/or "to" parameters to the query. Those parameters must be XML timestamps.

Uploading power data

To upload data into WattzOn from her tweetawatt, adafruit can do an HTTP POST to

For permissions, only adafruit is allowed to upload to for her meters — she can use either her API key or HTTP-Auth with her username and password.

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

Countries

List all countries

To list all the countries that WattzOn has in its database, and uses (e.g. in the calculations around countries), then use the following end point

This will return an array of all the keys for all the countries that WattzOn knows about. These keys are not meant to be FIPS nor ISO-complaint keys, but instead, are keys that WattzOn uses. The response to this call, for example, may look like

To get more specific details in this list, then use

instead. This, instead of just returning an array of strings as the all.json endpoint does, this will return an array of objects that also has the FIPS and ISO code for each country, as well as a reference to the continent that this country belongs in. At this point, there is no way to query the continental information, but this is here for future compatibility. The return of this endpoint may have items that look like

Country details

With the country key, you can query to get more details about a specific country by using the country key in the following endpoint (this endpoint is setup to query for information on the United States)

This will return a JSON document that encodes most of the information WattzOn tracks regarding each country in its database. For example, the United State's JSON object looks something like

Right now, "versioning" nor sources are available through the API, but those will be exposed in future versions.

The values that are reported in the JSON are self-explanatory.