"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

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:

FieldMeaning
report_idThe report_id
fieldField name in the reporting database. Use this field for constructing your query.
search_typeWhen used for filtering, what type of filter is expected. Types can include int, string, double, date
cast_typeNot currently used
field_nameThe name of the field in the resulting query (e.g. the "AS" portion of the query)
field_typeFields are either of type field or metric. Only fields with type field can be used for filtering or sorting.
field_orderThe order of the fields in the report
join_keyInternal use
table_nameInternal use

The request_details JSON

KeyDescriptionValidationDefault
fieldFields (sometimes called "dimensions") to include in the report.Only fields associated with the report may be included.All fields.
filterFields and values to filter the results by (e.g. WHERE clause)Only fields associated with the report may be used for filtering.No filtering
metricMetrics 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.
offsetNumber of rows to offset results from the first results (e.g. for pagination through results)Single numeric value0
rowsNumber of rows to include in the reportSingle 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_byA 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}]
   }
}