API Access Instructions

Custom Analytics API

Full API with instruction is available in the Reporting tab on the Publisher Dashboard. The same information that is provided in that link, is also provided below. Note that you’ll need to log in to your publisher dashboard and navigate to the API page to get your specific API Key and Access URL. Navigate to API by selecting the “Reporting” tab in your Publisher Dashboard and then selecting API Info once you are in “Reporting.”

Publisher Dashboard ->Reporting -> API Info

Screen_Shot_2020-10-26_at_12.29.46_PM.png

Accessing the Underdog Media Reporting API occurs through a POST request.

Note: Your API Key is a token based authentication key. Please keep this key private. It's best to remove this key from email communications to protect it.

API access is monitored and there is a daily quota on the amount of data that can be pulled per day. In the event that the quota is hit, the API will return an error until the next 24 hour period.

The POST payload is a JSON object, passed directly in as the request body, that contains multiple fields describing the users query as described below:

Using `apiKey` and `repId` to pull the data for one of your Saved Reports

{
  "apiKey": "Your apiKey Here"
  "repSpec": {
    "repId": "Your repId Here"
  }
}

As shown in the above example, by using a saved reports repId (located on the 'Your Reports' page in the Reporting area) and your unique apiKey (shown above), you can form a simple JSON POST payload which will pull the report associated with that repId from the API.

Top Level Fields

Name	Description	Required	Accepted Formats/Values	Data Type
apiKey	Your custom API key.	true	Get your unique API Key by logging into your publisher dashboard.	string
repSpec	This object holds all your API specifications.	true	See repSpec table below.	object

repSpec Fields

Name	Description	Required	Accepted Formats/Values	Data Type
timeZone	The timezone your report data will reference.	true	See timeZone table below.	object
dateRange	The date range your report data will come from.	true	See dateRange table below.	object
colSpecs	The metrics, dimensions, and filters you may apply to your report.	true	See colSpecs table below.	array of object
orderCols	Allows you to order columns in your result set	false	{ "colId": <string>, "dir": <"asc" \| "desc"> }	array of object

timeZone Fields

Name	Description	Required	Accepted Formats/Values	Data Type
tzCode	Standard timezone declarations.	tzCode OR tzOffset	`PT`, `MT`, `CT`, `ET`, `UTC`	string
tzOffset	UTC offset values.	tzCode OR tzOffset	This fields accepts integer values between -12 and +13.	integer

dateRange Fields

Name	Description	Required	Accepted Formats/Values	Data Type
rangeName	String value used in tandem with rangeQual to define a date range.	Recommended (with rangeQual)	`{N} Days Ago`, `Last {N} Days`, `{N} Weeks Ago`, `{N} Months Ago`, `{N} Qtrs Ago`, `Month To Date`, `Quarter To Date`, `Custom`, `Custom Single Day`	string
rangeQual	Integer value used in tandem with rangeName to define a date range.	Recommended (with rangeName)	This fields accepts any integer value.	integer
startDate	Marks the start date of the requested data for the report. When using startDate and endDate, the rangeName should be Custom. Just use startDate if rangeName is Custom Single Day	rangeName & rangeQual OR startDate & endDate	Format: `YYYY-MM-DD`	string
endDate	Marks the end date of the requested data for the report. When using startDate and endDate, the rangeName should be Custom. Just use startDate if rangeName is Custom Single Day	rangeName & rangeQual OR startDate & endDate	Format: `YYYY-MM-DD`	string

colSpecs Fields

Name	Description	Required	Accepted Formats/Values	Data Type
colId	column names that can be displayed for grouping or filtering	true	See colId table below	string
showCol	indicates if this column will be part of the result set	true	true / false	boolean
filtExpr	object with values to indicate the filter applied on the current colId	false	See Table filtExpr table below	object

filtExpr Fields

