AMEE API / Profile API / Profile Item Value

Overview

Profile Item Values belong to Profile Items. Each Profile Item Value represents a distinct value such as 'distance' or 'quantity'. Profile Item Values are defined by an Item Value Definition. Profile Item Values are similar in structure to Data Item Values.

See also: AMEE Concepts, AMEE Profile API

Properties

API Version	Property	Definition
all	value	The value of this Profile Item Value.
all	path	The path component for this Profile Item Value.
all	name	The name of this Profile Item Value.
>= 2.0	unit	The non-time unit of this Profile Item Value, e.g. "kg"
>= 2.0	perUnit	The time unit of this Profile Item Value, e.g. "month"

See also: Common Properties

API Operations

Viewing Profile Item Values

• URL:  http://{server}/profiles/{profile_uid}/{category_path}/{profile_item_uid}/{profile_item_value_path}
• Method: GET
• Response format: application/xml, application/json
• Response code: 200 OK
• Response body: A description of the profile item value.

Parameters:

API Version	Parameter	Definition	Required
>= 2.0	returnUnit	Units to return amount in (mass). For example, specifying returnUnit=lb would return lb/year instead of kg/year. See Units for more details.	No
>= 2.0	returnPerUnit	Units to return amount in (time). For example, specifying returnPerUnit=month would return kg/month instead of kg/year. See Units for more details.	No

Example: AMEE 2 JSON

Request:

GET /profiles/85EDF7C8D10C/home/energy/quantity/8BA555AEC6F3/energyConsumption HTTP/1.1
Accept: application/json
Authtoken: {your_authtoken_goes_here}

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "apiVersion":"2.0",
  "itemValue":{
    "itemValueDefinition":{
      "perUnit":"year",
      "uid":"BFD215C4CAB1",
      "unit":"kWh",
      "name":"Energy Consumption",
      "path":"energyConsumption",
      "valueDefinition":{
        "uid":"45433E48B39F",
        "environment":{
          "uid":"5F5887BCF726"
        },
        "created":"2007-07-27 09:30:44.0",
        "description":"",
        "name":"amount",
        "valueType":"DECIMAL",
        "modified":"2007-07-27 09:30:44.0"
      }
    },
    "perUnit":"year",
    "uid":"6BA6E8C3ACE3",
    "unit":"kWh",
    "created":"2009-03-24 13:58:00.0",
    "item":{    
      "uid":"8BA555AEC6F3",
      "itemValues":[...]
    },
    "name":"Energy Consumption",
    "value":"10",
    "path":"energyConsumption",
    "displayPath":"energyConsumption",
    "displayName":"Energy Consumption",
    "modified":"2009-03-24 13:58:00.0"
  },
  "path":"/home/energy/quantity/8BA555AEC6F3/energyConsumption",
  "actions":{
    "allowCreate":true,
    "allowView":true,
    "allowList":true,
    "allowModify":true,
    "allowDelete":true
  },
  "profile":{
    "uid":"85EDF7C8D10C"
  }
}

Example: AMEE 2 XML

Request:

GET /profiles/92B44839FBF4/home/energy/quantity/5AB81A30998D/energyConsumption 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 xmlns="http://schemas.amee.cc/2.0">
  <ProfileItemValueResource>
    <ItemValue Created="2009-03-24 14:17:33.0" Modified="2009-03-24 14:17:33.0" uid="D393D0268191">
      <Path>energyConsumption</Path>
      <Name>Energy Consumption</Name>
      <Value>10</Value>
      <Unit>kWh</Unit>
      <PerUnit>year</PerUnit>
      <ItemValueDefinition uid="BFD215C4CAB1">
        <Path>energyConsumption</Path>
        <Name>Energy Consumption</Name>
        <ValueDefinition created="2007-07-27 09:30:44.0" modified="2007-07-27 09:30:44.0" uid="45433E48B39F">
          <Name>amount</Name>
          <ValueType>DECIMAL</ValueType>
          <Description/>
          <Environment uid="5F5887BCF726"/>
        </ValueDefinition>
        <Unit>kWh</Unit>
        <PerUnit>year</PerUnit>
        <FromProfile>true</FromProfile>
        <FromData>false</FromData>
      </ItemValueDefinition>
      <ProfileItem uid="5AB81A30998D"/>
    </ItemValue>
    <Path>/home/energy/quantity/5AB81A30998D/energyConsumption</Path>
    <Profile uid="92B44839FBF4"/>
  </ProfileItemValueResource>
</Resources>

Example: AMEE 1 JSON

Request:

GET /profiles/9A25DCBF701A/home/energy/quantity/2C01063EA9E0/kWhPerMonth HTTP/1.1
Accept: application/json
Authtoken: {your_authtoken_goes_here}

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=ISO-8859-1

{
  "path":"/home/energy/quantity/2C01063EA9E0/kWhPerMonth",
  "profile":{
    "uid":"9A25DCBF701A"
  },
  "itemValue":{
    "item":{
      "uid":"2C01063EA9E0"
    },
    "modified":"2009-03-24 13:57:18.0",
    "created":"2009-03-24 13:57:18.0",
    "value":"10",
    "uid":"F714E0B2F986",
    "path":"kWhPerMonth",
    "name":"kWh Per Month",
    "itemValueDefinition":{
      "valueDefinition":{
        "valueType":"DECIMAL",
        "uid":"26A5C97D3728",
        "name":"kWh"
      },
      "uid":"4DF458FD0E4D",
      "path":"kWhPerMonth",
      "name":"kWh Per Month"
    }
  }
}

