Page tree
Skip to end of metadata
Go to start of metadata

Please Note: You should not share your API key with any partners. Your API key is for your account and your account only. It contains all your account data.  DO NOT SHARE IT WITH EXTERNAL PARTIES YOU DO NOT WANT HAVING ACCESS TO ALL YOUR DATA AND/OR CONTROL OF YOUR ACCOUNT.

Authentication

Authentication is currently handled by HTTP Basic Authentication over SSL. Your account admin can generate API credentials via the API Keys tab on their Account settings page.  The credentials consist of a Secret Key ID and a Secret Key that resemble the following:

Secret Key IDSecret Key
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx1111111111111111111111111111111111111

For use in Basic Authentication, the Secret Key ID serves as the username and the Secret Key serves as the password.  


These values should be base64 encoded using the following format:

TypeExample
Unencodedxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:1111111111111111111111111111111111111
EncodedeHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHg6MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMQ==
Authorization Header Example
Authorization: Basic eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHg6MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMQ==

Reporting API

JSON Parsing Guidelines

The API is subject to change, in that new fields may be added at any time. Your JSON parsing should therefore be tolerant of new fields being added to the JSON. Please do not parse the JSON in a way that would not tolerate the addition of new fields.

Rate Limits

Unless otherwise permitted, all API users are subject to a rate limit of 30 queries per day (UTC).

Queries cannot be executed simultaneously.

Request

HTTP MethodEndpoint
POSThttps://api.lkqd.com/reports

The reporting request (POST) body is in the following JSON format:

{
    "timeDimension": "HOURLY", 		// Equivalent of Time Level in UI reporting.  Values are OVERALL, MONTHLY, DAILY, HOURLY.
    "reportType": ["PARTNER","SITE","COUNTRY"],  	// Equivalent of Dimensions in UI reporting.  Up to 5 dimensions can be included per request. See Dimension Mapping below for all options. 
    "reportFormat": "JSON",			// The format of the report output. Values are JSON, CSV.
    "startDate": "2017-07-07",		// Required. These are in America/New_York timezone by default.
    "endDate": "2017-07-07",		// Required. These are in America/New_York timezone by default.
	"startHour": 5, 				// Optional. This property should only be included when timeDimension value is HOURLY. Value must be an Int (not String).
	"endHour": 19,			 		// Optional. This property should only be included when timeDimension value is HOURLY. Value must be an Int (not String).
	"timezone": "UTC", 				// "UTC" and "America/New_York" currently supported
	"filters": [{					// Optional.  Applies filters to your output.
		 "dimension": "SITE", 		// The dimension the filter applies to.
		 "operation": "include",    // The operation of the filter.  Values are 'include' and 'exclude'.
		 "filters": [{				// The match type of the value.  Use "id" for entity IDs and "partial" for wildcard filtering by entity name.
		 	"matchType": "id", 	 	// This example filter includes records where Supply Source ID is 105350 or 105351.
		 	"value": "105350"		
		 },{
		 	"matchType": "id",
		 	"value": "105351"
		 }]},{
		 "dimension": "SITE",
		 "operation": "include",
		 "filters": [{
		 	"matchType": "partial",	// This example filters for Supply Sources with "high" in the name.
		 	"value": "high"
		}]},{
		 "dimension": "COUNTRY", 	// This example filters by Country ID "US".
		 "operation": "include",
		 "filters": [{
		 	"matchType": "id",
		 	"value": "US"}]
				}],
	"metrics": ["OPPORTUNITIES","IMPRESSIONS","REVENUE","CLICKS"],  // Optional. If the metric property is excluded from a request, all applicable default metrics will be returned in the output.  Default metrics are defined as those that are pre-selected in the UI based on the report's dimension selections.
    "sort": [{ 					// This example sorts by Dimension 1 (Supply Partner) descending, then Ad Opportunities descending.					
        "field": "SITE", 		// The column sorting will be applied to. Values are the dimension and metric strings listed in the tabled below.
        "order": "desc"			// The direction of the sort. Values are asc, desc.
    		},{
  		"field": "REVENUE",
  		"order": "desc"
 			}],
	"limit": 100,			// Optional. The max number rows that will be returned in your output.  
	"offset": 0				// Optional. Including this property will match the first record of you output to the specified record number.  Not applicable for reportFormat type CSV.  The default value is 0.  
}

