Reporting API (WIP)

reporting-api.md

@@ -6,17 +6,21 @@ Adspect Reporting API provides programmatic access to Adspect statistics via two
 * [Sales funnel endpoint](api.md#reporting-sales-funnel) for creating aggregated reports;
 * [Click log endpoint](api.md#reporting-click-log) for extracting raw click by click data.
 
-These endpoints functionally mirror the Reporting section of the Adspect clients area.
+These endpoints functionally mirror the [Reporting section](reporting.md) of the Adspect clients area.
 
 (reporting-filters)=
 ### Reporting Filters
 
 Both Reporting API endpoints support filters via URL parameters to narrow down the portion of statistics data to be processed.
-The following table lists available report filters.  All parameters are optional.  Parameters ending with `[]` are arrays:
-you may specify several such parameters, and their values will be added together, e.g. `os[]=iOS&os[]=macOS` will extract
-clicks that came from iOS **or** macOS operating systems.
 
-:::{list-table} Report Filter Parameters
+The following table lists available report filters.  All parameters are optional.
+
+:::{note}
+Parameters ending with `[]` are arrays: you may specify several such parameters, and their values will be added together, e.g.
+`os[]=iOS&os[]=macOS` will extract clicks that came from iOS **or** macOS operating systems.
+:::
+
+:::{list-table}
 :header-rows: 1
 
 * - Parameter
@@ -99,7 +103,13 @@ the `group_by[]` parameters followed by the order of the `metrics[]` parameters.
 
 The following table lists URL parameters specific to the sales funnel endpoint.
 
-:::{list-table} Sales Funnel Endpoint URL Parameters
+:::{note}
+Parameters ending with `[]` are arrays: you may specify several such parameters, and their values will be added together, e.g.
+`group_by[]=date&group_by[]=stream_id` will result in funnel breakdown first by date and then by stream IDs.  Likewise,
+`metrics[]=clicks&metrics[]=money_hits` will add clicks and money hits metrics to the output, in that order.
+:::
+
+:::{list-table}
 :header-rows: 1
 
 * - Parameter
@@ -120,7 +130,7 @@ The following table lists URL parameters specific to the sales funnel endpoint.
 
 The following table lists available breakdown columns for the `group_by[]` URL parameter.
 
-:::{list-table} Sales Funnel Breakdown Columns
+:::{list-table}
 :header-rows: 1
 
 * - Column
@@ -181,7 +191,7 @@ The following table lists available sales funnel metrics for the `metrics[]` URL
 Please specify only those metrics that you actually need in your API requests.
 :::
 
-:::{list-table} Sales Funnel Metric Columns
+:::{list-table}
 :header-rows: 1
 
 * - Column Name
@@ -262,36 +272,26 @@ This list may also be obtained via the
 (reporting-sales-funnel-examples)=
 #### Examples
 
-Example #1: obtaining basic metrics for all streams, grouped by stream ID:
-
-```{code-block}
-:caption: Example #1 Request
+**Example #1:** obtaining basic metrics for all streams, grouped by stream ID:
 
+```
 GET /reports/funnel?group_by[]=stream_id&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality
 ```
 
-```{code-block} json
-:caption: Example #1 Response
-
+```json
 ["1ec5880e-bcb6-49b8-9778-a31d22b70708", "1453", "754", "699", 0.5189263592567103]
 ["07ac03df-268e-41ff-84ba-adfe2241beb2", "3219", "2034", "1125", 0.6318732525629077]
 ["7a3d39f7-fe75-431e-8be6-9ea9b56b1e4a", "179", "0", "179", 0]
 ["9f79b75f-20ef-4654-8141-b8bbb2124ec4", "65", "0", "65", 0]
 ```
 
-<hr>
-
-Example #2: obtaining basic metrics for the stream with ID `07ac03df-268e-41ff-84ba-adfe2241beb2`:
-
-```{code-block}
-:caption: Example #2 Request
+**Example #2:** obtaining basic metrics for the stream with ID `07ac03df-268e-41ff-84ba-adfe2241beb2`:
 
+```
 GET /reports/funnel?group_by[]=date&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2
 ```
 
-```{code-block} json
-:caption: Example #2 Response
-
+```json
 ["2024-04-01", "931", "343", "582", 0.3684210526315789]
 ["2024-04-02", "1166", "829", "300", 0.7109777015437393]
 ["2024-04-03", "1113", "855", "243", 0.7681940700808625]
@@ -310,7 +310,12 @@ the order of the `columns[]` parameters.
 
 The following table lists URL parameters specific to the click log endpoint.
 
-:::{list-table} Click Log Endpoint URL Parameters
+:::{note}
+Parameters ending with `[]` are arrays: you may specify several such parameters, and their values will be added together, e.g.
+`columns[]=timestamp&columns[]=ip_address` will add timestamp and IP address columns to the output, in that order.
+:::
+
+:::{list-table}
 :header-rows: 1
 
 * - Parameter
@@ -331,7 +336,7 @@ The following table lists available click log columns for the `columns[]` URL pa
 Please specify only those columns that you actually need in your API requests.
 :::
 
-:::{list-table} Click Log Columns
+:::{list-table}
 :header-rows: 1
 
 * - Column Name
@@ -398,20 +403,16 @@ Please specify only those columns that you actually need in your API requests.
 This list may also be obtained via the `GET /collections/query-log-columns` collection endpoint.
 :::
 
-(reporting-click-log-example)=
-#### Example
+(reporting-click-log-examples)=
+#### Examples
 
 Obtaining today's click log of the stream with ID `07ac03df-268e-41ff-84ba-adfe2241beb2`:
 
-```{code-block}
-:caption: Request
-
+```
 GET /reports/log?columns[]=timestamp&columns[]=ip_address&columns[]=country_code&columns[]=target&date_from=today&date_to=tomorrow&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2
 ```
 
-```{code-block} json
-:caption: Response
-
+```json
 ["2024-04-01 00:00:00", "23.83.90.68", "US", 0]
 ["2024-04-01 00:00:00", "2a03:2880:30ff:8::33", "SE", 0]
 ["2024-04-01 00:00:00", "47.128.19.245", "SG", 0]