Reporting (Deprecated)

❗️
Upgrade Notice
Reporting has been upgraded and these APIs are no longer supported. You must 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 `int`, `string`, `double`, `date`
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` or `metric`. Only fields with type `field` can be used for filtering or sorting.
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. `"report_format":"none"`) a 1,500 record limit is imposed. If the report results will be saved in a file, (e.g. `"report_format":"xls"`) the limit is 30,000 records.	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}]
   }
}