Name	Description	Required	Accepted Formats/Values	Data Type
filtType	Standard timezone declarations.	true	`innotInlikenotLike`	string
filtVals	Array of values to filter data within this colId	true	Dependent on colIds - see below	array

colIds

Name	Description	Required	Accepted Filter Values	Data Type
Time Intervals
date	Displays the date in YYYY-MM-DD format.	false	Dates formatted: YYYY-MM-DD	string
dateHour (hour)	Displays the date in YYYY-MM-DD format followed by the 2-digit hour ranging from 00 - 23.	false	Hours formatted: 00 - 23	string
week	Displays the week of the year as a number ranging from 0 - 52.	false	Week formated 0 - 52	string
month	Displays the month of the year as a string.	false	Full Month Name	string
monthNum	Displays the month of the year as a number.	false	Month number Formatted 0 - 12	string
qtr	Displays the quarter as a number ranging from 0 - 4.	false	Quarter formatted: 0 - 4	string
year	Displays the year as a 4-digit number.	false	Year formatted YYYY	string
Metrics
Name	Description	Required	Accepted Filter Values	Data Type
impReqs	Impression Requests/Page Views	false	n/a	string
paidImps	Paid Impressions	false	n/a	string
pubRev	Revenue	false	n/a	string
rpm	RPM	false	n/a	string
ecpm	Paid eCPM	false	n/a	string
rawFillRate	Raw Fill (Win) Rate	false	n/a	string
qualRpm	Edge CPM	false	n/a	string
Dimensions/Filters
Name	Description	Required	Accepted Filter Values	Data Type
reqType	Request Type - must be 'UDM'	true	This is required: 'UDM'	string
pid	Pub ID	true	Your Publisher ID - this is required	string
sid	Site ID	false	Filter by site IDs if desired.	string
siteName	Site Name	false	Filter by Site Name if desired	string
siteFlags	Product Type	false	Edge A, In-Page Header, Adapter	string
domain	Domain	false	Filter by site domain if desired	string
adType	Allows you to add a dimension or filter by adType. Ex. '728x90 banner' and '300x250 banner'.	false	WxH [style] where [style] id banner of video	string
country	Country the site is based in.	false	Full country name ie: 'United States'	string
state	State the site is based in.	false	Full state name ie: 'New York'	string
device	Device type (Ex. Desktop, Mobile, Tablet)	false	Desktop, Mobile, Tablet	string
browser	Browser being used.	false	Browser Name ie: Andoid, Chrome, Edge, Facebook, Internet Explorer, Safari	string
os	Operating System	false	OS Name ie: Android, iOS, Mac OS, Linux, Windows	string
utmSource	utmSource	false	Customer Defined	string
utmCampaign	utmCampaign	false	Customer Defined	string
utmMedium	utmMedium	false	Customer Defined	string
utmContent	utmContent	false	Customer Defined	string
utmTerm	utmTerm	false	Customer Defined	string
utmReferrer	utmReferrer	false	Customer Defined	string
customParameter	customParameter	false	Customer Defined	string
subId	subId	false	Customer Defined	string

Dimensions vs Filters

A filter will dictate what report data gets retrieved from the API. A dimension is metadata that will be displayed for your selected report, in the form of a column.

Filter Example

Dimension Example

{
  "colId": "sid",
  "showCol": false,
  "filtExpr": {
    "filtType": "in",
    "filtVals": [
    "1",
    "1234"
    ]
  }
}

{
  "colId": "month",
  "showCol": true
}

The Filter Example is showing an sid filter that is gathering report data where the sid = 1 OR sid = 1234. Notice 'showCol': false, which means that no report column will show up for sid. The Dimension Example is retrieving the associated month that the pulled data belongs to.

Response Format

The API responds with JSON formatted text with the following fields:

Response Example

 {
         "status": <"success" | <error string>>,
         "results": [<col-keyed hash>...],
         "total": <col-keyed hash (metrics only)>,
         "resStats": {
           "bytesProcessed": <integer>,
           "runTime": <float>,                      // seconds
           "cost": <float>                          // dollars
         }
     }

