Report Option Examples¶
Overview¶
- Timeframe and Granularity. Highly granular reports that cover long reporting periods (such as a year-to-date daily reports) are not supported in a single API call. If you require long reports that have a high-level of granularity, break up the report into several smaller reporting periods using multiple API calls.
Filter Options¶
The filterOptions array enables you to reduce the scope of your reports by identifying specific dimensions of data that are of interest. Dimensions may be be included in or exclude from reports.
The array comprises one or more Filter objects that consist of an includedValues object, an includedValues attribute, and a dimensionTypeId attribute. While the dimensionTypeId identifies dimension, the includedValues array identifies one or more dimension-value filters, and the isExcluded attribute determines whether the matching data is returned.
The dimension-value filters (includedValues array) enable you to reduce the size of your reports by specifying the dimensions returned or specifying the dimensions that are not returned.
{
"reportOption": {
"dimensionTypeIds": [ 5 ],
"filterOptions": [
{
"includeValues": [
{
"name": "France",
"id": "250"
}
],
"isExcluded": "false",
"dimensionTypeId": 19
}
],
...
Do not use the same dimension type ID to filter and group report data. The dimensionTypeId array identifies the dimensions used to group report data. The Filter objects’s dimensionTypeId attribute defines only a dimension to filter report data.
Instead, specify another dimension type ID in the dimensionTypeIds array and create a top-N report by specifying a limit attribute to reduce the scope of the report. For example, it is better to create a report that shows information about ad spend in the top ten cities rather than in all cities:
{
"dimensionTypeIds": [21],
"limitSpec": {
"columns": [
{
"metricTypeId": 44
}
],
"limit": 10,
}
}
To learn more, see top-n-reports.
Time Series Reports¶
“A time series is a series of data points indexed (or listed or graphed) in time order. Most commonly, a time series is a sequence taken at successive equally spaced points in time. Thus it is a sequence of discrete-time data. … Time series data have a natural temporal ordering.”
To specify a time series report, pass an dimensionTypeIds array in the payload body.
{
"reportOption": {
"dimensionTypeIds": [],
"metricTypeIds": [ 44, 1, 2 ],
...
}
}
If no dimension type IDs are specified, the number of rows returned in the report is determined by the intervalTypeId granularity.
Group By Report¶
“The Single Level Group By report displays issues returned from a specified issue filter of your choice, grouped by a specified field. For example, an issue filter can be created to retrieve all open issues for a particular version of a particular project. The Single Level Group By report can then be used to display these issues grouped by a specified field (e.g. Assignee).”
To define a group by report, specify one or more dimension type ID values in the dimensionTypeIds array.
EXAMPLE NEEDED
{
"reportOption": {
"dimensionTypeIds": [],
"metricTypeIds": [ 44, 1, 2 ],
...
}
}
The number of rows returned in the report, is the product of cardinality of the specified dimensions and the time-axis.
Top-N Reports¶
“Top-N reports allows you to collect and analyze data for each physical port on a switch. When Top-N reports start, they obtain statistics from the appropriate hardware counters and then go into sleep mode for a user-specified interval. When the interval ends, the reports obtain the current statistics from the same hardware counters, compare the current statistics from the earlier statistics, and store the difference.”
To define a top-N report, specify a single dimension type ID in the dimensionTypeIds array and a limitSpec value.
The object generates a report that returns the top ten cities with the greatest ad spend in the specified time period.
{
"dimensionTypeIds": [21],
"limitSpec": {
"columns": [
{
"metricTypeId": 44
}
],
"limit": 10,
}
}
The dimensionTypeIds array specifies a single dimension type ID (21), which groups report data by the City dimension.
The number of rows returned by the report is the product of the limit attribute value multiplied by the size of the reporting period.
