AMEE API / Profile History

Overview

Each Profile has a history. This makes it possible to track and compare CO2 emissions recorded within a Profile for different points in time. This could be now, last month, six months ago, etc.

Profile histories are embodied in Profile Items via their 'validFrom' and 'end' properties. When a Profile has multiple Profile Items related to the same Data Item these form history.

See also: AMEE Concepts

Example

Consider a Profile where the CO2 emissions for an average diesel car are modelled. Over time the usage of this car could vary. Heavy usage one month and light usage another month, for instance. We use multiple Profile Items with distinct validFrom dates to record varying travel distances over time.

As an example, we can model the following usage for an average diesel European car:

  • Jan/2007: 500 miles
  • Feb/2007: 500 miles
  • Mar/2007: 1500 miles
  • Apr/2007: 1500 miles
  • May/2007: Sold car

This is recorded in three Profile Items with these values:

  1. validFrom = 20070101, distance = 500, end = false, amountPerMonth = 95 (kgCO2)
  2. validFrom = 20070301, distance = 1500, end = false, amountPerMonth = 285 (kgCO2)
  3. validFrom = 20070501, end = true

As the distance travelled in Feb and Apr is the same as the previous month we do not need to create fresh Profile Items. The CO2 amount per month is 'carried forward' automatically. So, 1 above is valid for Jan as well as Feb and 2 is valid for Mar as well as Apr (this is carrying forward).

Item 3 is a special Profile Item with the end marker set to true. This means that this particular Data Item (a car of this type) will no longer be represented in this Profile from this point forward. For example, this could be because the user sold their car. Note: if the user made a mistake, e.g. entered a car by mistake and wishes to remove it, then you should delete the profile item.

Profile Item History Rules

Here are the rules relating to Profile Items and history:

  • A Profile Item will 'carry forward' and be valid for all dates after the validFrom date (a homogeneous history).
  • If a Profile contains two Profile Items relating to the same Data Item and with the same name they will form a history in order of the validFrom date (a varied history).
  • It is possible to have two Profile Items with the same validFrom date related to the same Data Item within the same Profile. See Multiple Profile Items for more on this.
  • Profile Items will remain valid until they are superseded by another Profile Item related to the same Data Item.
  • A Profile Item with its end marker set to true will halt the historical sequence (the Profile Item will not be carried forward).

Profile Categories

Profile Items are contained within a Profile Category. The Profile Category will contain different Profile Items at different points of time, according to the rules above. When requesting a Profile Category Resource the Profile Items returned depends on the 'profileDate' parameter. See Profile Category Resource for more details.

Profile History Diagram

Below is a diagram illustrating history with a Profile.

  • This diagram illustrates the history of an example Profile over four months.
  • Each column in the diagram represents a monthly timeframe.
  • Each circle in a column represents a Profile Item that is valid for that timeframe.
  • Each circle in a row represents Profile Items bound to the same Data Item (such as an average diesel European car).
  • Profile Items that start in a particular timeframe are represented by the solid circles.
  • Dashed circles and lines show how Profile Items can be ‘carried over’ to following months / timeframes.
  • Profile Items can be superceded by later Profile Items based on the same Data Item. This ends a period of carry over.
  • A solid circle with a line through it illustrates a Profile Item that is an end marker.
  • Profile Items will be carried over until they are superceded by another Profile Item or an end marker Profile Item ends the sequence (optional).

Example HTTP requests and responses

First create a profile item for a large diesel car Make sure to give it a name - this one is called mainCar 

POST /profiles/CBDD4F4BB1E1/transport/car/generic HTTP/1.0
Accept: application/xml
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82HyjjpJx2QJ3Rn6hTtDpIt9kcQp79/wfa1ZNvg1THmjK+rsODSMahfNlNycxk4bXSXGk=
Host: stage.co2.dgen.net
Content-Type: application/x-www-form-urlencoded
Content-Length: 60

