Introduction to AMEE

Embed environmental intelligence into your applications

Today, there is a great deal of interest in energy, and its less-desirable environmental shadow, carbon dioxide. To create a more sustainable world, individuals, companies, and governments are focusing attention on energy and how we use it. The route to understanding our usage of energy (and therefore carbon) is to measure and analyze it, to understand the results, and then act on that information. AMEE is a neutral aggregation platform for all forms of energy and activity data, and associated carbon models. In this article, you learn how to use the AMEE platform in your applications to deliver a high quality energy management and carbon calculation solution to your clients.

Share:

James Smith, Development Manager, AMEE

James Smith is development manager at AMEE. He has a background in software engineering, having spent more than 10 years in C++ software development, on projects ranging from biometrics to flight simulation, as well as having a Ph.D. in 3-D animation algorithms. He has carried out substantial work in the environmental software sector, working on Web-based projects, such as The Carbon Diet and Green Thing before joining AMEE.



24 August 2009 (First published 18 August 2009)

Also available in Chinese Japanese

Introduction

Join the green groups on My developerWorks

Discuss topics and share resources about energy, efficiency, and the environment on the GReen IT Report space and the Green computing group on My developerWorks.

AMEE is a Web-based API that allows users to store and retrieve many forms of consumption data over long periods, while simultaneously applying recognised carbon calculation models to determine the environmental consequences of that consumption. It has been used by developers to deliver energy tracking and management applications ranging from the UK Government's Act On CO2 calculator, CNN, and Google applications and to power carbon management applications such as Carbonetworks and Misys OpenCarbonWorld. The "Powered by AMEE" logo shows that your application complies with authoritative standards.


The AMEE platform

Frequently used acronyms

  • API: Application program interface
  • AMEE: Avoiding Mass Extinctions Engine
  • GHG: Greenhouse gas
  • HTTP: Hypertext Transfer Protocol
  • JSON: JavaScript Object Notation
  • REST: Representational state transfer
  • SAP: Standard Assessment Procedure
  • UID: User identifier
  • URL: Uniform Resource Locator
  • XML: Extensible Markup Language

Interaction with the AMEE platform is accomplished though a RESTful HTTP API which offers a choice of XML, JSON, or Atom data formats. SOAP and other APIs will be added in the future. The API consists of two parts: profiles and data. Profiles are where your energy data is stored. By storing this data over time, you can store a history of energy use for your clients, your business, or yourself. The data store provides a huge array of standard models, including the GHG Protocol, SAP building assessment, carbon emissions factors for 150 countries and regions, and related methodologies. When you store your energy data in an AMEE profile, these methodologies are automatically applied to give a reliable carbon footprint for your energy use.

As mentioned, AMEE is an HTTP API. To show the examples in this article, I will normally include the relevant parts of the HTTP requests involved so you can see exactly what goes on. Therefore, I will assume that you're comfortable with how HTTP requests work, and that you can read XML. If you need help on these, check out the Resources at the end of the article.


Getting started

The first step towards using the AMEE platform is to sign up for an access key. You can do this for free at http://my.amee.com/signup. Enter your details, and within a minute or two you will receive an e-mail with an API key, as well as links to documentation and other relevant resources.

This key will give you access to the AMEE stage platform. This platform is free for you to use while you develop and test your client application. However, the data on it is regularly wiped, so once you decide your application is ready to go into production, you will need to change over to using the AMEE live platform (where service fees might apply). In the example below, you will use the URL for the stage platform because it's where you'll start out.

developerWorks podcast with James Smith

Podcast: James Smith on embedding environmental intelligence in your apps (05:03) - 18 Aug 2009: Listen as the author talks about AMEE (Avoiding Mass Extinction Engine) and how to add its environmental intelligence to your apps.

Another thing to note is that as well as using the API, you can view either of the stage or live platforms directly in your Web browser. If you log in, you can browse around the API at your leisure; all URLs in the examples below will work in your browser. You can also view the XML, JSON and Atom output, which can help during application development.


Authentication

Once you have your key, you're ready to start talking to the API itself, and the first step is authentication. There are two methods of authenticating with the API: HTTP Basic, or an authenticated session.

HTTP basic authentication is extremely simple. You simply provide your username and password with every request, using the standard HTTP format. Most HTTP libraries will support this functionality; as an example, Listing 1 shows this process in Ruby.

Listing 1. HTTP basic authentication
http = Net::HTTP.new @host, 443
http.use_ssl = true
req = Net::HTTP::Get.new @location
req.basic_auth @username, @password
http.request(req)