resStats cost is logged to ensure daily queries do not exceed the allowable quota. This is not a fee.

Code Examples

runSpec examples

You will see runSpec referenced as a variable in the below code samples. It serves as an example of report parameter selections that can be passed into the API.

Example 1:

{ "apiKey": "",
  "repSpec": {
    "dateRange": {
      "rangeName": "Last {N} Days", 
      "rangeQual": 3
    },
    "colSpecs": [
      {
        "colId": "reqType", 
        "showCol": false, 
        "filtExpr": {
          "filtVals": ["UDM"],
          "filtType": "in"
        }
      }, 
      {
        "colId": "pid", 
        "showCol": false, 
        "filtExpr": {
          "filtVals": [""], 
          "filtType": "in"
        }
      }, 
      {
        "colId": "sid", 
        "showCol": true
      }, 
      {
        "colId": "siteName", 
        "showCol": true
      }, 
      {
        "colId": "pubRev", 
        "showCol": true
      }, 
      {
        "colId": "impReqs", 
        "showCol": true
      }, 
      {
        "colId": "paidImps", 
        "showCol": true
      }, 
      {
        "colId": "date", 
        "showCol": true
      }
    ], 
    "timeZone": {
      "tzCode": "PT"
    }
  }
}

The above runSpec formats a query for a report spanning the past 3 days, in the Pacific Standard Timezone. 'reqType' and 'pid' are static objects that must be part of the JSON payload. 'reqType' = 'UDM', and 'pid' = your publisher ID. sid, siteName, pubRev, impReqs, paidImps, and date have been applied as columns (dimensions) that will show up in the results table.

Example 2:

{
  "apiKey": "",
  "repSpec": { 
    "dateRange": {
      "rangeName": "Custom", 
      "startDate": "2020-07-13", 
      "endDate": "2020-07-17"
    }, 
    "colSpecs": [
      {
        "colId": "reqType", 
        "showCol": false, 
        "filtExpr": {
          "filtVals": ["UDM"], 
          "filtType": "in"
        }
      }, 
      {
        "colId": "pid", 
        "showCol": false, 
        "filtExpr": {
          "filtVals": [""], 
          "filtType": "in"
        }
      }, 
      {
        "colId": "date", 
        "showCol": true
      }, 
      {
        "colId": "paidImps", 
        "showCol": true
      }, 
      {
        "colId": "pubRev", 
        "showCol": true
      }, 
      {
        "colId": "rpm", 
        "showCol": true
      }, 
      {
        "colId": "adType", 
        "showCol": true, 
        "filtExpr": {
          "filtVals": ["728x90 banner", "300x250 banner"], 
          "filtType": "in"
        }
      }
    ], 
    "timeZone": {
      "tzOffset": 3
    }
  }
}

The above runSpec formats a query for a report with a custom date range of 7/13/2020 - 7/17/2020, a timezone value of 'UTC +3'. 'reqType' and 'pid', again, are static objects that must be part of the JSON payload. 'reqType' = 'UDM', and 'pid' = your publisher ID. date, paidImps, pubRev, and rpm have been applied as columns (dimensions) that will show up in the results table. An adType filter has been applied for the adType's of '728x90 banner' and '300x250 banner'.

cURL

curl -H 'Content-Type:application/json' -X POST -d runSpec 'https://pub.udmserve.com/reports/runReport'

Node.js

const request = require('request'); // npm package request
request.post(
  'https://pub.udmserve.com/reports/runReport', runSpec,
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
);

Python

import requests
r = requests.post('https://pub.udmserve.com/reports/runReport', json=runSpec)
print(r.text)

Ruby

require 'httparty'
puts
HTTParty.post("https://pub.udmserve.com/reports/runReport",
  :headers => { 'Content-Type' => 'application/json' },
  body: runSpec
  .to_json).body