AMEE API / AMEE Data API / Data Category Drill Down Resource

Overview

The Data Category Drill Down resource is available at ‘/drill’ below each Data Category that contains Data Items. This resource is designed to make it easier to find Data Items where there are many potential choices. All Item Definitions define a drill down sequence which is used to narrow down the potential Data Item choices.

As an example, the drill down sequence for the 'Domicile' Data Category is 'homeDwellingType, homeSubType, homeNoOfBedrooms, homeFuel'.

It is up to the developer to supply user selections to the API so that further choices can be returned. Once all potential choices have been exhausted a list of Data Items will be returned.

The UID from these Data Items can be used in further API calls (such as adding a Profile Item).

Example JSON Response

{"itemDefinition":{"modified":"2007-02-19 10:43:54.0","created":"2007-02-19 10:43:54.0","uid":"DDFFEF54F08D","environment":{"uid":"812244FE5A13"},"name":"Lighting"},"dataCategory":{"modified":"2007-02-19 10:43:55.0","created":"2007-02-19 10:43:54.0","uid":"3EECE400BB13","path":"lighting","name":"Lighting"},"selections":[{"value":"lightbulb","name":"lightingAppliance"},{"value":"normal","name":"lightingType"}],"choices":{"choices":[{"value":"100W","name":"100W"},{"value":"40W","name":"40W"},{"value":"60W","name":"60W"},{"value":"typical","name":"typical"}],"name":"lightingSubType"}}

Example XML Response

The XML below is returned when requesting the drill down for a Data Category. The are two main lists; 'Selections' are choices selected by previous requests and 'Choices' are potential choices for narrowing the drill down. This first example contains the initial top level choices list for ‘/data/home/domicile/drill’. Note that the selections node is currently empty.

<?xml version="1.0" encoding="UTF-8"?>
<Resources>
    <DrillDownResource>
        <DataCategory uid="ABBB99F484C0"/>
        <ItemDefinition uid="EE7331423F26"/>
        <Selections/>
        <Choices>
            <name>homeDwellingType</name>
            <Choice>
                <name>bungalow</name>
                <value>bungalow</value>
            </Choice>
            <Choice>
                <name>flat</name>
                <value>flat</value>
            </Choice>
            <Choice>
                <name>house</name>
                <value>house</value>
            </Choice>
        </Choices>
    </DrillDownResource>
</Resources>

The next example shows a further set of choices based on a selection having been made. This response would have been produced by a request containing parameters. For example: ‘/data/home/domicile/drill?homeDwellingType=house’.

<?xml version="1.0" encoding="UTF-8"?>
<Resources>
    <DrillDownResource>
        <DataCategory uid="ABBB99F484C0"/>
        <ItemDefinition uid="EE7331423F26"/>
        <Selections>
            <Choice>
                <name>homeDwellingType</name>
                <value>house</value>
            </Choice>
        </Selections>
        <Choices>
            <name>homeSubType</name>
            <Choice>
                <name>detached</name>
                <value>detached</value>
            </Choice>
            <Choice>
                <name>end-terrace</name>
                <value>end-terrace</value>
            </Choice>
            <Choice>
                <name>mid-terrace</name>
                <value>mid-terrace</value>
            </Choice>
            <Choice>
                <name>semi-detached</name>
                <value>semi-detached</value>
            </Choice>
        </Choices>
    </DrillDownResource>
</Resources>

The last example shows the XML returned when all potential Data Category choices have been exhausted. The only choice remaining is the UID(s) for the Data Item(s) at the bottom of this drill down. This example was produced by requesting '/data/home/domicile/drill?homeDwellingType=house&homeSubType=detached&homeNoOfBedrooms=2%20bedroom&homeFuel=coal'.

<?xml version="1.0" encoding="UTF-8"?>
<Resources>
    <DrillDownResource>
        <DataCategory uid="ABBB99F484C0"/>
        <ItemDefinition uid="EE7331423F26"/>
        <Selections>
            <Choice>
                <name>homeDwellingType</name>
                <value>house</value>
            </Choice>
            <Choice>
                <name>homeSubType</name>
                <value>detached</value>
            </Choice>
            <Choice>
                <name>homeNoOfBedrooms</name>
                <value>2 bedroom</value>
            </Choice>
            <Choice>
                <name>homeFuel</name>
                <value>coal</value>
            </Choice>
        </Selections>
        <Choices>
            <name>uid</name>
            <Choice>
                <name>7C80A26FADE8</name>
                <value>7C80A26FADE8</value>
            </Choice>
        </Choices>
    </DrillDownResource>
</Resources>

Supported HTTP Methods

• GET - View the drill down choices and selections for the Data Category represented in the URL.

Parameter Definition

Parameter	Definition	Methods
{choiceName}	The name of a choice detailed in the choices list.	GET
{choiceValue}	The value of a choice detailed in the choices list.	GET