Dimension Mapping

UI DimensionAPI Dimension
N/AOVERVIEW
Supply PartnerPARTNER

Supply Source

SITE
DomainDOMAIN
Detected DomainDETECTED_DOMAIN
App NameAPP_NAME
Bundle IDBUNDLE_ID
Supply Tag TypeSUPPLY_TAG_TYPE
LKQD Tag TypeLKQD_TAG_TYPE
Supply Partner ManagerSUPPLY_PARTNER_ASSIGNED_USER
Demand PartnerSOURCE
Demand OrderORDER
Demand DealDEAL
Demand TagTAG

Deal Start Date

DEAL_START_TS
Deal End DateDEAL_END_TS

Deal Delivery Goal

DEAL_DELIVERY_GOAL
Deal Front Load %DEAL_FRONT_LOAD_PERCENT
Demand Deal TypeDEAL_TYPE
Demand Delivery TypeTAG_AD_DELIVERY_TYPE
Demand Tag TypeTAG_TYPE
Demand Partner ManagerDEMAND_PARTNER_ASSIGNED_USER
Programmatic Deal IDPROGRAMMATIC_DEAL_ID
FormatFORMAT
EnvironmentENVIRONMENT
CountryCOUNTRY
Device TypeDEVICE
OSOS

Width X Height

PLAYER_WIDTH_HEIGHT
Custom 1CUSTOM1
Custom 2CUSTOM2
Custom 3CUSTOM3


Metric Mapping

UI Metric
API Metric
Available Report Types
Format LoadsFORMAT_LOADSSupply Only
Format Fill RateFORMAT_FILL_RATESupply Only
Ineligible Ops - DemandINELIGIBLE_OPS_DEMANDSupply Only
Ineligible Ops - RestrictionsINELIGIBLE_OPS_RESTRICTIONSSupply Only
OpportunitiesOPPORTUNITIESSupply Only
ImpressionsIMPRESSIONSSupply and Demand
Fill RateFILL_RATESupply Only
EfficiencyEFFICIENCYSupply and Demand
CPMCPMSupply and Demand
RevenueREVENUESupply and Demand
CostCOSTSupply and Demand
ProfitPROFITSupply and Demand
Profit MarginPROFIT_MARGINSupply and Demand
CTRCTR

Supply and Demand

25% View RateFIRST_QUARTILE_RATESupply and Demand
50% View RateMIDPOINT_RATESupply and Demand
75% View RateTHIRD_QUARTILESupply and Demand
100% View RateVTRSupply and Demand
ClicksCLICKSSupply and Demand
25% ViewsFIRST_QUARTILESSupply and Demand
50% ViewsMIDPOINTSSupply and Demand
75% ViewsTHIRD_QUARTILESSupply and Demand
100% ViewsCOMPLETED_VIEWSSupply and Demand
Ad StartsAD_STARTSSupply and Demand
Ad Starts RateAD_STARTS_RATESupply and Demand
Viewability Measured RateVIEWABILITY_MEASURED_RATESupply and Demand
Viewability RateVIEWABILITY_RATESupply and Demand
RequestREQUESTSDemand Only
VAST AdsVAST_ADSDemand Only
VPAID ResponsesVPAID_RESPONSESDemand Only
VPAID AttemptsVPAID_ATTEMPTSDemand Only
VPAID AdsVPAID_ADSDemand Only
VPAID Opt OutsVPAID_OPT_OUTSDemand Only
VPAID TimeoutsVPAID_TIMEOUTSDemand Only
VPAID ErrorsVPAID_ERRORSDemand Only
VPAID Opt Out RateVPAID_OPT_OUT_RATEDemand Only
VPAID Timeout RateVPAID_TIMEOUT_RATEDemand Only
VPAID Error RateVPAID_ERROR_RATEDemand Only
WinsWINSDemand Only
VAST Ad RateVAST_AD_RATEDemand Only
VPAID Ad RateVPAID_AD_RATEDemand Only
Win RateWIN_RATEDemand Only
Tag TimeoutsTIMEOUTSDemand Only
Tag Timeout RateTIMEOUT_RATEDemand Only
Tag ErrorsERRORSDemand Only
Tag Error RAteERROR_RATEDemand Only
Playback ErrorsPLAYBACK_ERRORSDemand Only
Playback Error RatePLAYBACK_ERROR_RATEDemand Only
Pre-bid IVT LookupsPRE_BID_IVT_LOOKUPSSupply Only
Pre-bid IVT EvaluationsPRE_BID_IVT_EVALUATIONSSupply Only
Pixalate BlocksPIXALATE_BLOCKSSupply Only
Pixalate EvaluationsPIXALATE_EVALUATIONSSupply Only
Viewability Measured ImpressionsVIEWABILITY_MEASURED_IMPRESSIONSSupply and Demand
Viewable ImpressionsVIEWABLE_IMPRESSIONSSupply and Demand
Anonymous IP BlocksANONYMOUS_IP_BLOCKSSupply Only

