Reporting API

Overview

The Reporting API enables you programmatically pull Custom and Scheduled Reports. In the API, " Custom Reports" may also be referred to as " Queued Reports".

📘

Note

All reports generated through the UI or API have a lifetime of 10 days. These reports expire after 10 days and need to be regenerated.

Creating a Custom Report with the Kevel API

Ping the Create Queued Report endpoint with details inside of a criteria object.
Add any GroupBy fields in a GroupBy object as a list of strings.
Add any Filter fields in a Parameters object as a list of Crit objects.
Add any Exclude Filter fields in a ExcludeParameters object as a list of Crit objects.
Wait for the GUID in the response.
Make a GET request to the Poll for Queued Report endpoint to retrieve the data.

This example pulls a report that;

Is for January 2017
Broken down by day and campaigns
Filtered by Advertiser 12 ("Nike")

JSON

{
  "StartDateISO": "2017-01-01T00:00:00",
  "EndDateISO": "2017-01-31T00:00:00",
  "GroupBy": ["day","campaignId"],
  "Parameters": [{"brandId": 12}]
}

In the response you would receive the following response:

JSON

{
    "Id": "a87ece06-28cd-4267-9314-e830af7eaa12"
}

You would then append the response and then make another GET request to the Poll for Queued Report endpoint: https://api.kevel.co/v1/report/queue/a87ece06-28cd-4267-9314-e830af7eaa12

This request will return the following report:

JSON

{
    "Id":"b0e0v47-be95-4f4e-8d01-090xx55gg44",
    "Status":2,
    "Result":{
        "StartDateISO": "2017-01-01T00:00:00",
        "EndDateISO": "2017-01-31T00:00:00",
        "Critiera":[
        ],
        "LoginId":0,
        "Records":[
            {
                "Impressions":51431687,
                "Clicks":63328,
                "Events":{
                    "1":29,
                    "2":8
                },
                "Revenue":114610.83561739461402407011453,
                "TrueRevenue":89415.3015,
                "Date":"2017-01-01T00:00:00Z",
                "FirstDate":"2017-01-01T00:00:00Z",
                "LastDate":"2017-01-31T00:00:00Z",
                "CTR":0.1231303184746788492471576900,
                "Details":[
                    {
                        "Title":"Name of My Flight ROS CPA",
                        "Impressions":107580,
                        "Clicks":22,
                        "FraudulentClicks":0,
                        "Events":{
                            "1":1,
                            "2":1
                        },
                        "Revenue":200.000,
                        "TrueRevenue":400.0,
                        "Date":"2014-03-07T00:00:00Z",
                        "FirstDate":"2014-03-01T00:00:00Z",
                        "LastDate":"2014-03-31T00:00:00Z",
                        "CTR":0.0204498977505112474437627800,
                        "AdjustedCTR":0,
                        "Details":[
                        ],
                        "Grouping":{
                            "OptionId":171761,
                            "BrandId":9396,
                            "CampaignId":91385,
                            "SiteId":0,
                            "ZoneId":0,
                            "CreativeId":0,
                            "PublisherAccountId":0,
                            "AdTypeId":0,
                            "ChannelId":4811,
                            "Date":6042,
                            "DateType":"month",
                            "MetroCode":0,
                            "PriorityId":0,
                            "RateTypeId":5,
                            "Price":"200"
                        },
                        "eCPM":3.7181632273656813534114147611
                    },
                    {
                        "Title":"Another Flight CPM",
                        "Impressions":33994,
                        "Clicks":49,
                        "Events":{
...

🚧

Caution

All StartDateISO and EndDateISO requests should use ISO 8601 midnight GMT, such as: '2016-06-01T00:00:00' or '2016-06-01T00:00:00Z'.

GroupBy and Parameter Fields - Optional

In the Reporting API, Group By options are under the GroupBy object, while the Filter fields are under Parameters. If you haven't already, please review the Custom Report Fields for an overview of these parameters.

Name	Description
`day`	Calendar day. `GroupBy` only.
`week`	Calendar week. `GroupBy` only.
`month`	Calendar month. `GroupBy` only.
`brandId`	The Advertiser's ID. Pull those here.
`campaignId`	The Campaign's ID. Pull those here.
`flightId`	The Flight's ID. Pull those here Includes price data when used as a Group By.
`flightWithoutPrice`	Includes flight data only when used as a Group By. `GroupBy` only.
`creativeId`	The Creative's ID. Pull those here
`adTypeId`	Ad Type / Size. Pull those here.
`siteId`	The Site's ID. Pull those here.
`zoneId`	The Zone's ID. Pull those here.
`countryCode`	The Country's code. Pull those here.
`metroCode`	The Metro's code. Pull those here.
`keyword`	Keywords being targeted. Each keyword is a value in a key value pair: `{"keyword":"foo"}`.
`channelId`	The Channel's ID. Pull those here. `Parameters` only.
`city`	The name of a city. Must be an exact match.
`regionCode`	The Region's code. Pull those here. Must also filter or group by Country.
`modelName`	The name of the device model (e.g. iPad for tablet).
`brandName`	Device Brand (e.g. Apple, Google, Mozilla).
`advertisedOs`	Operating System (e.g. iOS, Android, Windows, macOS, Linux)
`osMajorVersion`	OS Major Version (e.g. 15 for iOS 15.5).
`osMinorVersion`	OS Minor Version (e.g. 5 for iOS 15.5).
`browser`	Browser (e.g. Chrome Desktop or Safari).
`browserMajorVersion`	Browser Major Version (e.g. 104 for Chrome 104.0).
`browserMinorVersion`	Browser Minor Version (e.g. 0 for Chrome 104.0).
`formFactor`	Device Form Factor (e.g "tablet" or "desktop").

📘

Note

For creativeId, make sure you use the ID associated with the Creative, not the ID associated with the Ad (Creative Flight Maps ID).