Connecting to LiveIntent's Reporting API

 

What is the LiveIntent Reporting API?

We’re excited to share a new and improved API, providing simple access and easier connections. While the current reporting API will be available until March 1st, we encourage adoption of the new API so you can take advantage of the new features as early as possible! 

Why use the new Reporting API?

Here’s a snapshot of what you can expect from the new 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
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”

            }

 

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

DSP  SSP 

Exact data

  • Demand Type
  • Advertiser ID
  • Advertiser Name
  • Campaign ID
  • Campaign Name
  • Line Item ID
  • Line Item Name
  • Creative ID
  • Creative Name
  • Creative Size
  • Publisher ID

 

 

 

 

 

 

 

 Exact data

  • Demand Type
  • Mail Type
  • Advertiser ID
  • Advertiser Name
  • Creative ID
  • Creative Name
  • Publisher ID
  • Publisher Name
  • Template ID
  • Template Name
  • Section ID
  • Section Name
  • Campaign ID
  • Campaign Name
  • Line Item ID
  • Line Item Name
  • Creative ID
  • Creative Name
  • Creative Size
  • Bidder ID
  • Bidder Seat
  • Bidder Campaign ID
  • Deal ID
 

Inexact data (estimated values based on sampled data)

  • Age
  • Gender
  • Device Type
  • Metro (DMA)
  • Country
  • Region
  • OS
  • Browser

Inexact data (estimated values based on sampled data)

  • List
  • Advertiser Domain
  • Email Domain
  • Country
  • Region
  • Metro
  • Age
  • Gender
  • Device Type
  • Device Maker
  • OS
  • ISP

 

Valid Metrics

DSP  SSP
  • Impressions
  • Clicks
  • Conversions
  • Post-view Conversions
  • Advertiser Spent
  • Gross ECPM
  • Gross ECPC
  • Gross ECPA
  • CTR
  • CCR
  • First Impressions
  • Impressions
  • Reopens
  • Clicks
  • Conversions
  • Post-view Conversions
  • Publisher Revenue
  • Net ECPM
  • CTR
  • CCR
  • Fill Rate

 

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”

“160x600”

“[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”

Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk