Description: This document lists and describes the API calls for obtaining attribution and onboarding data for measuring and optimizing TV campaigns.
Attribution API Overview
After your traffic has been modeled and attributed in your InnovidXP platform, the Innovid Attribution API can provide flexible access to the attributed TV spot data and metadata.
Attribution data is extracted from InnovidXP using the Attribution API at a partner level, where a partner is generally an entity responsible for one or more end clients and their associated brands. When an end client deals with Innovid directly, the partner level is synthesized to allow the use of the Attribution API.
Typical workflows with the Attribution API involve multiple calls to different API endpoints, extracting and passing parameterized data to achieve the required results in the end application. The Attribution API lets users automate the acquisition of attribution data in this manner, at a desired granularity, for inclusion in their data analysis or presentation to end clients.
Onboarding API Overview
Onboarding data is extracted from InnovidXP using the Onboarding API.
Authentication
The InnovidXP API requires you to authenticate with the InnovidXP platform to access your client and brand data. You must set up and use basic authentication to access the available InnovidXP Attribution API endpoints. This requires a Basic HTTP Authorization header to be sent with each request.
For more information on the HTTP Authorization header, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization.
Making calls to the API
The API uses basic authentication over an https connection. To authenticate, you must send an HTTP Authorization header with every API call, containing a hash of the username and password specified previously for use with the Attribution API.
-
To authenticate with the Attribution API using the curl command, use the following command line, substituting the username and password of the API user:
curl --user <api_username>:<api_password> https://apixx.tvsquared.com/... - Alternatively, you can use a separate 3rd-party command line tool or your preferred programming language to generate the authentication header.
Attribution API
The InnovidXP Attribution API provides flexible access to automate the acquisition of attributed TV spot data and metadata from the platform at a desired granularity.
This section lists all the InnovidXP endpoints and associated information.
Setup
The InnovidXP Attribution API is a standard RESTful HTTP API based on GET, POST requests with JSON formatted responses.
The Attribution API exclusively uses the HTTPS protocol for encryption and data security - plain HTTP requests are blocked and will not be successful.
All Attribution API endpoints share the same base URL, accessed at the partner level:
https://<partnerdomain>.tvsquared.com/api/v2/ |
Where <partnerdomain> is a unique identifier for the API in the format api-xx. Use your <partnerdomain> for the base URL for all Attribution API endpoints.
Parameters
The InnovidXP Attribution API follows several conventions for parameters passed and returned in API calls. All date and time parameters are formatted in the ISO standard as follows unless otherwise stated:
- Date: YYYY-MM-DD
- Datetime: YYYY-MM-DDThh:mm:ss
Client ID and brand ID are used in several Attribution API endpoints, identified by <clientid> and <brandid>.
These are unique identifiers for the required client and brand and can be derived from the InnovidXP portal or the response to an Inventory request.
Inventory
Performing a GET request at the following endpoint returns basic inventory information regarding any partners, clients, or brands you can access.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution |
Response format
{
|
The partner details include the title, ID, API domain, and partner domain. Client details include title, ID, and associated brand titles and IDs. This endpoint can get the appropriate client and brand IDs for subsequent API requests.
Brand inventory
Performing a GET request to this endpoint returns details regarding a brand's spot and action metrics and timeseries splits.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/<brandid> |
Response format
{
|
Parameters
| Parameter | Description |
| MEDIA | A list of the media types, for example, web, app, phone, SMS. |
| SMETRICS | A list of the available spot metrics, for example, audience and cost. |
| TSGRANS | A list of the time frames you can use to explore your data, for example, minute, week, and month. |
| UMETRICS |
A list of available response metrics, for example, region and lag. |
| TSUMSPLITS | A list of timeseries response metric splits, for example, product, lag, and region. These parameters are generally dictionary keys with lists of more specific data as values. For example, a medium-time response metric split may contain web or phone as values. |
| TSRTMTYPES |
These parameters allow access to timeseries data for different groupings of the data, as follows:
|
| UACTIONS | A list of available response actions, for example, allresponse, signup, and subscription |
| TSREFS | A list of referrers names, for example, search, paysearch, tvwebsite, banner. |
Retrieve spot attribution
Performing a GET request will retrieve a day's worth of attributed spots for the day specified through the URL parameters.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/<brandid>/spotsjson/<year>/<month>/<day> |
The returned data includes details about the spot time, daypart, the program the spot appeared in, and specific spot and response metric data.
Response format
{
|
Retrieve spot columns
This GET request will retrieve a list of the column names for spots in a supplied date range.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/ |
The <y1>, <y2> parameters represent the start and end dates of the date range you want to view spot column names for.
Response format
{
|
The response format is a simple list of spot column names. These column names can then retrieve specific information in subsequent calls. Note that the column types vary across date ranges depending on what data was supplied in the spots and responses during this time.
Additional information
A full list of spot column names:
| Column Name | Type | Description |
| datetime | Ordinal | Date time the spot was transmitted: YYYY-MMDDThh:mm:ss |
| daypart | Ordinal | Daypart the spot was transmitted during |
| length | Ordinal | Length of spot in seconds |
| saleshouse | Ordinal | Saleshouse this spot was bought via |
| programme | Ordinal | Program the spot was transmitted during |
| genre | Ordinal | Genre of the program the spot was transmitted during |
| country | Ordinal | Country the spot was transmitted in |
| region | Ordinal | Region the spot was transmitted in |
| clocknumber | Ordinal | Clocknumber |
| clockgroup | Ordinal | Clocknumber group name |
| chgenre | Ordinal | Genre of the channel/station the spot was transmitted on |
| spotid | Ordinal | Our internal ID for the spot |
| feed | Ordinal | Spot feed (U.S. only) |
| sm.audience.v | Spot metric | Total audience for the spot |
| sm.cost.v | Spot metric | Total cost of the spot |
| sm.spots.v | Spot metric | Number of spots composing the spot (for pre-aggregated spots) |
| um.\<action>\.m.session | Response metric | Total number of response \<action>\ sessions attributed to the spot |
| um.\<action>\.m.revenue | Response metric | Total response \<action>\ revenue attributed to the spot |
| um.\<action>\.region.\<regionid>\.m.session | Response metric | Number of response \<action>\ sessions attributed to the spot in \<regionid>\ |
| um.\<action>\.m.region\<regionid>\.m.revenue | Response metric | Total revenue of response \<action>\ attributed to the spot in \<regionid>\ |
The response \<action\> includes actions such as a signup, sale, or subscription.
Cross-platform
A full list of OTT-specific column names. Use these to split the data in any combination.
Note: We have provided the typical use for c_deviceclass, c_placementgroup, and c_publisher. The others can vary from partner to partner and be used for whatever suits. Ensure the column names are exactly the same format as in the table below:
| URL Parameter | Corresponding Macro | Representation in URL |
| c_deviceclass | Ordinal | Type of device the impression was served on |
| c_placementgroup | Ordinal | Placement group of the impression |
| c_publisher | Ordinal | Publisher that delivered the ad |
| c_contentname | Ordinal | Misc |
| c_contentrating | Ordinal | Misc |
| c_deliveryplatform | Ordinal | Misc |
| c_externalname | Ordinal | Misc |
| c_externalplacementname | Ordinal | Misc |
Retrieve attributed spots
Performing a POST request returns detailed spot metadata and attribution metrics for a specific date. With the request, you should POST a list of column names for spot data you are interested in.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/<brandid>/spotsarray/<year>/<month>/<day> |
Request and response format
{
|
COLUMN NAMES should be an ordered list of the spot column values you wish to retrieve. The available column names can be obtained from the [Retrieve Spot Columns endpoint](#attr-spotColumns).
Any columns that do not exist in the database will return Null. Note that values from the datetime column are always returned, and if this column is not included in COLUMN NAMES, the datetime values are inserted at the start of each item of spot data.
{
|
Unattributed response data
Performing a GET request returns unattributed response timeseries data of a specified granularity between two dates inclusively.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/ |
Parameters
| Parameter | Description |
| UACTION | Action to retrieve, for example, allresponse, signup. |
| UMETRIC | Metric to retrieve, for example, session, response. |
| REFTYPE | Referrer type of timeseries to retrieve, for example, direct or search. |
| GRAN | Granularity to retrieve, for example, day, month. |
| MEDIUM | Medium to retrieve, for example, web, mobile. |
Possible parameter values can be found by performing an [inventory] (#inventory)request and the subsequent response data.
Response format
{
|
Spot metric timeseries
Performing a GET request retrieves spot metric timeseries data of a specified granularity between two dates inclusively.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/ |
Response format
{
|
Spot attribution timeseries
Performing a GET request returns the attribution timeseries for spots at the granularity requested between two dates inclusively.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/ |
Parameters
| Parameter | Description |
| SPLIT | Data split, for example, medium. |
| SPLITNAME | Data splitname to retrieve, for example, web. |
Response format
[VALUE0, VALUE1, ...] |
Response attribution timeseries
Performing a GET request returns the attribution timeseries for response at the granularity requested between two dates inclusively.
URL
https://<partnerdomain>.tvsquared.com/api/v2/attribution/<clientid>/ |
Parameters
| Parameter | Description |
| TSRTMTYPE | Breakdown type of timeseries to receive. |
For a full list, see Brand Inventory.
Response format
{
|
Using the Attribution API
While Attribution API calls can be used individually to retrieve data from the InnovidXP platform, you can also get utility from multiple calls used in sequence.
This section provides end-to-end examples describing using multiple Attribution API calls to retrieve targeted data for typical scenarios.
Note: Attribution API GET and POST calls in the following examples can be made using simple cURL command lines, as described in Making calls to the API or using the libraries of your preferred programming language.
Data warehousing
This example explores a typical early scenario that can be used to familiarize with the Attribution API - data warehousing of spot attribution data on a daily cadence.
To extract spot attribution data from InnovidXP requires a client and brand ID, and appropriate date parameters, to be passed for data retrieval into the data warehousing application.
-
Retrieve the top-level inventory from the Attribution API using the base Inventory GET request, for example, for an API partner domain of api-123:
https://api-123.tvsquared.com/api/v2/attribution
All inventory data available under your assigned permissions is returned, for example:{
"partners": [
{
"api": "api-123.tvsquared.com",
"portal": "example-partner.tvsquared.com",
"id": "example-partner",
"title": "Example Partner"
}, ...
],
"clients": [
{
"brands": [
{
"id": "default",
"title": "default"
}, ...
],
"id": "example-client",
"title": "Example Client"
}, ...
]
} - Inside the client's array, find the required client id value paired with the id key - in this case, example-client. This client ID is static data and can be stored for later use.
-
Retrieve the inventory from the Attribution API filtered down for this client by passing the client ID as a parameter to the Inventory request, for example:
https://api-123.tvsquared.com/api/v2/attribution/exampleclient
- Within the brand's array for the specified client data returned, find the required brand id value, which is paired with the id key - in this case, default. This brand ID is static data and can be stored for later use.
-
Retrieve the brand inventory from the Attribution API using the Brand inventory GET request, passing the client ID and brand ID as parameters, for example:
https://api-123.tvsquared.com/api/v2/attribution/exampleclient/default
All brand inventory data for the specified client/brand is returned, for example:
{
|
- Use the time range max and min values inside the spots document to determine the next date required for the data warehousing application in YYYY, MM, DD format.
-
Retrieve the spot attribution data for the data warehousing application using the Retrieve spot attribution GET request, passing the client and brand ID and the required date, for example:
https://api-123.tvsquared.com/api/v2/attribution/exampleclient/
default/spotsjson/2018/03/03
All attributed spot data for the specified date is returned for use in the application, for example:
{
"spots": [
{
"aggchannel": "DRAMA",
"country": "GB",
"region": "national",
"saleshouse": "SALES",
"datetime": "2018-03-03T20:00:57",
"um": {
"all response": {
"medium": {
"web": {
"m": {
"session": 0.0,
"revenue": 0.0,
}
},
"m": {
"session": 0.0,
"revenue": 0.0,
}
},
"m": {
"session": 0.0,
"revenue": 0.0,
}
},
},
"spotid": 12345
"length": 30,
"daypart": "breakfast",
"sm": {
"audience": {
"v": 0.0,
},
"cost": {
"v": 0.0,
}
},
"genre": "None",
"programme": "COFFEE PANIC",
"clocknumber": "CREATIVE1",
"channel": "DRAMA"
}, ...
]
}
Formatted spot data
This example demonstrates using dynamic data with the Attribution API - producing formatted, attributed spot data based on the available spot data columns, suitable for further analysis.
To extract formatted, attributed spot data from Innovid for further analysis requires a client and brand ID, and an appropriate date range to identify the available data columns for formatting.
- Identify an appropriate client and brand ID, such as those stored previously in Data warehousing, and a date range of interest from the Brand inventory response.
-
Retrieve the spot columns for your date range of interest from the Attribution API by passing the client ID, brand ID and date parameters to the Retrieve spot columns GET request, for example:
https://api-123.tvsquared.com/api/v2/attribution/exampleclient/
default/spotheaders/2017/08/02/2017/08/05
Spot columns can vary across date ranges depending on what data was supplied in the spots and responses during this time.
{
"headers": [
"datetime",
"daypart",
"chgenre",
"saleshouse",
"aggchannel",
"genre",
"spotid",
"um.all.response.m.session",
"um.sale.m.revenue",
"sm.cost.v",
...]
}
-
Retrieve the formatted, attributed spot date for use in further analysis using the Retrieve attributed spots POST request.
Send the required headers, as determined by your analysis needs, for retrieval in the POST data:{"headers": [
"datetime",
"daypart",
"channel",
"um.all.response.m.session",
"um.install.m.session",
"um.install.m.revenue"
]
}
Pass the client ID, brand ID, and date for the data you are interested in to the URL, for example:https://api-123.tvsquared.com/api/v2/attribution/exampleclient/
default/spotsarray/2017/08/03
All spot metadata and attribution metrics for the date specified are returned for use in further analysis, for example:{
"daterange": {
"max": "2017-08-03T23:31:00",
"min": "2017-08-03T00:18:00",
},
"ordinals": {
"channel": {
"date": false,
"values": [
"SCIENCE",
"HISTORY CHANNEL"
],
"title": "Channel"
},
"daypart": {
"date": true,
"values": [
"breakfast",
"coffee",
"day",
"earlypeak",
"latepeak",
"postpeak",
"bob",
"latenight"
],
"title": "Daypart"
}
},
"headers": {
"datetime": 0,
"daypart": 1,
"channel": 2,
"um.all response.m.session": 3,
"um.install.m.session": 4,
"um.install.m.revenue": 5
},
"spots": [
["2017-08-03T00:18:00", 6, 0, 13.423, 9.576, 0.0],
["2017-08-03T00:33:57", 0, 1, 15.572, 8.944, 0.0]
],
"smetrics": [
"audience",
"cost",
"spots"
],
"umetrics": [
"session",
"revenue"
],
"uactions": [
"all response",
"sale",
"install"
]
}
Direct vs. non-direct response view
This example demonstrates extracting timeseries data using the Attribution API to create a direct versus non-direct response view of the data for comparison.
To extract timeseries data from Innovid to create views for comparison requires a date range and several additional parameters. These determine the metrics (values) and splits (data groupings) in the returned data.
- Identify an appropriate client and brand ID, for example, from those stored previously in Data warehousing, and the following additional parameters from the Brand inventory response:
-
- Response action (for example, signup or all response)
- Response metric (for example, session)
- Time granularity (for example, day)
- Medium (for example, web)
- Date range of interest
-
To get the non-direct response timeseries data (sum of baseline response and non-attributed response), pass these parameters to the Response attribution timeseries GET
request, with a ts_rtm_type of nondr, for example:
https://api-123.tvsquared.com/api/v2/attribution/exampleclient/default/ts/rtm/all%20respons/session/nondr/day/
web/2018/6/1/2018/7/1
Non-direct response timeseries data for the dates, metrics, and splits supplied is returned. For example, the following results, with a value returned for each day in the date range specified:
{
"group": "rtm",
"action": "all response",
"metric": "session",
"type": "nondr",
"gran": "day",
"medium": "web",
"date1": "2018-06-01T00:00:00",
"date2": "2018-07-01T00:00:00",
"values": [
890.7431672131167,
634.0000000000001,
...
568.0000000000001,
401.00000000000006,
405.39431611011844
]
} -
To get the direct response timeseries data for comparison, pass the same parameters to the Response attribution timeseries GET request with a ts_rtm_type of dr, for example:
https://api-123.tvsquared.com/api/v2/attribution/exampleclient/default/ts/rtm/all%20respons/session/dr/day/
web/2018/6/1/2018/7/1
Direct response timeseries data for the dates, metrics, and splits supplied is returned for comparison with the non-direct response, for example:
{
"group": "rtm",
"action": "all response",
"metric": "session",
"type": "dr",
"gran": "day",
"medium": "web",
"date1": "2018-06-01T00:00:00",
"date2": "2018-07-01T00:00:00",
"values": [
35.14378426195513,
0.0,
...
315.60518845883036
]
}
Onboarding API
This section of the API allows retrieval of client onboarding. The base URL is appended with onboarding so that the base URL for the attribution endpoints becomes:
https://<partnerdomain>/api/v2/onboarding |
All URLs in this section start with this base URL.
Setup
The InnovidXP Onboarding API is a standard RESTful HTTP API based on GET, POST requests with JSON formatted responses.
The API exclusively uses the HTTPS protocol for encryption and data security - plain HTTP requests are blocked and will not be successful.
All API endpoints share the same base URL, accessed at the partner level:
https://<partnerdomain>.tvsquared.com/api/v2/ |
where <partnerdomain> is a unique identifier for the API in the format api-xx. Use your <partnerdomain> for the base URL for all API endpoints.
Inventory
Performing a GET request at the following endpoint returns basic inventory information regarding any partners, clients, or brands you can access.
URL
Users who have partner-level access permissions can call this endpoint:
https://<partnerdomain>/api/v2/onboarding |
Response format
{
|
The partner details include the title, ID, API domain, and partner domain. Client details include title, ID, and associated brand titles and IDs. This endpoint can get the appropriate client and brand IDs for subsequent API requests.
Example response format
{
|