What is the LiveIntent Reporting API?
The reporting API provides simple access and easier connections when pulling reports from LiveIntent.
đĄ Please Note:
|
Why use the Reporting API?
Hereâs a snapshot of what you can expect from the LiveIntent Reporting API:
- Easier connection: just request an Access Token from the authorization server, then attach the token as an HTTP header when making API requests
- Increased ways to pull data with new splits: Dive further into understanding your RTB activity with new splits like âBidder IDâ, âBidder Seatâ and âDeal IDâ, plus track how many ad requests are fulfilled with âFill Rateâ
- Faster reporting: Summarized, packaged data and reduction in API traffic allows for faster reporting turnaround â from minutes to seconds
Check out set-up instructions below.
Authentication
LiveIntent uses OAuth2 for authentication.
The idea is simple - request an Access Token from the Authorization Server, then attach the obtained Access Token as an HTTP header when making requests to the API.
All requests to the API must include an Authorization HTTP header, with its value containing the retrieved Access Token.
In order to retrieve an Access Token, please submit your Client Credentials â a LiveIntent username + password pair â to the token-endpoint, and in exchange receive an Access Token.
This scheme is only appropriate when a confidential app performs server-to-server communication.
1.1 Prerequisites
Before your app can send requests to the Authorization Server, you must obtain your username and password from your LiveIntent account manager. Without those valid credentials you won't be able to receive Access Tokens from the Authorization server.
đĄ Please Note: The LiveIntent username/password must be added to any request made at the Authorization Server, so it can know which 3rd-party is making this request. |
1.2 Client Credentials
The Client Credentials scheme involves the client-app sending a LiveIntent username and password in order to obtain an appropriate Access Token.
1.2.1 Request Structure
POST /auth/login/
Host: https://connect.liveintent.com
Content-Type: application/json
Accept: application/json
BODY (raw) â JSON (application/json) { 'username': 'LiveIntent username', 'password': 'LiveIntent password' }
1.2.2 Example Request and Response
{ 'username': 'mary.lou@liveintent.com', 'password': 'P@$$word100' }
{ 'token': 'abcdefghijklmnopqrstuvwxyz-1234567890.zyxwvutsrqponmlkjihgfedcba', 'username': 'mary.lou@liveintent.com', 'userID': 'ajiwg02tkt4jlshxit20et2nkjlx', 'refreshToken': '03xektjekwlvcjlbhd235266skdjfksj' }
1.3 Execute Query
With your Access Token, you can now execute valid queries via the LiveIntent Reporting API.
1.3.1 Request Structure
POST /reporting/api/executeQuery Host: https://connect.liveintent.com
*Please note that executeQuery is case sensitive.
Headers Authorization: 'Bearer {token}' Content-Type: application/json
Body (raw) { 'type': {String}, 'interval': {Object}, 'granularity': {String}, 'splits': ['String1', 'String2', 'String3'], 'metrics': ['String1', 'String2', 'String3'], 'filters': [{ 'dimension': 'StringA', 'operator': 'OperatorB', 'values': ['StringC'] }, { 'dimension': 'StringX', 'operator': 'OperatorY', 'values': ['IntegerZ'] }] }
1.3.2 Example Response
{
'type': 'publisher',
"interval": {
'type': 'dynamic',
'value': 'YTD'
},
'granularity': 'all',
'splits': ['Demand Type', 'Mail Type'],
'metrics': ['NetECPM', 'First Impressions', 'CTR', 'CCR'],
'filters': [{
'dimension': 'Publisher ID',
'operator': 'equals',
'values': [10000]
},
{
'dimension': 'Section ID',
'operator': 'equals',
'values': [12345, 67890]
}]
}
[
{
'version': 'v1',
'timestamp': '2017-01-01T00:00:00.000Z',
'event': {
'CTR': 0,
'Impressions': 200000,
'CCR': 0,
'Demand Type': 'default',
'Conversions': 0,
'First Impressions': 188995,
'Publisher Revenue': 590.09886199980974197,
'NetECPM': 2.95049431139847639,
'Clicks': 0,
'Mail Type': "marquee"
}
},
{
'version': 'v1',
'timestamp': '2017-01-01T00:00:00.000Z',
'event': {
'CTR': 0.20833333333333333,
'Impressions': 12000,
'CCR': 0,
'Demand Type': 'default',
'Conversions': 0,
'First Impressions': 11580,
'Publisher Revenue': 111.11303799599409103,
'NetECPM': 9.25941983373263375,
'Clicks': 2500,
'Mail Type': 'newsletter'
}
}
]
â ď¸ Please Note: Once generated, an Access Token has a 12-hour expiry period. After 12 hours the Access Token is revoked, you will need to request another one, either by submitting a Refresh Token or by initiating a new authentication flow. |
đĄ Please Note: The Access Token should be attached to any request made at the API. An API call which is missing the Authorization header will result in a 401 Unauthorized error response. |
đĄ Please Note: If a request to the API contains an invalid or expired Access Token, the request will result in a 401 Unauthorized error response. |
Valid Request Entries
Valid Types: 'publisher', 'advertiser'
Valid Granularity Values: 'day', 'week', 'month', 'all'
Valid Absolute Intervals:
{
'type': 'absolute',
'start': '2017-01-10',
'end': '2017-01-20'
}
Note: For 'type':'absolute', 'start' and 'end' must be different dates. You cannot have '2018-03-01' for both 'start' and 'end'. |
Valid Dynamic Intervals:
{
'type': 'dynamic',
'value': 'WTD'
}
Valid Value (Meaning) |
⢠'WTD' (Week to Date), ⢠'MTD' (Month to Date), ⢠'QTD' (Quarter to Date), ⢠'YTD' (Year to Date), ⢠'1' (Yesterday), ⢠'7' (Last 7 days), ⢠'30' (Last 30 days), ⢠'90' (Last 90 days), ⢠'LM' (Last Month) |
Valid Splits
Advertiser | Publisher |
Exact splits
|
Exact splits
|
Inexact splits (estimated values based on sampled data)
|
Inexact splits (estimated values based on sampled data)
|
Valid Metrics
Advertiser | Publisher |
|
|
Valid Filters:
{
âdimensionâ: String,
âoperatorâ: String,
âvaluesâ: Array of String/Number
}
Valid operator: [âequalsâ, ânot equalsâ]
Valid Filter dimensions & values
DSP |
SSP |
||
Dimension |
Values |
Dimension |
Values |
Demand Type |
âdefaultâ, âdirectâ, âhouseâ |
Demand Type |
âdefaultâ, âdirectâ, âhouseâ |
Advertiser ID |
numeric value. Ex: 12345 |
Section ID |
numeric value. Ex: 12345 |
Campaign ID |
numeric value. Ex: 12345 |
Advertiser ID |
numeric value. Ex: 12345 |
Line Item ID |
numeric value. Ex: 12345 |
Creative ID |
numeric value. Ex: 12345 |
Creative ID |
numeric value. Ex: 12345 |
Publisher ID |
numeric value. Ex: 12345 |
Publisher ID |
numeric value. Ex: 12345 |
Template ID |
numeric value. Ex: 12345 |
Age |
ââ, â18-20â, â21-24â, â25-34â, â35-44â, â45-54â, â55-64â, â65+â |
Mail Type |
âcontentâ, âdedicatedâ, âmarqueeâ, ânativeâ, ânewsÂÂletterâ, âskinâ |
Gender |
ââ, âmaleâ, âfemaleâ |
List |
List id <String> |
Device Type |
ââ, âPCâ, âPhoneâ, âTabletâ, âGoogleProxyâ, âMediaCenterâ |
Email Domain |
Ex: Yahoo.com, gmail.com |
Metro |
numeric value between 500 - 881 |
Publisher Name |
âXYZ Mediaâ |
Advertiser Name |
âABC Apparelâ |
Template Name |
âMonday Newsletterâ |
Insertion Order Name |
âInsertion Order for 2017â |
Section Name |
âAfternoon Edition Marqueeâ |
Campaign Name |
âWinter 2017 Promotionâ |
Age |
ââ, â18-20â, â21-24â, â25-34â, â35-44â, â45-54â, â55-64â, â65+â |
Line Item Name |
âNYC Winter 2017 Promoâ |
Gender |
ââ, âmaleâ, âfemaleâ |
Creative Name |
âNYC_Winter 2017 Promo_300x250â |
Device Type |
ââ, âPCâ, âPhoneâ, âTabletâ, âGoogleProxyâ, âMediaCenterâ |
Creative Size |
â300x250â â970x250â â728x90â â970x550â â[custom width]x[custom height]â |
Device Maker |
âAlcatelâ âAcerâ âAmazonâ âAppleâ âAsusâ âBeelineâ âBlackBerryâ âFlyâ âFujitsuâ âGoogleProxyâ âHTCâ âHuaweiâ âKyoceraâ âLGâ âLenovoâ âMTSâ âMedionâ âMeizuâ âMotorolaâ âNECâ âNokiaâ âODYSâ âPanasonicâ âPantechâ âPhillipsâ âPrestigioâ âSamsungâ âSharpâ âSonyâ âWexlerâ âZTEâ |
Browser |
âAOLâ âAndroidâ âAndroid_Appâ âBlackBerryâ âBrowserNGâ âChromeâ âDalvikâ âDolfinâ âEdgeâ âEudoraâ âEvolutionâ âFirefoxâ âGoogleProxyâ âGoogleSearchAppâ âMSIEâ âMSOEâ âMacMailâ âNetNewsWireâ âNintendoBrowserâ âOperaâ âOperaMiniâ âOperaMobiâ âOtherBrowsersâ âOutlookâ âOviâ âSafariâ âSamsungBrowserâ âSparrowâ âSpotifyâ âThunderbirdâ âUCBrowserâ âYandexBrowserâ âiOS_Appâ |
Metro |
numeric value between 500 - 881 |
OS |
âAndroidâ âBlackBerryâ âBlackBerryTabletâ âChromeOSâ âGoogleProxyâ âLinuxâ âOSXâ âSymbianâ âWindowsâ âWindowsPhoneâ âiOSâ |
Browser |
âAOLâ âAndroidâ âAndroid_Appâ âBlackBerryâ âBrowserNGâ âChromeâ âDalvikâ âDolfinâ âEdgeâ âEudoraâ âEvolutionâ âFirefoxâ âGoogleProxyâ âGoogleSearchAppâ âMSIEâ âMSOEâ âMacMailâ âNetNewsWireâ âNintendoBrowserâ âOperaâ âOperaMiniâ âOperaMobiâ âOtherBrowsersâ âOutlookâ âOviâ âSafariâ âSamsungBrowserâ âSparrowâ âSpotifyâ âThunderbirdâ âUCBrowserâ âYandexBrowserâ âiOS_Appâ |
|
|
OS |
âAndroidâ âBlackBerryâ âBlackBerryTabletâ âChromeOSâ âGoogleProxyâ âLinuxâ âOSXâ âSymbianâ âWindowsâ âWindowsPhoneâ âiOSâ |
|
|
Bidder ID |
numeric value. Ex: 12345 |
|
|
Bidder Seat |
string value. Ex: â1234_56â |
|
|
Bidder Campaign ID |
string value. Ex: 12345 |
|
|
Deal ID |
string value. Ex: âABC_DEâ |
|
|
Insertion Order Name (or ID) |
âDirect Sold Insertion Order for 2017â |
|
|
Campaign Name (or ID) |
âWinter 2017 Direct Soldâ |
|
|
Line Item Name (or ID) |
âNYC Winter 2017 Direct Soldâ |