AMEE API / URL Architecture

Overview

The base URL is supplied to you along with your access credentials.

Note: UIDs (e.g. '2B07C4082E5E') and categories shown on this page are dummy.

Data Resource Structure

All raw data can be accessed and manipulated via the API. Each node in the resource structure has a unique URL organised in a hierarchy.

Paging

Paging is used when AMEE needs to give a lengthy response to a query. So, for example, /data/home/heating contains a very large number of data items. The response will only show the first page of these. To see the next page, use data/home/heating?page=2. The response will contain these xml elements [or json equivalents] <CurrentPage?>, <PreviousPage?>, <NextPage?>, <LastPage?> to help with navigating the data.

Structure of Data resources

  1. /data
  2. /data/{itemPath|categoryPath}
  3. /data/{categoryPath}/
  4. /data/{categoryPath}/drill
  5. /data/{categoryPath}/{itemPath}
  6. /data/{categoryPath}/{itemPath}/{valuePath}
  7. /data/{categoryPath}/{categoryPath}

Notes on this structure

  1. Root Data Category with response containing list of children.
  2. Potential children of any Data Category are addressed by their path.
  3. A top level Data Category with a list of its children.
  4. A drill down resource for this Data Category.
  5. A Data Item with list of its Data Item Values.
  6. An Item Value.
  7. Further child Data Categories.

Concrete examples

Below is a nested structure leading to a Data Item describing the type of fuel for a home.

  • /data/
  • /data/home
  • /data/home/domicile
  • /data/home/domicile/drill
  • /data/home/domicile/8049AACD53C9
  • /data/home/domicile/8049AACD53C9/homeFuel

Profile resource structure

Profile resources mirror the Data Category structure of the CO2 data. Data Category paths are prefixed by /profiles and the profile key. Profile Items are addressed by their UID with child Item Values addressed by their Item Value Definition path.

Structure of Profile resources

  1. /profiles
  2. /profiles/{profileKey}
  3. /profiles/{profileKey}/{categoryPath|itemPath}
  4. /profiles/{profileKey}/{categoryPath}
  5. /profiles/{profileKey}/{categoryPath}/{itemPath}
  6. /profiles/{profileKey}/{categoryPath}/{itemPath}/{valuePath}
  7. /profiles/{profileKey}/{categoryPath}/{categoryPath}

Notes on this structure

  1. A list of Profiles.
  2. Home for a Profile listing its children.
  3. Potential children of Profiles and Profile Categories are addressed by their path.
  4. A Profile Category containing Profile Items and/or further Profile Categories.
  5. A Profile Item with list of its Item Values.
  6. An Item Value belonging to a Profile Item.
  7. A nested Profile Category. Further nesting of paths as described above is possible.

Concrete examples

Below is listed the nested structure leading to a Profile Item describing a type of home for an individual.

  • /profiles/
  • /profiles/2B07C4082E5E
  • /profiles/2B07C4082E5E/home
  • /profiles/2B07C4082E5E/home/domicile/4F7A8289D7A9