Beeswax

Reporting

❗️

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 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}]
   }
}

Updated 2 months ago

Reporting


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.