Alternatively, you can create an authenticated session. You will need to make a POST request to https://stage.amee.com/auth and provide your username and password as form-encoded data in the request body. You also need to specify which format you want the result in (XML or JSON) using a standard Accept header. The response to this request includes various pieces of information, but the most important is the authentication token, which is returned both as a cookie and as a custom header, both called authToken. Store this authToken value and include it as a cookie in any subsequent requests to the API. The authToken will expire after two hours, or if unused for half an hour. Therefore, if you are using authenticated sessions, your application should always be prepared to re-authorise on any request, should the authToken expire.


The AMEE profile API

Now that you're authenticated, you can start to store some data in a profile. A profile might represent an individual, an office, an entire company, or whatever you want, really. It's completely up to you how you want to split up your data; you can create as many profiles as you like. Your application design will probably suggest the most appropriate split, but generally speaking, if something is considered a single energy-using entity in your system, give it a profile to itself.

Each profile in AMEE is identified by a 16-digit random string (a profile UID), which you will need to store in your application's database alongside any other user details you might have; if the user comes back later on, you will need the profile UID to retrieve their information again. This is because privacy and security of data are of utmost importance; all data stored in AMEE is anonymized, so you cannot retrieve profile data based on personal information.

To create a profile, you can send a POST request to https://stage.amee.com/profiles. You need to send the parameter profile=true in the body, as in Listing 2.

Listing 2. Creating a profile
POST /profiles HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
profile=true

Note that I left out authentication details here, and in subsequent examples. You will get back a response that looks like Listing 3 (again, I omitted the less important parts for clarity).

Listing 3. The response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources xmlns="http://schemas.amee.cc/2.0">
  <ProfilesResource>
    <Profile uid="7C7D68C2A7CD">
      ...
    </Profile>
  </ProfilesResource>
</Resources>

The important part of this response is the uid attribute in the Profile tag, which in this case has the value 7C7D68C2A7CD. This is the UID for the newly-created profile, and forms part of the URL for subsequent requests that use that profile.

Profile categories

A profile contains a hierarchy of profile categories, which split up the data that you can store into contextual areas, similar to a folder structure on disk. Top-level categories include such broad sections as Home, Business, Transport, and so on. Each category can contain any number of other categories, and some categories (the lower-level ones normally) can contain profile items. These are like files, and are where you actually store your energy data.

First, look at the description of a profile category in Listing 4. Note that the profile UID from Listing 3 is included in the request path.

Listing 4. Description of a profile category
GET /profiles/7C7D68C2A7CD/home HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources xmlns="http://schemas.amee.cc/2.0">
  <ProfileCategoryResource>
    <Path>/home</Path>
    <Profile uid="7C7D68C2A7CD"/>
    ...
    <DataCategory uid="BBA3AC3E795E">
      <Name>Home</Name>
      <Path>home</Path>
    </DataCategory>
    <ProfileCategories>
      <DataCategory uid="427DFCC65E52">
        <Name>Appliances</Name>
        <Path>appliances</Path>
      </DataCategory>
      <DataCategory uid="30BA55A0C472">
        <Name>Energy</Name>
        <Path>energy</Path>
      </DataCategory>
      ...
    </ProfileCategories>
  </ProfileCategoryResource>
</Resources>

By doing a GET request to /profiles/7C7D68C2A7CD/home, you get back an XML document describing the Home category. You can see that it contains a number of other categories within it. If the category contained profile items (see Listing 5), they are also included in the returned document.

Subcategories are arranged in the same URL structure, so the path for the Appliances subcategory is /profiles/7C7D68C2A7CD/home/appliances. You can traverse the category hierarchy in this way until you find the category that you want to store your data in. However, you will most likely do this category browsing at development time, and probably through the Web interface instead of the XML or JSON API. Category layouts do not change over time, so you can safely store category paths permanently in your code.

Storing data and calculating CO2

Once you find the category where you want to store your energy data, you will want to create a profile item to store that data. To do this, simply POST to the category URL with an appropriate set of parameters, and your data will be stored in a newly-created profile item. For example, to store some energy data in the /home/energy/quantity category, you can send the request in Listing 5.

Listing 5. Storing some energy data in the /home/energy/quantity category
POST /profiles/7C7D68C2A7CD/home/energy/quantity HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
dataItemUid=66056991EE23&energyConsumption=10

HTTP/1.1 201 CREATED
Location: https://stage.amee.com/profiles/7C7D68C2A7CD/home/energy/quantity
/F7C0580D088A

If the request is successful, you get back a 201 CREATED response, with the location of the newly-created item. There are a few things to note here, particularly the parameters in the POST request. The first is dataItemUid, which specifies exactly what type of data you wish to store in the category (in this case, natural gas usage). I will come back to this in more detail in a moment. The second is energyConsumption, which is a profile item value specific to this category. As each category can store a different type of data, the profile item values are different for each one, and I will go into more detail on how you can find out which ones to use in each category later on. However, in this case, the call will store a value of 10 kWh/month of energy for this item. Note that you can select the units you wish to use with your POST (see the Units section for details).