Response

If you Include one of the specified dimensions:

  • Demand Partner
  • Demand Order
  • Demand Deal
  • Demand Tag

The report will be considered a "Demand" report, for which a sample response is below (JSON):

{
  "status": "success",
  "data": {
    "header": {
      "reportType": ["DEAL"],
      "reportFormat": "JSON",
      "startDate": "2015-11-17",
      "endDate": "2015-11-18",
      "sort": [{
        "field": "field_name1",
        "order": "desc"
      }],
      "limit": 100
    },
    "entries": [
      {
        "fieldId": "123",
        "fieldName": "Demo",
        "adRequests": 14073369,
        "adResponses": 120570,
        "adImpressions": 52323,
        "adClicks": 16,
        "adCompletedViews": 41490,
        "adWins": 82015,
        "adFirstQuartiles": 47249,
        "adMidpoints": 45324,
        "adThirdQuartiles": 43724,
        "adTimeouts": 2,
        "adErrors": 1674,
        "adVpaidRequests": 0,
        "adVpaidAttempts": 0,
        "revenue": 209.292,
        "siteCost": 159.4753,
        "profit": 49.8167,
        "profitMargin": 0.23802486478222,
        "requestFillRate": 0.00857,
        "fillRate": 0.00857,
        "winRate": 0.68023,
        "efficiencyRate": 0.63797,
        "cpm": 4,
        "ctr": 0.00031,
        "adFirstQuartileRate": 0.90303,
        "adMidpointRate": 0.86623,
        "adThirdQuartileRate": 0.83566,
        "vtr": 0.79296,
        "adTimeoutRate": 0,
        "adErrorRate": 0.00012
      },
      {
        "fieldId": "456",
        "fieldName": "Demo",
        "adRequests": 92587834,
        "adResponses": 729473,
        "adImpressions": 276705,
        "adClicks": 101,
        "adCompletedViews": 145347,
        "adWins": 575801,
        "adFirstQuartiles": 256335,
        "adMidpoints": 236464,
        "adThirdQuartiles": 230565,
        "adTimeouts": 0,
        "adErrors": 32296,
        "adVpaidRequests": 0,
        "adVpaidAttempts": 0,
        "revenue": 830.115,
        "siteCost": 663.80375,
        "profit": 166.31125,
        "profitMargin": 0.20034724104492,
        "requestFillRate": 0.00788,
        "fillRate": 0.00788,
        "winRate": 0.78934,
        "efficiencyRate": 0.48056,
        "cpm": 3,
        "ctr": 0.00037,
        "adFirstQuartileRate": 0.92638,
        "adMidpointRate": 0.85457,
        "adThirdQuartileRate": 0.83325,
        "vtr": 0.52528,
        "adTimeoutRate": 0,
        "adErrorRate": 0.00035
      }
    ]
  },
  "errors": []
}


Otherwise the report will be an "Supply" report - a sample response (JSON):

