AMEE API / Data API / Data Item
Table of Contents
Overview
A Data Item represents a single type of energy usage which contributes to CO2 emissions. Data Items provide the data required to perform emissions calculations for Profile Items.
For example, a particular Data Item could represent an average sized petrol car. You could create a Profile Item associated with this Data Item, which would specifying that a user has an average sized petrol car. You could set extra parameters in this Profile Item to specify information such as that the car is driven 5000 kilometres per year.
Each Data Item can have several Data Item Values (distance, for instance).
See also: AMEE Concepts, AMEE Data API
Properties
| Property | Definition |
| path | The path segment for this Data Item within the URL path. This is not always used and will default to the UID. |
| name | A display name for this Data Item. This is not always used and will default to the UID. |
See also: Common Properties
API Operations
Viewing a Data Item
- URL: http://{server}/data/{subcategory_path}/{data_item_uid}
- Method: GET
- Response format: application/xml, application/json
- Response code: 200 OK
- Response body: A description of the data item and its values.
Example: JSON
Request:
GET /data/transport/plane/generic/FFC7A05D54AD HTTP/1.1
Accept: application/json
Authtoken: {your_authtoken_goes_here}
Response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8
{
"path":"/transport/plane/generic/FFC7A05D54AD",
"userValueChoices":{
"choices":[
{
"name":"distance",
"value":""
},
{
"name":"IATACode1",
"value":""
},
{
"name":"IATACode2",
"value":""
},
{
"name":"journeys",
"value":""
},
{
"name":"lat1",
"value":"-999"
},
{
"name":"lat2",
"value":"-999"
},
{
"name":"long1",
"value":"-999"
},
{
"name":"long2",
"value":"-999"
},
{
"name":"numberOfPassengers",
"value":""
},
{
"name":"passengerClass",
"value":""
}
],
"name":"userValueChoices"
},
"dataItem":{
"uid":"FFC7A05D54AD",
"startDate":"2007-08-01T09:00:41+01:00",
"dataCategory":{
"uid":"FBA97B70DBDF",
"name":"Generic",
"path":"generic"
},
"itemValues":[
{
"itemValueDefinition":{
"uid":"C376560CB19F",
"name":"Type",
"path":"type",
"valueDefinition":{
"uid":"CCEB59CACE1B",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"description":"",
"name":"text",
"valueType":"TEXT",
"modified":"2007-07-27 09:30:44.0"
}
},
"perUnit":"",
"uid":"E459F81B0876",
"unit":"",
"name":"Type",
"value":"domestic",
"path":"type",
"displayPath":"type",
"displayName":"Type"
},
{
"itemValueDefinition":{
"uid":"5D7FB5F552A5",
"name":"Size",
"path":"size",
"valueDefinition":{
"uid":"CCEB59CACE1B",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"description":"",
"name":"text",
"valueType":"TEXT",
"modified":"2007-07-27 09:30:44.0"
}
},
"perUnit":"",
"uid":"33A729613596",
"unit":"",
"name":"Size",
"value":"one way",
"path":"size",
"displayPath":"size",
"displayName":"Size"
},
{
"itemValueDefinition":{
"uid":"D7B4340D9404",
"name":"kgCO2 Per Passenger Km",
"path":"kgCO2PerPassengerKm",
"valueDefinition":{
"uid":"996AE5477B3F",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"description":"",
"name":"kgCO2PerKm",
"valueType":"DECIMAL",
"modified":"2007-07-27 09:30:44.0"
}
},
"perUnit":"",
"uid":"19602052C053",
"unit":"",
"name":"kgCO2 Per Passenger Km",
"value":"0.0000",
"path":"kgCO2PerPassengerKm",
"displayPath":"kgCO2PerPassengerKm",
"displayName":"kgCO2 Per Passenger Km"
},
{
"itemValueDefinition":{
"uid":"653828811D42",
"name":"kgCO2 Per Passenger Journey",
"path":"kgCO2PerPassengerJourney",
"valueDefinition":{
"uid":"8CB8A1789CD6",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"description":"",
"name":"kgCO2PerJourney",
"valueType":"DECIMAL",
"modified":"2007-08-01 08:57:31.0"
}
},
"perUnit":"",
"uid":"C32B6E2EDCB0",
"unit":"",
"name":"kgCO2 Per Passenger Journey",
"value":"81.2000",
"path":"kgCO2PerPassengerJourney",
"displayPath":"kgCO2PerPassengerJourney",
"displayName":"kgCO2 Per Passenger Journey"
},
{
"itemValueDefinition":{
"uid":"0F0592F05AAC",
"name":"Source",
"path":"source",
"valueDefinition":{
"uid":"CCEB59CACE1B",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"description":"",
"name":"text",
"valueType":"TEXT",
"modified":"2007-07-27 09:30:44.0"
}
},
"perUnit":"",
"uid":"F3C2C8046B54",
"unit":"",
"name":"Source",
"value":"defra/amee 2008",
"path":"source",
"displayPath":"source",
"displayName":"Source"
}
],
"environment":{
"uid":"5F5887BCF726",
"itemsPerFeed":10,
"created":"2007-07-27 09:30:44.0",
"description":"",
"name":"AMEE",
"owner":"",
"path":"",
"itemsPerPage":10,
"modified":"2007-07-27 09:30:44.0"
},
"created":"2007-08-01 09:00:41.0",
"name":"FFC7A05D54AD",
"path":"",
"itemDefinition":{
"uid":"441BF4BEA15B",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"name":"Plane Generic",
"drillDown":"type,size",
"modified":"2007-07-27 09:30:44.0"
},
"endDate":"",
"label":"domestic,one way",
"modified":"2007-08-01 09:00:41.0"
},
"actions":{
"allowCreate":false,
"allowView":true,
"allowList":false,
"allowModify":false,
"allowDelete":false
},
"amountPerMonth":0
}
Example: XML
Request:
GET /data/transport/plane/generic/FFC7A05D54AD HTTP/1.1
Accept: application/xml
Authtoken: {your_authtoken_goes_here}
Response:
HTTP/1.1 200 OK Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <Resources> <DataItemResource> <DataItem created="2007-08-01 09:00:41.0" modified="2007-08-01 09:00:41.0" uid="FFC7A05D54AD"> <Name>FFC7A05D54AD</Name> <ItemValues> <ItemValue uid="E459F81B0876"> <Path>type</Path> <Name>Type</Name> <Value>domestic</Value> <Unit/> <PerUnit/> <ItemValueDefinition uid="C376560CB19F"> <Path>type</Path> <Name>Type</Name> <ValueDefinition created="2007-07-27 09:30:44.0" modified="2007-07-27 09:30:44.0" uid="CCEB59CACE1B"> <Name>text</Name> <ValueType>TEXT</ValueType> <Description/> <Environment uid="5F5887BCF726"/> </ValueDefinition> <FromProfile>false</FromProfile> <FromData>true</FromData> </ItemValueDefinition> </ItemValue> <ItemValue uid="33A729613596"> <Path>size</Path> <Name>Size</Name> <Value>one way</Value> <Unit/> <PerUnit/> <ItemValueDefinition uid="5D7FB5F552A5"> <Path>size</Path> <Name>Size</Name> <ValueDefinition created="2007-07-27 09:30:44.0" modified="2007-07-27 09:30:44.0" uid="CCEB59CACE1B"> <Name>text</Name> <ValueType>TEXT</ValueType> <Description/> <Environment uid="5F5887BCF726"/> </ValueDefinition> <FromProfile>false</FromProfile> <FromData>true</FromData> </ItemValueDefinition> </ItemValue> <ItemValue uid="19602052C053"> <Path>kgCO2PerPassengerKm</Path> <Name>kgCO2 Per Passenger Km</Name> <Value>0.0000</Value> <Unit/> <PerUnit/> <ItemValueDefinition uid="D7B4340D9404"> <Path>kgCO2PerPassengerKm</Path> <Name>kgCO2 Per Passenger Km</Name> <ValueDefinition created="2007-07-27 09:30:44.0" modified="2007-07-27 09:30:44.0" uid="996AE5477B3F"> <Name>kgCO2PerKm</Name> <ValueType>DECIMAL</ValueType> <Description/> <Environment uid="5F5887BCF726"/> </ValueDefinition> <FromProfile>false</FromProfile> <FromData>true</FromData> </ItemValueDefinition> </ItemValue> <ItemValue uid="C32B6E2EDCB0"> <Path>kgCO2PerPassengerJourney</Path> <Name>kgCO2 Per Passenger Journey</Name> <Value>81.2000</Value> <Unit/> <PerUnit/> <ItemValueDefinition uid="653828811D42"> <Path>kgCO2PerPassengerJourney</Path> <Name>kgCO2 Per Passenger Journey</Name> <ValueDefinition created="2007-07-27 09:30:44.0" modified="2007-08-01 08:57:31.0" uid="8CB8A1789CD6"> <Name>kgCO2PerJourney</Name> <ValueType>DECIMAL</ValueType> <Description/> <Environment uid="5F5887BCF726"/> </ValueDefinition> <FromProfile>false</FromProfile> <FromData>true</FromData> </ItemValueDefinition> </ItemValue> <ItemValue uid="F3C2C8046B54"> <Path>source</Path> <Name>Source</Name> <Value>defra/amee 2008</Value> <Unit/> <PerUnit/> <ItemValueDefinition uid="0F0592F05AAC"> <Path>source</Path> <Name>Source</Name> <ValueDefinition created="2007-07-27 09:30:44.0" modified="2007-07-27 09:30:44.0" uid="CCEB59CACE1B"> <Name>text</Name> <ValueType>TEXT</ValueType> <Description/> <Environment uid="5F5887BCF726"/> </ValueDefinition> <FromProfile>false</FromProfile> <FromData>true</FromData> </ItemValueDefinition> </ItemValue> </ItemValues> <Environment uid="5F5887BCF726"/> <ItemDefinition uid="441BF4BEA15B"/> <DataCategory uid="FBA97B70DBDF"> <Name>Generic</Name> <Path>generic</Path> </DataCategory> <Path>FFC7A05D54AD</Path> <Label>domestic,one way </Label> <StartDate>2007-08-01T09:00:41+01:00</StartDate> <EndDate/> </DataItem> <Path>/transport/plane/generic/FFC7A05D54AD</Path> <Choices> <Name>userValueChoices</Name> <Choices> <Choice> <Name>distance</Name> <Value/> </Choice> <Choice> <Name>IATACode1</Name> <Value/> </Choice> <Choice> <Name>IATACode2</Name> <Value/> </Choice> <Choice> <Name>journeys</Name> <Value/> </Choice> <Choice> <Name>lat1</Name> <Value>-999</Value> </Choice> <Choice> <Name>lat2</Name> <Value>-999</Value> </Choice> <Choice> <Name>long1</Name> <Value>-999</Value> </Choice> <Choice> <Name>long2</Name> <Value>-999</Value> </Choice> <Choice> <Name>numberOfPassengers</Name> <Value/> </Choice> <Choice> <Name>passengerClass</Name> <Value/> </Choice> </Choices> </Choices> <AmountPerMonth>0.000000</AmountPerMonth> </DataItemResource> </Resources>
Creating a Data Item
NOTE: This function is only accessible to Administrators.
- URL: http://{server}/data/{subcategory_path}
- Method: POST
- Response format: application/xml, application/json
- Response code: 201 Created
- Response body: A description of the created data item.
Updating a Data Item
NOTE: This function is only accessible to Administrators.
- URL: http://{server}/data/{subcategory_path}/{data_item_uid}
- Method: PUT
- Response format: application/xml, application/json
- Response code: 200 OK
- Response body: A description of the updated data item.
Deleting a Data Item
NOTE: This function is only accessible to Administrators.
- URL: http://{server}/data/{subcategory_path}/{data_item_uid}
- Method: DELETE
- Response code: 200 OK
Performing on-the-fly calculations
By supplying name / value pairs (such as distance=1000) in a GET request, the CO2 value can be retrieved without requiring the creation of a Profile. The name / value pairs must match the 'userValueChoices' list included in the response. If no parameters are specified, the amount will be 0.
NOTE: While calculations without profiles are possible, we strongly recommend that you use the Profile API to store your data.
- Using Profiles will mean that your data is stored and maintained in line with the underlying algorithms, so as they evolve, you don't need to re-code or re-calculate.
- Building your own Profile storage would be duplicating effort and replicating a core feature of what we offer as a service.
- The calls to the Data and Profile APIs are very similar, so the development overhead is no different, and lower than building your own storage system.
- The AMEE Profile framework is maintained to be parallel to the Data Items, so as these grow and evolve, you don't need to worry about keeping your data model in sync- AMEE manages that for you.
- AMEE has very advanced time-based tracking, which you need to use the Profiles for.
- Using AMEE as the store will allow much more detailed analytics and reporting over time.
- The business reasons are simple:
- Save time - reduce time to launch
- Save money - reduce development effort
- Reduce maintenance - reduce costs, and increase business continuity
AMEE strongly recommends that you do not build your application around on-the-fly calculations for these reasons, and rather use the Profile API to store your data permanently.
Related Resources
- Profile Item - Profile Items are "instances" of Data Items.
- Data Category - Data Items belong to a Data Category.
- Data Item Value - Data Items have many Data Item Values.
- Item Definition - Data Items are defined by an Item Definition.
