AMEE API / Data API / Drilldown Resources
Table of Contents
Overview
Drilldowns are a special resource available within every Data Category that contains Data Items.
As data items are identified by UIDs in API calls such as creating Profile Items, a way is required of translating human-readable choices into these UIDs. This is particularly important for large categories, such as UK car models, which can contain many thousands of data items.
Also, data item UIDs may be different on different AMEE platforms for the same item (dev, stage, and live). Because of this, data item UIDs should never be hardcoded into client apps. Instead, you should use the drilldown resource (which doesn't change) to obtain the UIDs, which can then be cached. Drilldowns may be safely hardcoded, so that you don't necessarily have to iterate each time if you already know which item you want to get to.
Usage
Drilldowns are performed via repeated accesses to the drilldown resource for each category. Each call to the resource will give a list of choices. The API client can then select one of these and provide it as a parameter to the next drilldown call. When the sequence of choices uniquely identifies one data item, a single UID choice is returned. This is the UID that should be used to refer to the chosen Data Item.
API Operations
Find a Data Item UID
- URL: http://{server}/data/{subcategory_path}/drill
- Method: GET
- Response code: 200 OK
- Response format: application/json, application/xml
- Response body: A set of available drilldown choices.
Parameters:
| API Version | Parameter | Description | Required |
| all | {choice_name} | Any number of choices and the values chosen. See below for an explanation. | No |
Example: JSON
First request
The first request made is to the main /drill resource, with no parameters. This gives the first choice.
Request:
GET /data/transport/car/generic/drill HTTP/1.1
Accept: application/json
Authtoken: {your_authtoken_goes_here}
Response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8
{
"dataCategory":{
"uid":"87E55DA88017",
"dataCategory":{
"uid":"1D95119FB149",
"name":"Car",
"path":"car"
},
"environment":{
"uid":"5F5887BCF726",
"itemsPerFeed":10,
"description":"",
"name":"AMEE",
"owner":"",
"path":"",
"itemsPerPage":10
},
"created":"2007-07-27 09:30:44.0",
"name":"Generic",
"path":"generic",
"itemDefinition":{
"uid":"123C4A18B5D6",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"name":"Car Generic",
"drillDown":"fuel,size",
"modified":"2007-07-27 09:30:44.0"
},
"modified":"2007-07-27 09:30:44.0"
},
"choices":{
"choices":[
{
"name":"average",
"value":"average"
},
{
"name":"cng",
"value":"cng"
},
{
"name":"diesel",
"value":"diesel"
},
{
"name":"lpg",
"value":"lpg"
},
{
"name":"petrol",
"value":"petrol"
},
{
"name":"petrol hybrid",
"value":"petrol hybrid"
}
],
"name":"fuel"
},
"selections":[],
"itemDefinition":{
"uid":"123C4A18B5D6"
}
}
Second request
When the client has made their selection, a second request is sent to get the next choice. The first choice is passed as a parameter.
Request:
GET /data/transport/car/generic/drill?fuel=diesel HTTP/1.1
Accept: application/json
Authtoken: {your_authtoken_goes_here}
Response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8
{
"dataCategory":{
"uid":"87E55DA88017",
"dataCategory":{
"uid":"1D95119FB149",
"name":"Car",
"path":"car"
},
"environment":{
"uid":"5F5887BCF726",
"itemsPerFeed":10,
"description":"",
"name":"AMEE",
"owner":"",
"path":"",
"itemsPerPage":10
},
"created":"2007-07-27 09:30:44.0",
"name":"Generic",
"path":"generic",
"itemDefinition":{
"uid":"123C4A18B5D6",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"name":"Car Generic",
"drillDown":"fuel,size",
"modified":"2007-07-27 09:30:44.0"
},
"modified":"2007-07-27 09:30:44.0"
},
"choices":{
"choices":[
{
"name":"large",
"value":"large"
},
{
"name":"medium",
"value":"medium"
},
{
"name":"small",
"value":"small"
}
],
"name":"size"
},
"selections":[
{
"name":"fuel",
"value":"diesel"
}
],
"itemDefinition":{
"uid":"123C4A18B5D6"
}
}
Third request
This item has only two choices, so once both are specified, the UID is returned. This is the final request.
Request:
GET /data/transport/car/generic/drill?fuel=diesel&size=large HTTP/1.1
Accept: application/json
Authtoken: {your_authtoken_goes_here}
Response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8
{
"dataCategory":{
"uid":"87E55DA88017",
"dataCategory":{
"uid":"1D95119FB149",
"name":"Car",
"path":"car"
},
"environment":{
"uid":"5F5887BCF726",
"itemsPerFeed":10,
"description":"",
"name":"AMEE",
"owner":"",
"path":"",
"itemsPerPage":10
},
"created":"2007-07-27 09:30:44.0",
"name":"Generic",
"path":"generic",
"itemDefinition":{
"uid":"123C4A18B5D6",
"environment":{
"uid":"5F5887BCF726"
},
"created":"2007-07-27 09:30:44.0",
"name":"Car Generic",
"drillDown":"fuel,size",
"modified":"2007-07-27 09:30:44.0"
},
"modified":"2007-07-27 09:30:44.0"
},
"choices":{
"choices":[
{
"name":"4F6CBCEE95F7",
"value":"4F6CBCEE95F7"
}
],
"name":"uid"
},
"selections":[
{
"name":"fuel",
"value":"diesel"
},
{
"name":"size",
"value":"large"
}
],
"itemDefinition":{
"uid":"123C4A18B5D6"
}
}
Example: XML
First request
The first request made is to the main /drill resource, with no parameters. This gives the first choice.
Request:
GET /data/transport/car/generic/drill 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> <DrillDownResource> <DataCategory uid="87E55DA88017"> <Name>Generic</Name> <Path>generic</Path> </DataCategory> <ItemDefinition uid="123C4A18B5D6"/> <Selections/> <Choices> <Name>fuel</Name> <Choices> <Choice> <Name>average</Name> <Value>average</Value> </Choice> <Choice> <Name>cng</Name> <Value>cng</Value> </Choice> <Choice> <Name>diesel</Name> <Value>diesel</Value> </Choice> <Choice> <Name>lpg</Name> <Value>lpg</Value> </Choice> <Choice> <Name>petrol</Name> <Value>petrol</Value> </Choice> <Choice> <Name>petrol hybrid</Name> <Value>petrol hybrid</Value> </Choice> </Choices> </Choices> </DrillDownResource> </Resources>
Second request
When the client has made their selection, a second request is sent to get the next choice. The first choice is passed as a parameter.
Request:
GET /data/transport/car/generic/drill?fuel=diesel 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> <DrillDownResource> <DataCategory uid="87E55DA88017"> <Name>Generic</Name> <Path>generic</Path> </DataCategory> <ItemDefinition uid="123C4A18B5D6"/> <Selections> <Choice> <Name>fuel</Name> <Value>diesel</Value> </Choice> </Selections> <Choices> <Name>size</Name> <Choices> <Choice> <Name>large</Name> <Value>large</Value> </Choice> <Choice> <Name>medium</Name> <Value>medium</Value> </Choice> <Choice> <Name>small</Name> <Value>small</Value> </Choice> </Choices> </Choices> </DrillDownResource> </Resources>
Third request
This item has only two choices, so once both are specified, the UID is returned. This is the final request.
Request:
GET /data/transport/car/generic/drill?fuel=diesel&size=large 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> <DrillDownResource> <DataCategory uid="87E55DA88017"> <Name>Generic</Name> <Path>generic</Path> </DataCategory> <ItemDefinition uid="123C4A18B5D6"/> <Selections> <Choice> <Name>fuel</Name> <Value>diesel</Value> </Choice> <Choice> <Name>size</Name> <Value>large</Value> </Choice> </Selections> <Choices> <Name>uid</Name> <Choices> <Choice> <Name>4F6CBCEE95F7</Name> <Value>4F6CBCEE95F7</Value> </Choice> </Choices> </Choices> </DrillDownResource> </Resources>