Example: AMEE 1 XML

Request:

GET /profiles/3035855E18D1/home/energy/quantity/4E505E81E238/kWhPerMonth HTTP/1.1
Accept: application/xml
Authtoken: {your_authtoken_goes_here}

Response:

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Resources>
  <ProfileItemValueResource>
    <ItemValue Created="2009-03-24 13:57:16.0" Modified="2009-03-24 13:57:16.0" uid="4E2D02F176CE">
      <Path>kWhPerMonth</Path>
      <Name>kWh Per Month</Name>
      <Value>10</Value>
      <ItemValueDefinition uid="4DF458FD0E4D">
        <Path>kWhPerMonth</Path>
        <Name>kWh Per Month</Name>
        <FromProfile>true</FromProfile>
        <FromData>false</FromData>
        <ValueDefinition uid="26A5C97D3728">
          <Name>kWh</Name>
          <ValueType>DECIMAL</ValueType>
        </ValueDefinition>
      </ItemValueDefinition>
      <ProfileItem uid="4E505E81E238"/>
    </ItemValue>
    <Path>/home/energy/quantity/4E505E81E238/kWhPerMonth</Path>
    <Profile uid="3035855E18D1"/>
  </ProfileItemValueResource>
</Resources>

Updating Values

• URL:  http://{server}/profiles/{profile_uid}/{category_path}/{profile_item_uid}/{profile_item_value_path}
• Method: PUT
• Request format: application/x-www-form-urlencoded
• Response format: application/xml, application/json
• Response code: 200 OK
• Response body: AMEE 2: None unless "representation=full" is specified. AMEE 1: Representation of created item.

Parameters:

API Version	Parameter	Definition	Required
all	value	The value that should be stored.	Yes
>= 2.0	unit	The non-time unit for this value, e.g. "kg".	No
>= 2.0	perUnit	The time unit for this value, e.g. "month".	No
>= 2.0	representation	What representation of the object should be returned in the response to this request? Set to 'full' to get a representation back, otherwise nothing will be returned in the response body.	No

Example: AMEE 2 JSON

PUT /profiles/85EDF7C8D10C/home/energy/quantity/8BA555AEC6F3/energyConsumption HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authtoken: {your_authtoken_goes_here}

perUnit=week&value=42.0&unit=J

Response:

HTTP/1.1 200 OK
Content-Type: text/plain

Example: AMEE 2 XML

Request:

PUT /profiles/92B44839FBF4/home/energy/quantity/5AB81A30998D/energyConsumption HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
Authtoken: {your_authtoken_goes_here}

perUnit=week&value=42.0&unit=J

Response:

HTTP/1.1 200 OK
Content-Type: text/plain

Example: AMEE 1 JSON

Request:

PUT /profiles/9A25DCBF701A/home/energy/quantity/2C01063EA9E0/kWhPerMonth HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authtoken: {your_authtoken_goes_here}

value=42.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=ISO-8859-1

{
  "path":"/home/energy/quantity/2C01063EA9E0/kWhPerMonth",
  "profile":{
    "uid":"9A25DCBF701A"
  },
  "itemValue":{
    "item":{
      "uid":"2C01063EA9E0"
    },
    "modified":"Tue Mar 24 13:57:19 GMT 2009",
    "created":"2009-03-24 13:57:18.0",
    "value":"42.0",
    "uid":"F714E0B2F986",
    "path":"kWhPerMonth",
    "name":"kWh Per Month",
    "itemValueDefinition":{
      "valueDefinition":{
        "valueType":"DECIMAL",
        "uid":"26A5C97D3728",
        "name":"kWh"
      },
      "uid":"4DF458FD0E4D",
      "path":"kWhPerMonth",
      "name":"kWh Per Month"
    }
  }
}

Example: AMEE 1 XML

Request:

PUT /profiles/3035855E18D1/home/energy/quantity/4E505E81E238/kWhPerMonth HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
Authtoken: {your_authtoken_goes_here}

value=42.0

Response:

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Resources>
  <ProfileItemValueResource>
    <ItemValue Created="2009-03-24 13:57:16.0" Modified="Tue Mar 24 13:57:17 GMT 2009" uid="4E2D02F176CE">
      <Path>kWhPerMonth</Path>
      <Name>kWh Per Month</Name>
      <Value>42.0</Value>
      <ItemValueDefinition uid="4DF458FD0E4D">
        <Path>kWhPerMonth</Path>
        <Name>kWh Per Month</Name>
        <FromProfile>true</FromProfile>
        <FromData>false</FromData>
        <ValueDefinition uid="26A5C97D3728">
          <Name>kWh</Name>
          <ValueType>DECIMAL</ValueType>
        </ValueDefinition>
      </ItemValueDefinition>
      <ProfileItem uid="4E505E81E238"/>
    </ItemValue>
    <Path>/home/energy/quantity/4E505E81E238/kWhPerMonth</Path>
    <Profile uid="3035855E18D1"/>
  </ProfileItemValueResource>
</Resources>

Related Resources

• Profile Item - Each Profile Item Value belongs to a Profile Item.
• Item Value Definition - Profile Item Values are defined by Item Value Definitions.