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 ID | Secret Key |
---|---|
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx | 1111111111111111111111111111111111111 |
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:
Type | Example |
---|---|
Unencoded | xxxxxxxxxxxxxxxxxxxxxxxxxxxxx:1111111111111111111111111111111111111 |
Encoded | eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHg6MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMQ== |
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 Method | Endpoint |
---|---|
POST | https://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 Dimension | API Dimension |
---|---|
N/A | OVERVIEW |
Supply Partner | PARTNER |
Supply Source | SITE |
Domain | DOMAIN |
Detected Domain | DETECTED_DOMAIN |
App Name | APP_NAME |
Bundle ID | BUNDLE_ID |
Supply Tag Type | SUPPLY_TAG_TYPE |
LKQD Tag Type | LKQD_TAG_TYPE |
Supply Partner Manager | SUPPLY_PARTNER_ASSIGNED_USER |
Demand Partner | SOURCE |
Demand Order | ORDER |
Demand Deal | DEAL |
Demand Tag | TAG |
Deal Start Date | DEAL_START_TS |
Deal End Date | DEAL_END_TS |
Deal Delivery Goal | DEAL_DELIVERY_GOAL |
Deal Front Load % | DEAL_FRONT_LOAD_PERCENT |
Demand Deal Type | DEAL_TYPE |
Demand Delivery Type | TAG_AD_DELIVERY_TYPE |
Demand Tag Type | TAG_TYPE |
Demand Partner Manager | DEMAND_PARTNER_ASSIGNED_USER |
Programmatic Deal ID | PROGRAMMATIC_DEAL_ID |
Format | FORMAT |
Environment | ENVIRONMENT |
Country | COUNTRY |
Device Type | DEVICE |
OS | OS |
Width X Height | PLAYER_WIDTH_HEIGHT |
Custom 1 | CUSTOM1 |
Custom 2 | CUSTOM2 |
Custom 3 | CUSTOM3 |
Metric Mapping
UI Metric | API Metric | Available Report Types |
---|---|---|
Format Loads | FORMAT_LOADS | Supply Only |
Format Fill Rate | FORMAT_FILL_RATE | Supply Only |
Ineligible Ops - Demand | INELIGIBLE_OPS_DEMAND | Supply Only |
Ineligible Ops - Restrictions | INELIGIBLE_OPS_RESTRICTIONS | Supply Only |
Opportunities | OPPORTUNITIES | Supply Only |
Impressions | IMPRESSIONS | Supply and Demand |
Fill Rate | FILL_RATE | Supply Only |
Efficiency | EFFICIENCY | Supply and Demand |
CPM | CPM | Supply and Demand |
Revenue | REVENUE | Supply and Demand |
Cost | COST | Supply and Demand |
Profit | PROFIT | Supply and Demand |
Profit Margin | PROFIT_MARGIN | Supply and Demand |
CTR | CTR | Supply and Demand |
25% View Rate | FIRST_QUARTILE_RATE | Supply and Demand |
50% View Rate | MIDPOINT_RATE | Supply and Demand |
75% View Rate | THIRD_QUARTILE | Supply and Demand |
100% View Rate | VTR | Supply and Demand |
Clicks | CLICKS | Supply and Demand |
25% Views | FIRST_QUARTILES | Supply and Demand |
50% Views | MIDPOINTS | Supply and Demand |
75% Views | THIRD_QUARTILES | Supply and Demand |
100% Views | COMPLETED_VIEWS | Supply and Demand |
Ad Starts | AD_STARTS | Supply and Demand |
Ad Starts Rate | AD_STARTS_RATE | Supply and Demand |
Viewability Measured Rate | VIEWABILITY_MEASURED_RATE | Supply and Demand |
Viewability Rate | VIEWABILITY_RATE | Supply and Demand |
Request | REQUESTS | Demand Only |
VAST Ads | VAST_ADS | Demand Only |
VPAID Responses | VPAID_RESPONSES | Demand Only |
VPAID Attempts | VPAID_ATTEMPTS | Demand Only |
VPAID Ads | VPAID_ADS | Demand Only |
VPAID Opt Outs | VPAID_OPT_OUTS | Demand Only |
VPAID Timeouts | VPAID_TIMEOUTS | Demand Only |
VPAID Errors | VPAID_ERRORS | Demand Only |
VPAID Opt Out Rate | VPAID_OPT_OUT_RATE | Demand Only |
VPAID Timeout Rate | VPAID_TIMEOUT_RATE | Demand Only |
VPAID Error Rate | VPAID_ERROR_RATE | Demand Only |
Wins | WINS | Demand Only |
VAST Ad Rate | VAST_AD_RATE | Demand Only |
VPAID Ad Rate | VPAID_AD_RATE | Demand Only |
Win Rate | WIN_RATE | Demand Only |
Tag Timeouts | TIMEOUTS | Demand Only |
Tag Timeout Rate | TIMEOUT_RATE | Demand Only |
Tag Errors | ERRORS | Demand Only |
Tag Error RAte | ERROR_RATE | Demand Only |
Playback Errors | PLAYBACK_ERRORS | Demand Only |
Playback Error Rate | PLAYBACK_ERROR_RATE | Demand Only |
Pre-bid IVT Lookups | PRE_BID_IVT_LOOKUPS | Supply Only |
Pre-bid IVT Evaluations | PRE_BID_IVT_EVALUATIONS | Supply Only |
Pixalate Blocks | PIXALATE_BLOCKS | Supply Only |
Pixalate Evaluations | PIXALATE_EVALUATIONS | Supply Only |
Viewability Measured Impressions | VIEWABILITY_MEASURED_IMPRESSIONS | Supply and Demand |
Viewable Impressions | VIEWABLE_IMPRESSIONS | Supply and Demand |
Anonymous IP Blocks | ANONYMOUS_IP_BLOCKS | Supply 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" }] }]