Upgrade Notice
Reporting APIs have been upgraded to reflect our new Report Builder capabilities. We strongly recommend you use the new 2.0 API for Reporting.
When requesting a report using the Report Queue or Report Save API methods you may specify fields, metrics, filters, sorting, rows, and offsets in the request_details JSON field. The exact parameters passed vary depending on which report is specified.
Getting the Report Definition and Field List
The available reports in the Buzz system can be found by GETting a view with "view_name":"reports".
curl -X GET "[host]/rest/view" -b cookies.txt -d '{"view_name":"reports"}'
This will provide a list of reports such as:
{
"success": true,
"payload": [
{
"report_id": 1,
"report_name": "performance_report",
"source_table": "performance_agg",
"object_type": "advertiser"
}
]
}
We need to know the fields available within the report, so we will GET again, this time from report_fields:
curl -X GET "[host]/rest/view" -b cookies.txt -d '{"view_name":"report_fields"}'
The results will include an array of parameters for each field (Example below truncated):
{
"success": true,
"payload":
[
{
"report_id": 1,
"field": "advertiser_id",
"search_type": "int",
"cast_type": "int",
"field_name": "advertiser",
"field_type": "field",
"field_order": 7,
"join_key": null,
"table_name": null
},
]
}
The meaning of these fields:
Field | Meaning |
|---|---|
report_id | The report_id |
field | Field name in the reporting database. Use this field for constructing your query. |
search_type | When used for filtering, what type of filter is expected. Types can include |
cast_type | Not currently used |
field_name | The name of the field in the resulting query (e.g. the "AS" portion of the query) |
field_type | Fields are either of type |
field_order | The order of the fields in the report |
join_key | Internal use |
table_name | Internal use |
The request_details JSON
Key | Description | Validation | Default |
|---|---|---|---|
field | Fields (sometimes called "dimensions") to include in the report. | Only fields associated with the report may be included. | All fields. |
filter | Fields and values to filter the results by (e.g. WHERE clause) | Only fields associated with the report may be used for filtering. | No filtering |
metric | Metrics to included and summed in the report. Metrics may not be used for filtering or sorting. | Only metrics associated with the report may be included. | All metrics. |
offset | Number of rows to offset results from the first results (e.g. for pagination through results) | Single numeric value | 0 |
rows | Number of rows to include in the report | Single numeric value. If sending the report results directly back from a GET request (i.e. | 50 |
sort_by | A field to sort the results by, along with the order (0=ascending). | Only fields associated with the report and included in the field key may be used for sorting. | First field in the report will be used for sorting. |
Examples
Specifying fields with the field key:
{"request_details":
{"field":
["advertiser_id","advertiser_name"]
}
}
Specifying fields and metrics with the metric key:
{"request_details":
{
"field":
["advertiser_id","advertiser_name"],
"metric":
["impressions","CPM"]
}
}
Sorting with sort_by (note it is a JSON object with the field name and the sort order):
{"request_details":
{
"field":
["advertiser_id","advertiser_name"],
"metric":
["impressions","CPM"],
"sort_by":
[
{"advertiser_id":1}
]
}
}
Filtering:
{"request_details":
{
"field":
["advertiser_id","advertiser_name"],
"metric":
["impressions","CPM"],
"filter":
[{"advertiser_id":1}]
}
}
Updated 8 months ago