{"_id":"56fd4a1327b4321900186f4e","user":"56c39c05bc41330d009f25d7","version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"__v":2,"githubsync":"","parentDoc":null,"project":"56c35c56c0c4630d004e864c","category":{"_id":"56fd3956caad892200847bce","__v":0,"project":"56c35c56c0c4630d004e864c","version":"56c35c56c0c4630d004e864f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-31T14:51:02.977Z","from_sync":false,"order":1,"slug":"buzz-json-objects","title":"Buzz JSON Objects"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-31T16:02:27.172Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"When requesting a report using the [Report Queue](doc:report-queue) or [Report Save](doc: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. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting the Report Definition and Field List\"\n}\n[/block]\nThe available reports in the Buzz system can be found by GETting a `view` with `\"view_name\":\"reports\"`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/view\\\" -b cookies.txt -d '{\\\"view_name\\\":\\\"reports\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThis will provide a list of reports such as:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"payload\\\": [\\n        {\\n            \\\"report_id\\\": 1,\\n            \\\"report_name\\\": \\\"performance_report\\\",\\n            \\\"source_table\\\": \\\"performance_agg\\\",\\n            \\\"object_type\\\": \\\"advertiser\\\"\\n        }\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nWe need to know the fields available within the report, so we will GET again, this time from report_fields:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/view\\\" -b cookies.txt -d '{\\\"view_name\\\":\\\"report_fields\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe results will include an array of parameters for each field (Example below truncated):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"payload\\\":\\n    [\\n        {\\n            \\\"report_id\\\": 1,\\n            \\\"field\\\": \\\"advertiser_id\\\",\\n            \\\"search_type\\\": \\\"int\\\",\\n            \\\"cast_type\\\": \\\"int\\\",\\n            \\\"field_name\\\": \\\"advertiser\\\",\\n            \\\"field_type\\\": \\\"field\\\",\\n            \\\"field_order\\\": 7,\\n            \\\"join_key\\\": null,\\n            \\\"table_name\\\": null\\n        },\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe meaning of these fields:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Meaning\",\n    \"0-0\": \"report_id\",\n    \"0-1\": \"The report_id\",\n    \"1-0\": \"field\",\n    \"1-1\": \"Field name in the reporting database. Use this field for constructing your query.\",\n    \"2-0\": \"search_type\",\n    \"2-1\": \"When used for filtering, what type of filter is expected. Types can include `int`, `string`, `double`, `date`\",\n    \"3-0\": \"cast_type\",\n    \"3-1\": \"Not currently used\",\n    \"4-0\": \"field_name\",\n    \"4-1\": \"The name of the field in the resulting query (e.g. the \\\"AS\\\" portion of the query)\",\n    \"5-0\": \"field_type\",\n    \"5-1\": \"Fields are either of type `field` or `metric`. Only fields with type `field` can be used for filtering or sorting.\",\n    \"6-0\": \"field_order\",\n    \"6-1\": \"The order of the fields in the report\",\n    \"7-0\": \"join_key\",\n    \"7-1\": \"Internal use\",\n    \"8-0\": \"table_name\",\n    \"8-1\": \"Internal use\"\n  },\n  \"cols\": 2,\n  \"rows\": 9\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"The request_details JSON\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Validation\",\n    \"0-0\": \"field\",\n    \"0-1\": \"Fields (sometimes called \\\"dimensions\\\") to include in the report.\",\n    \"0-2\": \"Only fields associated with the report may be included.\",\n    \"h-3\": \"Default\",\n    \"h-4\": \"Blank\",\n    \"0-3\": \"All fields.\",\n    \"1-0\": \"filter\",\n    \"1-1\": \"Fields and values to filter the results by (e.g. WHERE clause)\",\n    \"1-2\": \"Only fields associated with the report may be used for filtering.\",\n    \"1-3\": \"No filtering\",\n    \"2-0\": \"metric\",\n    \"2-1\": \"Metrics to included and summed in the report. Metrics may not be used for filtering or sorting.\",\n    \"2-2\": \"Only metrics associated with the report may be included.\",\n    \"2-3\": \"All metrics.\",\n    \"3-0\": \"offset\",\n    \"3-1\": \"Number of rows to offset results from the first results (e.g. for pagination through results)\",\n    \"3-2\": \"Single numeric value\",\n    \"3-3\": \"0\",\n    \"4-0\": \"rows\",\n    \"4-1\": \"Number of rows to include in the report\",\n    \"4-2\": \"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.\",\n    \"4-3\": \"50\",\n    \"5-0\": \"sort_by\",\n    \"5-1\": \"A field to sort the results by, along with the order (0=ascending).\",\n    \"5-2\": \"Only fields associated with the report and included in the field key may be used for sorting.\",\n    \"5-3\": \"First field in the report will be used for sorting.\"\n  },\n  \"cols\": 4,\n  \"rows\": 6\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\nSpecifying fields with the `field` key:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"request_details\\\":\\n \\t{\\\"field\\\":\\n   [\\\"advertiser_id\\\",\\\"advertiser_name\\\"]\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nSpecifying fields and metrics with the `metric` key:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"request_details\\\":\\n \\t{\\n    \\\"field\\\":\\n   \\t\\t[\\\"advertiser_id\\\",\\\"advertiser_name\\\"],\\n  \\t\\\"metric\\\":\\n   \\t\\t[\\\"impressions\\\",\\\"CPM\\\"]\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nSorting with `sort_by` (note it is a JSON object with the field name and the sort order):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"request_details\\\":\\n {\\n  \\t\\\"field\\\":\\n  \\t\\t[\\\"advertiser_id\\\",\\\"advertiser_name\\\"],\\n  \\t\\\"metric\\\":\\n   \\t\\t[\\\"impressions\\\",\\\"CPM\\\"],\\n \\t\\t\\\"sort_by\\\":\\n   \\t\\t[\\n        {\\\"advertiser_id\\\":1}\\n      ]\\n }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nFiltering:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"request_details\\\":\\n\\t{\\n  \\t\\\"field\\\":\\n    \\t[\\\"advertiser_id\\\",\\\"advertiser_name\\\"],\\n    \\\"metric\\\":\\n    \\t[\\\"impressions\\\",\\\"CPM\\\"],\\n\\t\\t\\\"filter\\\":\\n    \\t[{\\\"advertiser_id\\\":1}]\\n   }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"reporting","type":"basic","title":"Reporting"}

Buzz API Overview

Buzz Concepts

Buzz API Reference

Buzz JSON Objects

Stinger

Release Notes

Reporting

When requesting a report using the [Report Queue](doc:report-queue) or [Report Save](doc: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. [block:api-header] { "type": "basic", "title": "Getting the Report Definition and Field List" } [/block] The available reports in the Buzz system can be found by GETting a `view` with `"view_name":"reports"`. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/view\" -b cookies.txt -d '{\"view_name\":\"reports\"}'", "language": "curl" } ] } [/block] This will provide a list of reports such as: [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"payload\": [\n {\n \"report_id\": 1,\n \"report_name\": \"performance_report\",\n \"source_table\": \"performance_agg\",\n \"object_type\": \"advertiser\"\n }\n ]\n}", "language": "json" } ] } [/block] We need to know the fields available within the report, so we will GET again, this time from report_fields: [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/view\" -b cookies.txt -d '{\"view_name\":\"report_fields\"}'", "language": "curl" } ] } [/block] The results will include an array of parameters for each field (Example below truncated): [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"payload\":\n [\n {\n \"report_id\": 1,\n \"field\": \"advertiser_id\",\n \"search_type\": \"int\",\n \"cast_type\": \"int\",\n \"field_name\": \"advertiser\",\n \"field_type\": \"field\",\n \"field_order\": 7,\n \"join_key\": null,\n \"table_name\": null\n },\n ]\n}", "language": "json" } ] } [/block] The meaning of these fields: [block:parameters] { "data": { "h-0": "Field", "h-1": "Meaning", "0-0": "report_id", "0-1": "The report_id", "1-0": "field", "1-1": "Field name in the reporting database. Use this field for constructing your query.", "2-0": "search_type", "2-1": "When used for filtering, what type of filter is expected. Types can include `int`, `string`, `double`, `date`", "3-0": "cast_type", "3-1": "Not currently used", "4-0": "field_name", "4-1": "The name of the field in the resulting query (e.g. the \"AS\" portion of the query)", "5-0": "field_type", "5-1": "Fields are either of type `field` or `metric`. Only fields with type `field` can be used for filtering or sorting.", "6-0": "field_order", "6-1": "The order of the fields in the report", "7-0": "join_key", "7-1": "Internal use", "8-0": "table_name", "8-1": "Internal use" }, "cols": 2, "rows": 9 } [/block] [block:api-header] { "type": "basic", "title": "The request_details JSON" } [/block] [block:parameters] { "data": { "h-0": "Key", "h-1": "Description", "h-2": "Validation", "0-0": "field", "0-1": "Fields (sometimes called \"dimensions\") to include in the report.", "0-2": "Only fields associated with the report may be included.", "h-3": "Default", "h-4": "Blank", "0-3": "All fields.", "1-0": "filter", "1-1": "Fields and values to filter the results by (e.g. WHERE clause)", "1-2": "Only fields associated with the report may be used for filtering.", "1-3": "No filtering", "2-0": "metric", "2-1": "Metrics to included and summed in the report. Metrics may not be used for filtering or sorting.", "2-2": "Only metrics associated with the report may be included.", "2-3": "All metrics.", "3-0": "offset", "3-1": "Number of rows to offset results from the first results (e.g. for pagination through results)", "3-2": "Single numeric value", "3-3": "0", "4-0": "rows", "4-1": "Number of rows to include in the report", "4-2": "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.", "4-3": "50", "5-0": "sort_by", "5-1": "A field to sort the results by, along with the order (0=ascending).", "5-2": "Only fields associated with the report and included in the field key may be used for sorting.", "5-3": "First field in the report will be used for sorting." }, "cols": 4, "rows": 6 } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] Specifying fields with the `field` key: [block:code] { "codes": [ { "code": "{\"request_details\":\n \t{\"field\":\n [\"advertiser_id\",\"advertiser_name\"]\n }\n}", "language": "json" } ] } [/block] Specifying fields and metrics with the `metric` key: [block:code] { "codes": [ { "code": "{\"request_details\":\n \t{\n \"field\":\n \t\t[\"advertiser_id\",\"advertiser_name\"],\n \t\"metric\":\n \t\t[\"impressions\",\"CPM\"]\n }\n}", "language": "json" } ] } [/block] Sorting with `sort_by` (note it is a JSON object with the field name and the sort order): [block:code] { "codes": [ { "code": "{\"request_details\":\n {\n \t\"field\":\n \t\t[\"advertiser_id\",\"advertiser_name\"],\n \t\"metric\":\n \t\t[\"impressions\",\"CPM\"],\n \t\t\"sort_by\":\n \t\t[\n {\"advertiser_id\":1}\n ]\n }\n}", "language": "json" } ] } [/block] Filtering: [block:code] { "codes": [ { "code": "{\"request_details\":\n\t{\n \t\"field\":\n \t[\"advertiser_id\",\"advertiser_name\"],\n \"metric\":\n \t[\"impressions\",\"CPM\"],\n\t\t\"filter\":\n \t[{\"advertiser_id\":1}]\n }\n}", "language": "json" } ] } [/block]