With Winter ’14 the new Analytics API turns GA. This RESTful style of API consumes standard API call limits, uses OAuth authentication and JSON request/response message formats (representations).
The key functionality of the Analytics API is the execution of reports (in synchronous or asynchronous modes), the application of dynamic filtering and the inspection of report metadata.
Note, in experimenting/testing any of the RESTful APIs (Force.com REST API, Chatter REST API, Analytics API etc.) the Apigee Salesforce API Consoles are an extremely convenient and useful tool – screenshot below.
Core API Resources
- Report metadata (GET /services/data/v29.0/analytics/reports/report_ID/describe)
- List recently viewed reports (GET /services/data/v29.0/analytics/reports/list)
Note to obtain a full list of reports the standard REST API should be used to query the Report resource (via Soql).
- Synchronous report execution (/services/data/v29.0/analytics/reports/report_ID)
GET for a simple execution (add includeDetail=true to the Querystring if required)
POST to apply filtering.
- Asynchronous report execution (/services/data/v29.0/analytics/reports/report_ID/instances) – POST to request an execution.
GET to retrieve a list of the execution instances.
GET to the ../instances/instance_ID to request the results of a single execution.
- Fact Maps
The JSON message format for a report execution, synchronous or asynchronous, provides the detail and summary data in a Fact Map structure. In short, the keys provided in the structured groupings (across and down) data provided in the embedded report metadata are concatenated to provide a composite lookup key to detail row (hasDetailRows response flag indicates the existence of detail rows) and aggregate data held in the data map.
For more on Fact Maps refer to the “Decode the Fact Map” section in the Analytics API Reference.
Use Cases
The Analytics API is a long awaited key enabler for mobile/tablet analytics use cases, allowing on-platform reports to be executed and the results accessed in a constrained-device friendly lightweight format. Without this API mobile app developers have been limited to the execution of Soql queries via the standard REST API. With the API such developers have access to the recently viewed reports for a specific user, the report metadata, the ability to execute reports and then to pass the report results up to the graphics library of choice using a standard data format.
Outside of the mobile context, the API offers the same patterns to composite applications such as complementary web applications and 3rd party tools where datasets can be defined on-platform using reports (by end-users perhaps) and the data picked up for services such as mass email marketing etc.
Key Limitations
- 500 synchronous report executions per hour
- 1200 synchronous report execution requests per hour
- Asynchronous report results are available for 24 hours from execution
Report Response Example – Matrix Report
HTTP/1.1 200 OK
Sforce-Limit-Info:api-usage=21/5000000
Date:Sat, 28 Sep 2013 18:30:16 GMT
Content-Length:8705
Content-Type:application/json;charset=UTF-8
{
"hasDetailRows": false,
"attributes": {
"describeUrl": "/services/data/v29.0/analytics/reports/00O300000041iFQEAX/describe",
"instancesUrl": "/services/data/v29.0/analytics/reports/00O300000041iFQEAX/instances",
"type": "Report",
"reportId": "00O300000041iFQEAX",
"reportName": "Example Report"
},
"groupingsDown": {
"groupings": [
{
"value": "001Q000000PUcCtIAX",
"key": "0",
"groupings": [
{
"value": "2013-08-28",
"key": "0_0",
"groupings": [],
"label": "2013/08/28 - 2013/09/03"
}
],
"label": "New Business"
},
{
"value": "001Q000000Q0wLMIAX",
"key": "1",
"groupings": [
{
"value": "2013-09-18",
"key": "1_0",
"groupings": [],
"label": "2013/09/18 - 2013/09/24"
}
],
"label": "Existing Business"
},
{
"value": "001Q000000OwobqIAX",
"key": "2",
"groupings": [
{
"value": "2013-07-31",
"key": "2_0",
"groupings": [],
"label": "2013/07/31 - 2013/08/06"
}
],
"label": "Prospects"
}
]
},
"groupingsAcross": {
"groupings": [
{
"value": "Product Sales",
"key": "0",
"groupings": [
{
"value": "a0AQ00000054Q0uMAX",
"key": "0_0",
"groupings": [],
"label": "Product A"
},
{
"value": "a0AQ0000004YV8xMAX",
"key": "0_1",
"groupings": [],
"label": "Product B"
}
],
"label": "Product Sales"
},
{
"value": "Services",
"key": "1",
"groupings": [
{
"value": "a0AQ0000005G0OpMAX",
"key": "1_0",
"groupings": [],
"label": "Service A"
}
],
"label": "Services"
}
]
},
"reportMetadata": {
"name": "Example Report",
"id": "00O300000041iFQEAX",
"aggregates": [
"RowCount"
],
"groupingsDown": [
{
"name": "Client__c.Name",
"sortOrder": "Asc",
"dateGranularity": "None"
},
{
"name": "Projection__c.Date__c",
"sortOrder": "Asc",
"dateGranularity": "Week"
}
],
"groupingsAcross": [
{
"name": "MyProduct__c.Classification__c",
"sortOrder": "Asc",
"dateGranularity": "None"
},
{
"name": "MyProduct__c.Name",
"sortOrder": "Asc",
"dateGranularity": "None"
}
],
"reportType": {
"type": "MyProduct_CRT__c",
"label": "My Product CRT"
},
"reportBooleanFilter": null,
"reportFilters": [],
"detailColumns": [],
"reportFormat": "MATRIX",
"currency": null,
"developerName": "Example_Report"
},
"factMap": {
"1_0!T": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"0!1_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"1!0_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"1!0_1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"2!T": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"0!0_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"0!0_1": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"1!1": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"T!1": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"1!0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"2_0!1_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"2_0!0_1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"0_0!1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"0_0!0": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"2_0!0_0": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"T!0": {
"aggregates": [
{
"value": 7,
"label": "7"
}
]
},
"1_0!1_0": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"2_0!0": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"2_0!1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"1_0!0_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"1_0!0_1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"0!1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"T!1_0": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"0!0": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"1_0!1": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"1_0!0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"2!1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"2!0_1": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"2!0_0": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"0_0!0_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"0_0!0_1": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"2!0": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"T!T": {
"aggregates": [
{
"value": 8,
"label": "8"
}
]
},
"0!T": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"1!T": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"2!1_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
},
"0_0!T": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"T!0_0": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"1!1_0": {
"aggregates": [
{
"value": 1,
"label": "1"
}
]
},
"T!0_1": {
"aggregates": [
{
"value": 2,
"label": "2"
}
]
},
"2_0!T": {
"aggregates": [
{
"value": 5,
"label": "5"
}
]
},
"0_0!1_0": {
"aggregates": [
{
"value": 0,
"label": "0"
}
]
}
},
"allData": true
}