One other option is useful in many cases. If you pass representation=full as an extra parameter in the POST request, you will get back a representation of the newly-created item, rather than just the location. If you want to get back the CO2 value of the data you have just stored, you will want to do this. The XML representation looks just like a GET response (see Listing 6).

Listing 6. XML representation of the newly-created item
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources xmlns="http://schemas.amee.cc/2.0">once you know where, 
  <ProfileCategoryResource>
    ...
    <ProfileItems>
      <ProfileItem uid="2DB26ED646AC">
        <Name/>
        <ItemValues>
          ...
          <ItemValue uid="2A0B5AD9927D">
            <Path>energyConsumption</Path>
            <Name>Energy Consumption</Name>
            <Value>10</Value>
            <Unit>kWh</Unit>
            <PerUnit>month</PerUnit>
            ...
          </ItemValue>
          ...
        </ItemValues>
        <Amount unit="kg/year">24.660000</Amount>
        <StartDate>2009-06-23T17:22:00Z</StartDate>
        <EndDate/>
        <DataItem uid="66056991EE23">
          <Label>gas</Label>
        </DataItem>
      </ProfileItem>
    </ProfileItems>
    <TotalAmount unit="kg/year">24.660000</TotalAmount>
  </ProfileCategoryResource>
</Resources>

Note the ProfileItem tag. It contains details of the new item. Most relevant for now are the values in the ItemValue tag, and the Amount tag. The item values (only one is shown here for clarity, but you will see more in a real response) are representations of the stored parameters from your POST request. In this case, the item value is energyConsumption, and the value is 10. Unit and PerUnit show the units for this item value, in this case kWh/month. The Amount tag simply shows the amount of CO2 emitted by the energy used. So, in this case, if you used 10kWh/month of gas for a year, you would emit 24.66kg of CO2.

Also note the TotalAmount tag at the end of the document. If you looked at a category that contained multiple items (which would all be included in the XML representation), this tag would contain the total CO2 emissions for all items in the category.

You can store thousands of different types of energy use in AMEE by finding the appropriate category and creating the right items. By setting various parameters, you can store different data values at different times, or in different units. I go into some of these options in the following sections.


The AMEE data API

So, storing data and getting results is easy, but how do you know what data to store, and where to store it? This section will delve into that question a little, and expose the mysteries of the strange dataItemUid parameter you came across earlier.

The data side of the AMEE API is located athttps://stage.amee.com/data. (Remember to use your AMEE access key to open the AMEE API. Get your free key at http://my.amee.com/signup.) If you visit this location in a Web browser, you will find it familiar from the examples above. The data API consists of a hierarchy of categories exactly the same as those inside each profile. In fact, these data categories are the real thing, and the hierarchy inside each profile is a virtual copy of the same structure.

Data categories can contain a number of data items, which are linked to the profile items you created earlier on. The data items contain the constants of the AMEE system, like CO2 emission factors, as opposed to profile items, which store the user-supplied variables. You can think of these structures in the following way:

  • Data categories are like abstract base classes; a category might be able to represent all models of car, for instance.
  • The Data Items within that category are like subclasses of that base; a category for car models will contain a data item which represents a Ford Focus, for instance, as well as many others.
  • Profile items are like instances of those classes; if you actually drove a Ford Focus 10,000 miles last year, you can create a profile item (in the equivalent profile category) and set the dataItemUid parameter to the UID of the Ford Focus data item (as well as setting the mileage value).

One important thing to note about data item UIDs—they don't always stay the same. They are subject to change across different instances of the AMEE platform, so they will be different between the live and stage platforms, for instance. While it's safe to hold a local cache of commonly-used item UIDs in your application, do not hardcode them in the same way that category paths can be.

Finding data item UIDs

So, if you need a UID to create a data item, but can't hardcode it into your application, how can you do it? The answer here is to use the drilldown resource for the data category you are interested in. If you send a GET request to https://stage.amee.com/data/{data_category_path}/drill, you will be sent back a list of available options, which will help to select the item you want. For instance, Listing 7 shows you how to select a fuel type in a home energy category.

Listing 7. Selecting a type of car
GET /data/home/energy/quantity/drill HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources>
  <DrillDownResource>
    ...
    <Selections/>
    <Choices>
      <Name>type</Name>
      <Choices>
        <Choice>
          <Name>Gas</Name>
          <Value>gas</Value>
        </Choice>
        <Choice>
          <Name>Electricity</Name>
          <Value>electricity</Value>
        </Choice>
      </Choices>
    </Choices>
  </DrillDownResource>
</Resources>

This document gives you a choice of type options to select from. To select one, you would make another call to the drilldown resource, this time specifying the type in the URL (see Listing 8).

Listing 8. Specifying the fuel type
GET /data/home/energy/quantity/drill?type=gas HTTP/1.1
Accept: application/xml

