Reporting API

Overview

The Reporting API lets you programmatically pull Custom and Scheduled Reports. In the API, "Custom Reports" are referred to as "Queued Reports".

📘

Please Note

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

Creating a Custom Report with 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. GET the Poll for Queued Report endpoint to get 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'd get:

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

Which you'd append to and then GET the Poll for Queued Report endpoint: https://api.kevel.co/v1/report/queue/a87ece06-28cd-4267-9314-e830af7eaa12

This will return the 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":{  
....

🚧

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 - look through Custom Report Fields for an overview.

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

(BETA) The name of a city. Must be an exact match.

regionCode

(BETA) The Region's code. Pull those here. Must also filter or group by Country.

📘

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

Creating a Scheduled Report with API

🚧

Scheduled reporting is in Beta. Contact your account manager or Kevel support to get started.

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. It uses the same criteria object.

The report will be delivered in an email to the account associated with the LoginId. You can 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.