Reports
=======

Reports endpoint will be responsible for gracefully pulling of necessary advertising data (clicks, impressions, spend, etc) per specified platform

GET to URL
----------

1. Main host - https://www.adverity.com/

2. Report endpoint - mint/reports/platform/{platform_name}/account/{account_id}/data

3. Final endpoint = Main host + Report endpoint = https://www.adverity.com/mint/reports/platform/{platform_name}/account/{account_id}/data

AUTHORISATION
-------------

OAUTH2 is recommended to be used for authorisation. Single Adverity bearer token (without expiration) can be used to get API access.


REPORT FILE FORMAT
------------------
Either JSON or CSV can be used.

REQUEST RATE FREQUENCY
----------------------
We’ll need the reports per account for the specified platform:

 - historical data - 1-YEAR AGO DATE RANGE

 - weekly data - 7-DAY AGO DATE RANGE

Historical data is needed once per account for the specified campaigns. If new campaign is added to account we’ll pull it 1 time.

Weekly data will be pulled every day per account for the specified campaigns. It’s needed to have always refreshed reports because external APIs can update the metrics -> its values can be changed during last week.

PAGINATION
----------
In case of big amount of data (rows) per request we can use pagination and parse the data page by page for example if number of rows is more than 100000.

REQUEST BODY
------------

The data filtering should be used while requesting the data including it in request body:

**CAMPAIGNS** - list of campaigns (ids) (minimum 1 campaign can be added to list)

**DATE RANGE** - start_date / end_date in format YYYY-MM-DD

**FREQUENCY** - DAILY only

**DIMENSIONS** - list of dimension columns ("date", "campaign_id", "ad_group_id", "ad_id")

**METRICS** - list of metric columns ("completed_views_full", "completed_views_first", "completed_views_mid", "completed_views_third", "spend", "video_start", "video_views", "platform_conversions", "clicks", "impressions")

DIMENSIONS and METRICS can be unified into the single COLUMNS column containing the list of dimensions and metrics

EXAMPLE BODY

.. code-block:: python

    {
        "campaigns": [17957, 23457, 90292, 17283],
        "start_date": "2024-05-01",
        "end_date": "2024-06-10",
        "frequency": "daily",
        "dimensions": ["date", "campaign_id", "ad_group_id", "ad_id"],
        "metrics": ["completed_views_full", "completed_views_first", "completed_views_mid", "completed_views_third", "spend", "video_start", "video_views", "platform_conversions", "clicks", "impressions"]
    }

-------
Metrics
-------

+-----------------------+--------------------------------------------------------------------+
| Metric                | Description                                                        |
+=======================+====================================================================+
| clicks                | The number of times a person has clicked on an ad                  |
+-----------------------+--------------------------------------------------------------------+
| completed_views_first | Video viewed calculated at 100% at 25% of the duration             |
+-----------------------+--------------------------------------------------------------------+
| completed_views_full  | Metric that count the times that a video ad is viewed till the end |
+-----------------------+--------------------------------------------------------------------+
| completed_views_mid   | Video viewed calculated at 100% at 50% of the duration             |
+-----------------------+--------------------------------------------------------------------+
| completed_views_third | Video viewed calculated at 100% at 75% of the duration             |
+-----------------------+--------------------------------------------------------------------+
| impressions           | The number of times your ad has been viewed                        |
+-----------------------+--------------------------------------------------------------------+
| spend                 | Amount of money spent                                              |
+-----------------------+--------------------------------------------------------------------+
| video_start           | Number of Video Start                                              |
+-----------------------+--------------------------------------------------------------------+
| video_views           | Number of Video Views                                              |
+-----------------------+--------------------------------------------------------------------+
| platform_conversions  | Number of Conversions                                              |
+-----------------------+--------------------------------------------------------------------+

----------
Dimensions
----------

+-----------------------+--------------------------------------------------------------------+
| Metric                | Description                                                        |
+=======================+====================================================================+
| date                  | The date in format YYYY-MM-DD                                      |
+-----------------------+--------------------------------------------------------------------+
| campaign_id           | ID for advertising campaign                                        |
+-----------------------+--------------------------------------------------------------------+
| ad_group_id           | ID for advertising group within campaign                           |
+-----------------------+--------------------------------------------------------------------+
| ad_id                 | ID for advertising ad within group                                 |
+-----------------------+--------------------------------------------------------------------+