name=mainCar&dataItemUid=4F6CBCEE95F7&distanceKmPerMonth=100
large diesel car 100km response = HTTP/1.1 200 OK
Date: Fri, 17 Aug 2007 15:45:59 GMT
Server: Apache/2.2.3 (Debian) DAV/2 SVN/1.4.2 mod_jk/1.2.18 mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-10 mod_ssl/2.2.3 OpenSSL/0.9.8e
Set-Cookie: authToken=rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7pg56OzO+cPqPTSC5Dnbac9gqS6mdTdvSQ=; Path=/
Vary: Accept-Charset,Accept-Encoding,Accept-Language,Accept
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7pg56OzO+cPqPTSC5Dnbac9gqS6mdTdvSQ=
Connection: close
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?><Resources><ProfileCategoryResource><Path>/transport/car/generic</Path><ProfileDate>200708</ProfileDate><Profile uid="CBDD4F4BB1E1"/><DataCategory uid="87E55DA88017"><Name>Generic</Name><Path>generic</Path></DataCategory><ProfileItem created="Fri Aug 17 16:45:59 BST 2007" modified="Fri Aug 17 16:45:59 BST 2007" uid="24000544BFB0"><Name>mainCar</Name><ItemValues><ItemValue uid="FB408CCC8103"><Path>distanceKmPerMonth</Path><Name>Distance Km Per Month</Name><Value>100</Value><ItemValueDefinition uid="642D122C75CF"><Path>distanceKmPerMonth</Path><Name>Distance Km Per Month</Name><FromProfile>true</FromProfile><FromData>false</FromData><ValueDefinition uid="B691497F1CF2"><Name>kM</Name><ValueType>DECIMAL</ValueType></ValueDefinition></ItemValueDefinition></ItemValue></ItemValues><Environment uid="5F5887BCF726"/><ItemDefinition uid="123C4A18B5D6"/><DataCategory uid="87E55DA88017"><Name>Generic</Name><Path>generic</Path></DataCategory><AmountPerMonth>26.450</AmountPerMonth><ValidFrom>20070801</ValidFrom><End>false</End><Profile uid="CBDD4F4BB1E1"/><DataItem uid="4F6CBCEE95F7"/></ProfileItem></ProfileCategoryResource></Resources>

Now make a very similar call, but put validFrom=20070601 - that is June 2007 Usually you wouldn't set this explicitly; it would just default to the current date, but we're doing it here so we have a historical value to play with. In reality, the user would have entered this value in June 2007 and is now inputing a new value. Make sure that this profile item refers to the same Data UID and has the same name. 

POST /profiles/CBDD4F4BB1E1/transport/car/generic HTTP/1.0
Accept: application/xml
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82HyjjpJx2QJ3Rn6hTtDpIt9kcQp79/wfa1ZNvg1THmjK+rsODSMahfNlNycxk4bXSXGk=
Host: stage.co2.dgen.net
Content-Type: application/x-www-form-urlencoded
Content-Length: 80

validFrom=20070601&name=mainCar&dataItemUid=4F6CBCEE95F7&distanceKmPerMonth=1000
large diesel car June 2007, 500km response = HTTP/1.1 200 OK
Date: Fri, 17 Aug 2007 15:45:59 GMT
Server: Apache/2.2.3 (Debian) DAV/2 SVN/1.4.2 mod_jk/1.2.18 mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-10 mod_ssl/2.2.3 OpenSSL/0.9.8e
Set-Cookie: authToken=rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7pZF+5MSdYOLl2QtXaibHKYahROZ4LUM2E=; Path=/
Vary: Accept-Charset,Accept-Encoding,Accept-Language,Accept
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7pZF+5MSdYOLl2QtXaibHKYahROZ4LUM2E=
Connection: close
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?><Resources><ProfileCategoryResource><Path>/transport/car/generic</Path><ProfileDate>200708</ProfileDate><Profile uid="CBDD4F4BB1E1"/><DataCategory uid="87E55DA88017"><Name>Generic</Name><Path>generic</Path></DataCategory><ProfileItem created="Fri Aug 17 16:45:59 BST 2007" modified="Fri Aug 17 16:45:59 BST 2007" uid="2670A4D90E32"><Name>mainCar</Name><ItemValues><ItemValue uid="E7EE1B7D888B"><Path>distanceKmPerMonth</Path><Name>Distance Km Per Month</Name><Value>1000</Value><ItemValueDefinition uid="642D122C75CF"><Path>distanceKmPerMonth</Path><Name>Distance Km Per Month</Name><FromProfile>true</FromProfile><FromData>false</FromData><ValueDefinition uid="B691497F1CF2"><Name>kM</Name><ValueType>DECIMAL</ValueType></ValueDefinition></ItemValueDefinition></ItemValue></ItemValues><Environment uid="5F5887BCF726"/><ItemDefinition uid="123C4A18B5D6"/><DataCategory uid="87E55DA88017"><Name>Generic</Name><Path>generic</Path></DataCategory><AmountPerMonth>264.500</AmountPerMonth><ValidFrom>20070601</ValidFrom><End>false</End><Profile uid="CBDD4F4BB1E1"/><DataItem uid="4F6CBCEE95F7"/></ProfileItem></ProfileCategoryResource></Resources>

The following gets the current value (time of writing is Aug 2007), which is 26.45 

GET /profiles/CBDD4F4BB1E1/transport/car/generic HTTP/1.0
Accept: application/xml
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82HyjjpJx2QJ3Rn6hTtDpIt9kcQp79/wfa1ZNvg1THmjK+rsODSMahfNlNycxk4bXSXGk=
Host: stage.co2.dgen.net
Content-Type: application/x-www-form-urlencoded
Content-Length: 0


