NAV
Code Examples

Reporting for Advertisers

Introduction

While LiveIntent provides a reporting interface within its application, many clients use an in-house or third party data management platform to centralize reporting and analytics across the many other ad tech services they use. With LiveIntent’s reporting API, clients can access their LiveIntent data in an automated fashion in order to more easily export it to their tool of choice.

Overview

LiveIntent’s reporting API allows users to receive specific data on demand to better understand their performance on LiveIntent’s platform. When calling the API, only a few key pieces of information must be specified:

  1. id, seed, hash – Authentication information so only data relevant to you is returned.
  2. splits – How you want to break out your data into records or rows. • For example, as an agency, you can separate out the data by advertiser ID, campaign ID, or creative ID. • Additionally, you can split the data by demographic information like the age or gender of users viewing ads or by the date or time that ads were viewed.
  3. columns – The information you want to see for each record or row. • You can choose to view metrics like impressions, clicks, and conversions as well as attributes. For example, if you chose advertiser ID for splits, you can view attributes like advertiser name and advertiser domain.
  4. startDate, endDate – The date range for which you want to pull the information.

The API described in this document powers the reporting interface in the LiveIntent application. While some of the capabilities in the UI are not available via direct access to the API and vice versa, the reporting interface remains a useful introduction to the API.

Guidelines

4.1 Authentication

Authentication for LiveIntent’s reporting API is token-based. As part of onboarding to the API, LiveIntent will assign a user ID and a private token, which must be used to populate specific parameters in every request.

See section 5.5 for required parameters.

4.2 Request Limits

Usage of the API is limited to 1 request per second for each user.

Request Information

5.1 Endpoint

The endpoint for the reporting API is https://api.liveintent.com/api. Requests must be made using the POST method and HTTPS protocol.

5.2 Headers
Header Description Value
Content-Type Identifies the request format to ensure the query is parsed correctly.If not specified, the API will try to autodetect the format. One of the following: application/json text/xml application/xml
Accept Specifies the response format. If not specified, the response will be returned in the same format as the request. One of the following: application/json, application/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/html
5.3 Request Format

Requests can be formatted as JSON or XML. Request parameters include scalars (single value such as an integer or string), objects (comma-separated list of key-value pairs), and arrays of scalars or objects.

5.3.1 JSON Format
{
    "scalar": "value",
    "object": {
        "key1": "value1",
        "key2": "value2"
    },
    "array":
    [
    "element1",
    "element2"
],
}
5.3.2 XML Format
<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <scalar>value</scalar>
  <object>
    <key1>value1</key1>
    <key2>value2</key2>
  </object>
    <array>element1</array>
  <array>element2</array>
</data>
5.4 Request Body
Parameter Required Data Type Description
id required string User ID provided by LiveIntent when onboarding to the API.
seed required integer UNIX timestamp. Must be unique for every request and be within 5 minutes of the time the request is actually sent.
hash required string SHA1 hash of the concatenation of the private token (provided by LiveIntent when onboarding to the API) and seed in that order.
function optional string Indicates the operation to perform. At this time, only “data” is allowed. If not specified, the default value is “data”.
startDate required string The start date of the date range for which data is requested. The value for startDate cannot be today’s date or later, and the difference between the startDate and endDate cannot be more than one year.,Can be specified in the following ways:,·,A specific date formatted as “YYYY-MM-DD”, a specific or relative date using any format described in http://php.net/manual/en/datetime.formats.php, a relative date matching the pattern “[first/last] day of [this/last/previous/next] [week/isoweek/quarter/year]”
endDate required string The end date of the date range for which data is requested. The value for endDate cannot be today’s date or later, and the difference between the startDate and endDate cannot be more than one year.
splits required array of strings Determines how the data is grouped into records. At this time, the maximum supported array size is one. See section 5.4.1 for allowed elements.
columns required array of strings Specifies which attributes and metrics to return for each record. Columns are returned in the same order in which they are requested. See section 5.4.2 for allowed elements.
filters optional array of objects Applies additional restrictions to the data so that only certain rows and data that meet the filter criteria are returned. See section 5.4.3 for more details.
sort optional object Determines the order in which records are returned. If not specified, records will be returned in descending order for numeric values (except IDs, age, zip, date, and time values) and ascending order otherwise based on the values for the splits parameter. See section 5.4.4 for more details.
format optional object Specifies whether to include column names and totals. If not specified, column names are returned as the first record and column totals are returned as the last record for Excel and HTML response formats; they are not returned for all other cases. See section 5.4.5 for more details.
5.4.1 Splits

Using the splits parameter, you can specify how to group the data into records. The value you specify for the type parameter dictates which elements can be used for the splits parameter. The API will return an error if the split requested is unsupported for the specified type.

Note that depending on the split you use, the metric data returned may be inexact. Because of the large amount of data that has to be processed, the data for certain splits is compressed, resulting in a margin of error in the reported data.

Splits Element Exact Data
advertiser_id exact
advertiser_domain inexact
publisher_id exact
publisher_domain inexact
ad_slot_id exact
template_id exact
insertion_order_id exact
campaign_id exact
campaign_type exact
demand_type exact
strategy_id exact
creative_id exact
size exact
year exact
month exact
year_month exact
day exact
day_hour inexact
hour inexact
age inexact
gender inexact
country inexact
region inexact
metro inexact
zip inexact
device_maker inexact
device_model inexact
device_type inexact
os inexact
browser inexact
5.4.2 Columns

The columns parameter specifies which metrics and attributes to return for each record.

The metrics allowed is dependent on the type parameter. If the column requested is unsupported for the specified type, the column will not be returned in the response.

Attributes correspond to the element chosen for the splits parameter. If the specified column is unrelated to the split, “null” will be returned for the column value.

Column Type Column Element Supported Splits
metric impressions -
unique_impressions -
reopens -
clicks -
conversions -
post_view_conversions -
spend -
gross_cpm -
gross_cpc -
gross_cpa -
ctr -
ccr -
attribute publisher_id · publisher_id
· publisher_domain
· template_id
· ad_slot_id
publisher_name · publisher_id
· publisher_domain
· template_id
· ad_slot_id
publisher_domain · publisher_id
· publisher_domain
· template_id
· ad_slot_id
template_id · template_id
· ad_slot_id
template_name · template_id
· ad_slot_id
ad_slot_name ad_slot_id
advertiser_id · advertiser_id
· insertion_order_id
· campaign_id
· strategy_id
advertiser_name · advertiser_id
· insertion_order_id
· campaign_id
· strategy_id
advertiser_domain · advertiser_id
· insertion_order_id
· campaign_id
· strategy_id
insertion_order_id · insertion_order_id
· campaign_id
· strategy_id
insertion_order_name · insertion_order_id
· campaign_id
· strategy_id
campaign_id · campaign_id
· strategy_id
campaign_name · campaign_id
· strategy_id
campaign_type · campaign_id
· strategy_id
demand_type · campaign_id
· strategy_id
strategy_name strategy_id
creative_name creative_id
5.4.3 Filters

The filters parameter allows you to apply additional restrictions to the data so that only certain rows and data that meet the filter criteria are returned.

Each criterion is a separate object comprised of the below parameters. If multiple filters are included, “AND” Boolean logic is applied, meaning that only data that meets all filter criteria will be returned.

Parameter Required Data Type Description
dimension required string One of the allowed elements for the splits parameter.
Note that any split can be chosen for the filter regardless of the type parameter.
operator required string Specifies the relationship between the dimension and values.
At this time only “equals” and “not equals” are supported.
values required array An array of values corresponding to the specified dimension.
5.4.4 Sort

The sort parameter determines the order in which records are returned.

Each sorting rule is a key-value pair in the sort object. Multiple sorting rules can be specified as a comma-separated list of key-value pairs in the sort object, in which case the sorting rules are applied in the order specified in the object.

Parameter Required Data Type Description
Can be any of the elements included in the request’s splits or columns parameter. required string Determines how to order the values of the sort key.
Allowed values are “asc” for ascending order and “desc” for descending order.
If unspecified, “desc” will be used for numeric values (except IDs, age, zip, date, and time values); other “asc” will be used.
5.4.5 Format

The format parameter specifies whether and where to include column names and totals.

The format is an object with the below parameters. At least one parameter must be specified when using the format object.