This time, you will receive a document that contains a different set of choices for the next option. After a couple of iterations, you will get only one choice called UID. This is the UID for the data item that corresponds to your choices. This is very useful for allowing your users to select efficiently from large lists of data items, but it's also required for items in smaller categories.

Even if you already know which item you want to store as you develop your application (for instance, natural gas usage only has one possible item), you will still need to use the drilldown resource. As noted earlier, UIDs can change. However, drilldown URLs are guaranteed not to, even across different AMEE instances platforms. Instead of hardcoding UIDs, you should use the complete drilldown URL and cache the provided UID temporarily.

What data should you use?

AMEE provides a huge range of data types that you can store, from domestic appliances to industrial processes, but you will probably not want to present this entire range to your users. As part of your application design process, you want to come up with a subset of the available data that you want to work with; you can then identify the AMEE categories and data items that you want to use.

The AMEE data wiki is a useful resource for this. Located at http://wiki.amee.com, it contains detailed information on all the data categories within AMEE, including the appropriate parameters to use for items in each category. It also lists all sources for all data, so that you can verify that the figures are reliable if you wish. It also contains some suggestions for common data subsets that you might want to use (for instance, for a domestic carbon calculator).

More control

A number of extra parameters are available that let you control other aspects of your data. The most important of these are times, and units. These are only covered briefly here; the AMEE documentation has much more detail.


Profile history

Storing a single profile item is useful, but most data changes over time, particularly when you talk about energy usage. AMEE allows you to store time information along with your data, so that you can build up a series of data points over time.

Three parameters are available to control time information: startDate, endDate, and duration. By providing these when you create profile items, you can set the time that the created profile item is valid for. By default, startDate is "now" and endDate is infinitely far in the future. If your data is not time-sensitive, then this will be fine. However, if your data represents usage at a particular time, you can set the values explicitly. The maximum time resolution of the AMEE platform is 1 minute. If seconds are specified, they are rounded down. Note that you can only set endDate or duration in a profile.

All these parameters are specified in standard ISO-8601 format. For instance, the parameters in Listing 9 are all valid (when correctly form-encoded):

Listing 9. Valid parameters in standard ISO-8601 format
startDate=2009-08-01T14:30:55Z
endDate=2009-08-02T14:30:55-08:00
duration=PT30S

Note that you don't necessarily need to set endDate or duration, even if you set startDate; if you create two items with different startDates, the endDate of the older one will be worked out automatically. Also, you can set endDate or duration in a profile—only one is allowed at a time.

Naming profile items

If you create two profile items with the same data item UID, and which overlap the same time, then the AMEE API will complain as it can't form a sensible time series from the data. However, there are cases in which you might want to do this; energy used by two cars of the same type, for instance. In this case, you can provide a name parameter to identify each series. You can build up multiple histories in the same profile category by using different names for each one. A name is not required, but if you suspect that you will want to store multiple time series alongside each other, it is good practice to specify one.

Requesting profile history

Once you have built up a time series, you will probably want to retrieve historical data. Above, you saw that profile categories include a list of current profile items. To modify this "present time" behavior, provide startDate and endDate query parameters in the GET request. You can request all data between particular dates, everything that starts after a certain time, or numerous other methods, including a special pro rata mode which calculates the amount of carbon emitted during only the queried time period.


Units

As mentioned earlier, AMEE includes built-in support for a wide range of unit conversions. Most units are SI (International System of Units) by default, but if you want to specify fuel in US gallons instead, you can. Time units can also be changed. Each parameter in a profile item has associated Unit and PerUnit parameters that control these. For instance, if you wanted to use the default units for fuel, you could add a fuel purchase with the following parameter, which would represent a fuel usage of 100 litres per month: volume=100.

If, however, you are measuring in gallons on a weekly basis, you could specify the following parameters: volume=100&volumeUnit=gal&volumePerUnit=week.

Likewise, the CO2 emission results generated by AMEE have default units of kg/year. If you prefer pounds per week, you can specify some special parameters in your GET requests: https://stage.amee.com/profiles/7C7D68C2A7CD/home/energy/ quantity?returnUnit=lb&returnPerUnit=week.

All unit conversion calculations are automatically handled by AMEE, giving you the correct results for your application with the minimum of effort.


Summary

In this article, you learned to use the AMEE API to embed environmental intelligence into your applications. It discussed how the AMEE API works, showed you how and where to store data. If you want to go further, the best way is to dive in and start using it. You can find lots of documentation freely available online that covers all aspects of using the API, and has much more detail on all topics mentioned in this article. Future articles will go into greater depth on how to create an end-to-end application using AMEE, but until then, sign up, have a go, and happy hacking!

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML, Industries
ArticleID=421164
ArticleTitle=Introduction to AMEE
publish-date=08242009