Get value for large diesel car, current date response = HTTP/1.1 200 OK
Date: Fri, 17 Aug 2007 15:45:59 GMT
Server: Apache/2.2.3 (Debian) DAV/2 SVN/1.4.2 mod_jk/1.2.18 mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-10 mod_ssl/2.2.3 OpenSSL/0.9.8e
Set-Cookie: authToken=rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7o7usQTYRHehnA2EC2wIukUn0uq5PiDBL8=; Path=/
Vary: Accept-Charset,Accept-Encoding,Accept-Language,Accept
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7o7usQTYRHehnA2EC2wIukUn0uq5PiDBL8=
Connection: close
Content-Type: application/xml

The following gets the value for July 2007 by setting profileDate=200707. This is BEFORE the validFrom date of the first profile itemwe set above but AFTER the validFrom date of the second one, so it is 264.5. 

<?xml version="1.0" encoding="UTF-8"?><Resources><ProfileCategoryResource><Path>/transport/car/generic</Path><ProfileDate>200708</ProfileDate><Profile uid="CBDD4F4BB1E1"/><DataCategory uid="87E55DA88017"><Name>Generic</Name><Path>generic</Path></DataCategory><Children><ProfileCategories/><ProfileItems><ProfileItem created="2007-08-17 16:45:59.0" modified="2007-08-17 16:45:59.0" uid="24000544BFB0"><distanceKmPerMonth>100</distanceKmPerMonth><amountPerMonth>26.450</amountPerMonth><validFrom>20070801</validFrom><end>false</end><dataItemUid>4F6CBCEE95F7</dataItemUid><path>24000544BFB0</path><name>mainCar</name><dataItemLabel>diesel, large</dataItemLabel></ProfileItem></ProfileItems><Pager><Start>0</Start><From>1</From><To>1</To><Items>1</Items><CurrentPage>1</CurrentPage><RequestedPage>1</RequestedPage><NextPage>-1</NextPage><PreviousPage>-1</PreviousPage><LastPage>1</LastPage><ItemsPerPage>10</ItemsPerPage><ItemsFound>1</ItemsFound></Pager></Children><TotalAmountPerMonth>26.450</TotalAmountPerMonth></ProfileCategoryResource></Resources>

GET /profiles/CBDD4F4BB1E1/transport/car/generic?profileDate=200707 HTTP/1.0
Accept: application/xml
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82HyjjpJx2QJ3Rn6hTtDpIt9kcQp79/wfa1ZNvg1THmjK+rsODSMahfNlNycxk4bXSXGk=
Host: stage.co2.dgen.net
Content-Type: application/x-www-form-urlencoded
Content-Length: 0


Get value for large diesel car, for July 2007 response = HTTP/1.1 200 OK
Date: Fri, 17 Aug 2007 15:45:59 GMT
Server: Apache/2.2.3 (Debian) DAV/2 SVN/1.4.2 mod_jk/1.2.18 mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-10 mod_ssl/2.2.3 OpenSSL/0.9.8e
Set-Cookie: authToken=rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7p9vJDKQLVeSg01HgavMn5Kxh7xqQhWNQE=; Path=/
Vary: Accept-Charset,Accept-Encoding,Accept-Language,Accept
authToken: rcWJsGORRpQw3rEND4c0cJGtXsqhu0lFnNSwRo82Hygxy4u+jyL7Dvt909r6mMEVgFM/e5+8F7p9vJDKQLVeSg01HgavMn5Kxh7xqQhWNQE=
Connection: close
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?><Resources><ProfileCategoryResource><Path>/transport/car/generic</Path><ProfileDate>200707</ProfileDate><Profile uid="CBDD4F4BB1E1"/><DataCategory uid="87E55DA88017"><Name>Generic</Name><Path>generic</Path></DataCategory><Children><ProfileCategories/><ProfileItems><ProfileItem created="2007-08-17 16:45:59.0" modified="2007-08-17 16:45:59.0" uid="2670A4D90E32"><distanceKmPerMonth>1000</distanceKmPerMonth><amountPerMonth>264.500</amountPerMonth><validFrom>20070601</validFrom><end>false</end><dataItemUid>4F6CBCEE95F7</dataItemUid><path>2670A4D90E32</path><name>mainCar</name><dataItemLabel>diesel, large</dataItemLabel></ProfileItem></ProfileItems><Pager><Start>0</Start><From>1</From><To>1</To><Items>1</Items><CurrentPage>1</CurrentPage><RequestedPage>1</RequestedPage><NextPage>-1</NextPage><PreviousPage>-1</PreviousPage><LastPage>1</LastPage><ItemsPerPage>10</ItemsPerPage><ItemsFound>1</ItemsFound></Pager></Children><TotalAmountPerMonth>264.500</TotalAmountPerMonth></ProfileCategoryResource></Resources>

Attachments