Parameter Required Data Type Description
columnNames optional string Determines whether to include column names as a record.
Allowed values are “top” to return them as the first record or “off” to not include them.
If not specified, the default value is “top” for Excel and HTML response formats and “off” for all other cases.
columnTotals optional string Determines whether to include column totals as a record.
Allowed values are “top” to return them as the first record, “bottom” to return them as the last record, or “off” to not include them.
If not specified, the default value is “bottom” for Excel and HTML response formats and “off” for all other cases.
5.5 Code Examples
5.5.1 JSON
{
    "function": "data"
    "filters":[
    {
        "dimension":"country",
        "operator":"equals",
        "values":[
          "US"
        ]
    }
    ],
    "sort":{  
        "impressions":"desc",
        "advertiser_id":"asc"
    },
    "format":{  
        "columnNames":"top",
        "columnTotals":"bottom"
    }
    "columns":[
    "impressions",
    "clicks",
    "conversions",
    "spend"
    ],
    "splits":[
        "advertiser_id"
    ],
    "startDate":"2015-06-01",
    "endDate":"2015-06-30",
    "seed":1436276847,
    "hash":"47e77781785bdc7a25dfb3a355127dd55bd0de6f",
    "id":"73dbac12153211e5805922000a970989"
}
5.5.2 XML
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <function/>
    <filters>
        <dimension>country</dimension>
        <operator>equals</operator>
        <values>US</values>
    </filters>
    <sort>           
        <impressions>desc</impressions>           
        <advertiser_id>asc</advertiser_id>     
    </sort>
    <format>           
        <columnNames>top</columnNames>           
        <columnTotals>bottom</columnTotals>     
    </format> 
    <columns>impressions</columns>
    <columns>clicks</columns>
    <columns>conversions</columns>
    <columns>spend</columns>
    <splits>advertiser_id</splits>
    <startDate>2015-06-01</startDate>
    <endDate>2015-06-30</endDate>
    <seed>1436280219</seed>
    <hash>fc33113022f4ac2e0c11d7141ed9dc7563eede34</hash>
    <id>73dbac12153211e5805922000a970989</id>
</data>

Response Information

6.1 Response Format

Data can be returned as JSON, XML, HTML, or an Excel spreadsheet. You can specify the response format you would like returned in the request header (see section 5.3).

6.2 Response Body

The reponse body only includes requested fields as specified in the splits and columns parameters.

The below table summarizes all possible response fields.