{
  "status": "success",
  "data": {
    "header": {
      "reportType": ["SITE"],
      "reportFormat": "JSON",
      "startDate": "2015-11-01",
      "endDate": "2015-11-02",
      "sort": [{
        "field": "field_name1",
        "order": "desc"
      }],
      "limit": 100
    },
    "entries": [
      {
        "fieldId": "123",
        "fieldName": "Demo",
        "adOpportunities": 28627833,
		"ineligibleOpsRestrictions ":0,
		"ineligibleOpsDemand ":0,
		"adTagLoads ":1,
		"formatLoads ":0,
		"formatFillRate":0.0,
        "adImpressions": 753155,
        "adClicks": 574,
        "adCompletedViews": 536848,
        "adWins": 838978,
        "adFirstQuartiles": 661927,
        "adMidpoints": 618576,
        "adThirdQuartiles": 573419,
        "revenue": 2830.6745,
        "siteCost": 2334.78,
        "profit": 495.8945,
        "profitMargin": 0.17518598482446,
        "opportunityFillRate": 0.02631,
        "fillRate": 0.02631,
        "efficiencyRate": 0.89771,
        "cpm": 3.7584222371225,
        "ctr": 0.00076,
        "adFirstQuartileRate": 0.87887,
        "adMidpointRate": 0.82131,
        "adThirdQuartileRate": 0.76136,
        "vtr": 0.7128
      },
      {
        "fieldId": "456",
        "fieldName": "Demo",
        "adOpportunities": 0,
		"ineligibleOpsRestrictions ":0,
		"ineligibleOpsDemand ":0,
		"adTagLoads ":1,
		"formatLoads ":0,
		"formatFillRate":0.0,
        "adImpressions": 4,
        "adClicks": 0,
        "adCompletedViews": 0,
        "adWins": 0,
        "adFirstQuartiles": 3,
        "adMidpoints": 3,
        "adThirdQuartiles": 3,
        "revenue": 0.024,
        "siteCost": 0.016,
        "profit": 0.008,
        "profitMargin": 0.33333333333333,
        "opportunityFillRate": 1,
        "fillRate": 1,
        "efficiencyRate": 1,
        "cpm": 6,
        "ctr": 0,
        "adFirstQuartileRate": 0.75,
        "adMidpointRate": 0.75,
        "adThirdQuartileRate": 0.75,
        "vtr": 0
      }
    ]
  },
  "errors": []
}


Applying Filters

Filtering by Multiple Values for the Same Dimension Using an OR Relationship.

This example shows how to filter for mutliple Supply Source IDs.  This will return records where the Supply Source ID is 105350 or 105351.

"filters": [{
	"dimension": "SITE",
	"filters": [{
		"matchType": "id",
		"value": "105350"
	}, {
		"matchType": "id",
		"value": "105351"
	}]
}]

This example shows how to filter for Supply Sources that meet one of the specified requirements.  This will return records where the Supply Source ID is 105350 or "high" is in the Supply Source name.

"filters": [{
	"dimension": "SITE",
	"filters": [{
		"matchType": "id",
		"value": "105350"
	}, {
		"matchType": "partial",
		"value": "high"
	}]
}]


Filtering by Multiple Values for the Same Dimension Using an AND Relationship.

This example shows how to filter for Supply Source IDs that meet both of the specified requirements.  This will return records where the Supply Source ID is 105350 and the Supply Source name includes "high" in it.

"filters": [{
	"dimension": "SITE",
	"filters": [{
		"matchType": "id",
		"value": "105350"
	}]
}, {
	"dimension": "SITE",
	"filters": [{
		"matchType": "partial",
		"value": "high"
	}]
}]


Filtering Values for Different Dimensions

This example shows how to filter for a specific Supply Source ID and a Country requirements.  This will return records where the Supply Source ID is 105350 and the Country is US.

"filters": [{
	"dimension": "SITE",
	"filters": [{
		"matchType": "id",
		"value": "105350"
	}]
}, {
	"dimension": "COUNTRY",
	"filters": [{
		"matchType": "id",
		"value": "US"
	}]
}]
  • No labels