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 report expire after 10 days and need to be regenerated.

Creating a Custom Report with the Kevel API

  1. Ping the Create Queued Report endpoint with details inside of a criteria object
  2. Add any GroupBy fields in a GroupBy object as a list of strings
  3. Add any Filter fields in a parameter object as a list of Crit objects
  4. Wait for the GUID in the response
  5. 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")

{
  "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:

{
    "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:

{  
    "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.

NameDescription
dayCalendar day. GroupBy only.
weekCalendar week. GroupBy only.
monthCalendar month. GroupBy only.
brandIdThe Advertiser's ID. Pull those here.
campaignIdThe Campaign's ID. Pull those here.
flightIdThe Flight's ID. Pull those here Includes price data when used as a Group By.
flightWithoutPriceIncludes flight data only when used as a Group By. GroupBy only.
creativeIdThe Creative's ID. Pull those here
adTypeIdAd Type / Size. Pull those here
siteIdThe Site's ID. Pull those here
zoneIdThe Zone's ID. Pull those here
countryCodeThe Country's code. Pull those here
metroCodeThe Metro's code. Pull those here
keywordKeywords being targeted. Each keyword is a value in a key value pair: {"keyword":"foo"}
channelIdThe Channel's ID. Pull those here. Parameters only
cityThe name of a city. Must be an exact match.
regionCodeThe Region's code. Pull those here. Must also filter or group by Country.
modelNameThe name of the device model (e.g. iPad for tablet
brandNameDevice Brand (e.g. Apple, Google, Mozilla)
osMajorVersionOS Major Version (e.g. 15 for iOS 15.5)
osMinorVersionOS Minor Version (e.g. 5 for iOS 15.5)
browserBrowser (e.g. Chrome Desktop or Safari)
browserMajorVersionBrowser Major Version (e.g. 104 for Chrome 104.0)
browserMinorVersionBrowser Minor Version (e.g. 0 for Chrome 104.0)
formFactorDevice 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).

🚧

Caution

For device reporting to be accurate, you must pass the User Agent (UA) to Kevel via the User-Agent header if you are proxying events through their server.

Failure to do so might lead to inconsistent attribution, resulting in, for example, clicks without impressions, as one is not attributed to the same device.

Creating a Scheduled Report with API

🚧

Caution

Scheduled reporting is currently in Beta. Please contact your account manager or Kevel support if you would like to use this feature.

The Scheduled Reports endpoint schedules a report to be generated and delivered at a future date and time. The report can be set to recur daily, weekly, or monthly, and uses the same criteria object.

The report will be delivered in an email to the account associated with the LoginId. You may also add external e-mails to the request.

The email includes a link to the reporting page in the UI, and the link contains the GUID of the report.