Field Data Type Description
publisher_id string Unique identifier assigned to each publisher by LiveIntent.
publisher_name string Name assigned to each publisher.
publisher_domain string The publisher’s primary domain.
template_id string Unique identifier assigned to each template by LiveIntent.
template_name string Name assigned to each template.
ad_slot_id string Unique identifier assigned to each ad slot by LiveIntent.
ad_slot_name string Name assiged to each ad slot.
advertiser_id string Unique identifier assigned to each advertiser by LiveIntent.
advertiser_name string Name assigned to each advertiser.
advertiser_domain string The advertiser’s primary domain.
insertion_order_id string Unique identifier assigned to each insertion order by LiveIntent.
insertion_order_name string Name assigned to each insertion order.
campaign_id string Unique identifier assigned to each campaign by LiveIntent.
campaign_name string Name assigned to each campaign.
campaign_type string The type of campaign; limited one of the following values:
· newsletter
· roadblock
· takeover
· dedicated
· display
demand_type string The demand source; limited to one of the following values:
· direct
· house
· exchange
· fallback_ads
strategy_id string Unique identifier assigned to each strategy by LiveIntent.
strategy_name string Name assigned to each strategy.
creative_id string Unique identifier assigned to each creative by LiveIntent.
creative_name string Name assigned to each creative.
size string Sizes of ads that are viewed in the format “wxh”
year integer Year that ads are viewed in the format “YYYY”
month integer Month that ads are viewed in the format “MM”
year_month date The year and month that ads are viewed in the format “YYYY MM”
day date The date that ads are viewed in the format “YYYY-MM-DD”
day_hour datetime The date and time that ads are viewed in the format “YYYY-MM-DD HH”
Note that data returned for day and hour is inexact.
hour time The hour that ads are viewed from 0 through 24.
Note that data returned for hours is inexact.
age string Age group to which the user viewing ads belongs; limited to one of the following values:
· 18-20
· 21-24
· 25-34
· 35-44
· 45-54
· 55-64
· 65+
Note that data returned for ages is inexact.
gender string Perceived gender of the user viewing the ads; limited to one of the following values:
· male
· female
Note that data returned for genders is inexact.
country string Country in which the ads are viewed.
Note that data returned for countries is inexact.
region string Regional area such as state or province in which the ads are viewed.
Note that data returned for regions is inexact.
metro string Designated Market Area (DMA) in which the ads are viewed; only DMA codes are returned.
Note that data returned for metros is inexact.
zip string Zip code in which the ads are viewed.
Note that data returned for zip codes is inexact.
device_maker string Brand of device used to view ads.
Note that data returned for device brands is inexact.
device_model string Specific model of phone or tablet used to view ads.
Note that data returned for device models is inexact.
device_type string The type of device used to view ads; limited to one of the following values:
· PC
· Phone
· Tablet
· GoogleProxy (using the Gmail web client)
· Windows Media Center
Note that data returned for device types is inexact.
os string Operating system on which ads are viewed.
Note that data returned for operating systems is inexact.
browser string Browser or email client used to view ads.
Note that data returned for browsers is inexact.
email_domain string Email domain of the recipient viewing ads.
Note that data returned for email domains is inexact.
impressions integer Total ad impressions and views (sum of unique impressions and shares and reopens).
unique_impressions integer Number of times an ad is viewed for the first time (does not include re-opens and shares).
reopens integer Number of subsequent ad views after an email has been opened the first time (includes shares and email forwards).
clicks integer Number of clicks an ad received.
conversions integer Number of conversions logged after an ad is clicked.
post_view_conversions integer Number of conversions logged after is viewed, but not clicked.
spend decimal Total spend of an ad campaign.
gross_cpm decimal Gross cost per thousand impressions.
gross_cpc decimal Gross cost per click.
gross_cpa decimal Gross cost per acquisition.
ctr decimal Clickthrough rate, i.e. percentage of impressions that received clicks.
ccr decimal Click-to-conversion ratio, i.e. percentage of clicks that converted.
6.3 Code Example
6.3.1 JSON
[  
   {  
      "advertiser_id":"advertiser_id",
      "impressions":"impressions",
      "clicks":"clicks",
      "conversions":"conversions",
      "spend":"spend"
   },
   {  
      "advertiser_id":"238",
      "impressions":24715,
      "clicks":20,
      "conversions":1,
      "spend":33.130296
   },
   {  
      "advertiser_id":"1310",
      "impressions":16800,
      "clicks":131,
      "conversions":0,
      "spend":122.823748
   },
   {  
      "advertiser_id":"(totals)",
      "impressions":41515,
      "clicks":151,
      "conversions":1,
      "spend":155.954044
   }
]
6.3.2 XML
<?xml version="1.0" encoding="UTF-8"?> 
<root>    
    <advertiser_id>advertiser_id</advertiser_id>       
        <impressions>impressions</impressions>     
        <clicks>clicks</clicks>     
        <conversions>conversions</conversions>    
        <spend>spend</spend>    
    <advertiser_id>238</advertiser_id>     
        <impressions>24715</impressions>     
        <clicks>20</clicks>     
        <conversions>1</conversions>     
        <spend>33.130296</spend>    
    <advertiser_id>1310</advertiser_id>    
        <impressions>16800</impressions>     
        <clicks>131</clicks>     
        <conversions>0</conversions>      
        <spend>122.823748</spend>    
    <advertiser_id>(totals)</ advertiser_id>     
        <impressions>41515</impressions>     
        <clicks>151</clicks>     
        <conversions>1</conversions>    
          <spend>155.954044</spend> 
</root>
6.4 Response Codes
Code HTTP Status Description
10, 11 401 Authentication failed
20 401 Authentication failed – invalid seed
21 401 Seed too low
22 401 Seed timestamp failed – seed not within 5 minutes of UNIX timestamp
30 401 Authentication failed – token not found
31 401 Authentication failed – invalid hash
40-44, 900 403 Permission denied
51 429 Query limit exceeded
52 401 Authentication failed – invalid id
53, 102-109, 701-702, 1002-1004, 1006 500 Internal error
(except for 701-702)
200 - OK – request succeeded
201 - No data returned
300 - Dimensions removed
901 403 Required parameter missing
902 403 Incorrect type
903 403 Invalid input
1000 400 Invalid content-type
1001 404 Invalid function
1005 403 Invalid dimension