Reporting API (WIP)

reporting-api.md

@@ -11,7 +11,23 @@ These endpoints functionally mirror the [Reporting section](reporting.md) of the
 (reporting-filters)=
 ### Reporting Filters
 
-Both Reporting API endpoints support filters via URL parameters to narrow down the portion of statistics data to be processed.
+Both Reporting API endpoints support filters via URL parameters to narrow down the portion of statistics data to be processed, e.g:
+
+```
+...&date_from=1672520400&date_to=1675198800&country_code[]=AE&os[]=iOS&os[]=macOS&mode[]=Filter
+```
+
+A report made with such filters will only contain clicks that match **all** of the following conditions:
+
+* during January 2023 (`date_from=1672520400&date_to=1675198800`);
+* from United Arab Emirates (`country_code[]=AE`;
+* from iOS **or** macOS devices (`os[]=iOS&os[]=macOS`);
+* made when stream mode was set to Filtering (`mode[]=Filter`.)
+
+:::{tip}
+You may specify dates and times as human-readable strings instead of Unix timestamps, e.g. `1 Jan 2023` or `2023-01-01` instead of
+`1672520400`.  Adspect will do its best to parse such a date string in a meaningful way.
+:::
 
 The following table lists available report filters.  All parameters are optional.
 
@@ -41,7 +57,7 @@ Parameters ending with `[]` are arrays: you may specify several such parameters,
 
 * - `time_zone`
   - String
-  - Default time zone for displaying date and time.
+  - Time zone for displaying date and time, e.g. `Asia/Dubai`.
 
 * - `stream_id[]`
   - String
@@ -118,11 +134,11 @@ Parameters ending with `[]` are arrays: you may specify several such parameters,
 
 * - `group_by[]`
   - String, optional
-  - Add sales funnel breakdown column (see below) to the output.
+  - Add a [sales funnel breakdown column](api.md#reporting-sales-funnel-breakdown) to the output.
 
 * - `metrics[]`
   - String, **required**
-  - Add a sales funnel metric column (see below) to the output.
+  - Add a [sales funnel metric column](api.md#reporting-sales-funnel-metrics) to the output.
 :::
 
 (reporting-sales-funnel-breakdown)=
@@ -179,7 +195,7 @@ The following table lists available breakdown columns for the `group_by[]` URL p
 :::
 
 :::{tip}
-This list may also be obtained via the [`GET /collections/query-group-by`](api.md#query-group-by) collection endpoint.
+This list may also be obtained via the [GET /collections/query-group-by collection endpoint](api.md#collections).
 :::
 
 (reporting-sales-funnel-metrics)=
@@ -265,8 +281,7 @@ Please specify only those metrics that you actually need in your API requests.
 :::
 
 :::{tip}
-This list may also be obtained via the
-[`GET /collections/query-funnel-metrics` collection endpoint](api.md#query-funnel-metrics-collection).
+This list may also be obtained via the [GET /collections/query-funnel-metrics collection endpoint](api.md#collections).
 :::
 
 (reporting-sales-funnel-examples)=
@@ -400,7 +415,7 @@ Please specify only those columns that you actually need in your API requests.
 :::
 
 :::{tip}
-This list may also be obtained via the `GET /collections/query-log-columns` collection endpoint.
+This list may also be obtained via the [GET /collections/query-log-columns collection endpoint](api.md#collections).
 :::
 
 (reporting-click-log-examples)=