Reporting Service API Guide

Category

URI

Token URI

https://api.integralplatform.com/uaa/oauth/token

Reporting URI

https://api.integralplatform.com/reportingservice/api/

Value

Description

{client ID}:{client Secret}

client ID and secret, separated by a colon

grant_type

set to password

username

the IAS Signal username

password

the password for the IAS Signal username

Value

description

access_token

token to use in the authorization header for requests to the reporting API

token_type

defines how the access_token was generated and how to make requests

expires_in

token expiration time in seconds

scope

reserved for future use

userId

ID associated with the IAS Signal

email

email associated with the IAS Signal username

jti

identifier used for IAS's internal diagnostics

Code

Description

200 OK

Successful query

401 Unauthorized

User does not have access to this resource.

400 Bad Request

Invalid arguments passed in parameters.

500 Internal Server Error

An error occurred during processing - please contact your IAS representative.

Required Path Parameter

Description

Type

team_id

Chooses which team's data to query. A team_id is a numeric value assigned to you. You can be granted permission to see any number of teams' data.

Integer

dimension

Possible values include: campaigns and publishers

String

dimension_params

Your IAS Open Web macro name, colon-delimited. For example:

/id1:id2:etc/

/name1:name2:etc/

Integer or string if your macro is a string type.

report_name

Chooses which report to generate.

String

Dimensions

Endpoint

Function

Campaigns

/campaigns/{campaign_ids}/dashboard/overview

Filter metrics by specific campaign

Publishers

/publishers/{publisher_ids}/dashboard/overview

Filter metrics by specific publishers

Campaigns and Publishers

/campaigns/{campaign_ids}/publishers/{publisher_ ids}/dashboard/overview

Filter metrics by specific campaigns and publishers

Param

Description

Variable Type and Example

Default Value

qualifiedAdsCriteria

Allows user to define/restrict Qualified Ads™ to within some or all of the Qualified Ads criteria categories: viewability, invalid traffic (fraud), geo, and brand safety.

Array. Colon delimited for groups:

qualifiedAdsCriteria=[viewability:fraud:geo:brandsafety]

customMetricsId

ID of the organization which defines the custom metrics. Note: Contact your Customer Service representative for details on which customMetricsId to use.

Integer:

?customMetricsId=2

period

You can specify a named keyword or dates to define the report period. Options include:

Named keywords: yesterday, today, latestDay, twoDaysAgo, last7days, last30days, thisWeek, lastWeek, lastMonth, thisMonth, thisQuarter, lastQuarter.

Date: you can use a range or a specific date.

String:

period=yesterday

period=twodaysago

Array:

period=[2011-02-01..2011-02-15] (elipses delimited for a date range)

period=[2011-02-01,2011-03-04] (comma delimited for specific dates)

last7days

groups

Granularity of grouping for result set. Options:

camp - the campaign

pub - the publisher (Primary seller); using pub returns the properties publisherId and publisherName. The reporting service then groups the output data by each publisher ID.

plac - the placement (ad unit). Groups results via an external placement ID, extPlacementId, defined when the campaign is configured. If an IAS generated ID is present (iasPlacementID) then the IAS generated ID is used. Since not all clients pass in an external placement ID, the extPlacementId might be missing.

date or daily

weekly

monthly

mediaApplicationAndFormat

mediaChannel

mediaFormat

site - returns metrics grouped at a domain/URL level

app - returns metrics grouped at the app level

Array. Colon delimited for groups:

groups=[camp:pub:daily] - the result set contains one record for each campaign, publisher and date combination.

groups=[camp] - the result set contains one record per campaign

[camp:pub]

rows

Limits the number of records returned per page in the result set to this number.

When "app" or "site" default = '5000' Else = '200000'

cutoff

Omits records from the result set that have totalImpressions < cutoff. Note that cutoff is applied after grouping the results.

Array:

when groups=[camp:pub:daily] the result set will contain records that have totalImpressions >= cutoff for each day, publisher and campaign combination.

When groups=[camp] the result set will contain records that have totalImpressions >= cutoff for each campaign.

sortIndex

Sorts results by the given column. Any column in the result set can be specified here.

String:

sortIndex=totalImpressions

sortOrder

Sorts records in the ascending or descending order of the sortIndex.

asc - for ascending order

desc - for descending order

String:

sortOrder=asc

sortOrder=desc

Objects and Keys

Description

overview

overview is a JSONArray with one JSONObject for each overview in the result set, with the following properties listed in the cells immediately below.

grossImps

The number of tracked ads which includes sophisticated and general invalid traffic.

totalEligibleForBrandSafety

The number of eligible ads for brand safety which includes sophisticated and general invalid traffic.

passedImps

The number of ads that passed brand safety checks.

passedPct

The percentage of passed ads out of total tracked ads.

totalNetEligibleImps

The total number of in-view ads with all invalid traffic removed that were not blocked.

totalNetMeasuredImps

The total number of in-view and out-of-view ads with general invalid traffic removed, where IAS was able to collect viewability data.

totalNetMeasuredPct

The percentage of measured ads out of total tracked ads with all invalid traffic removed.

totalNetInViewImps

The number of viewable ads including flagged ads.

fraudulentImps

The total invalid traffic, which includes sophisticated and general invalid traffic, but does not include incentivized browsing traffic.

fraudulentPct

The percentage of invalid traffic out of total tracked ads, which includes sophisticated and general invalid traffic, but does not include reduced-value inventory (for example incentivized browsing traffic).

eligibleForQualifiedAds

When Qualified Ads criteria excludes viewability: Total Tracked Ads The total number of ads processed by IAS. When Qualified Ads criteria includes viewability: The number of ads that were measured for viewability or failed another selected criteria (such as brand safety, invalid traffic, or geo).

qualifiedAds

The number of ads that passed all selected Qualified Ads criteria. Note: For Proprietary Platforms, ads can fail only for metrics covered by each integration. Some Proprietary Platforms may not cover geo and/or brand safety.

qualifiedPct

The percentage of ads that passed all selected Qualified Ads criteria (out of Eligible for Qualified Ads). Note: For Proprietary Platforms, ads can fail only for metrics covered by each integration. Some Proprietary Platforms may not cover geo and/or brand safety.

mediaChannel

The viewability by device type which is displayed only when groups includes 'mediaChannel'. Possible values are: - 1 (Desktop) - 2 (Mobile) - 3 (Tablet) - 0 (Unknown, when the media channel is not known) Any value other than 1, 2, or 3 is an unknown media channel (0).

mediaFormat

The viewability by format which is displayed only when groups includes 'mediaFormat'. Possible Values: - 1 (Display) - 2 (Video)

mediaApplicationAndFormat

The viewability by environment and format which is displayed only when groups contains 'mediaApplicationAndFormat'. The value is a concatenation of the media application and format, where AF: A = 0 (Unknown), 1 (Browser), 2 (In-app) F = 0 (Unknown), 1 (Display), 2 (Video) Possible values: 11 (Browser Display) 12 (Browser Video) 21 (In-app Display) 22 (In-app Video) 01 (Unknown Display when the media app is unknown) 02 (Unknown Video when the media app is unknown) 10 (Browser Unknown when the format is unknown) 20 (In-app Unknown when the format is unknown) 00 (Unknown Unknown when both the app and format is unknown)

customMetricsId[id]totalNetInViewImps

The number of display in view ads as defined by the organization identified by the input parameter customMetricsId.

customMetricsId[id]totalNetInViewPct

The percentage of display in view ads as defined by the organization identified by the input parameter customMetricsId.

site

When site is set in the groups query parameter, site is the domain/URL which the metrics apply.

app

When app is set in the groups query parameter, app is the name of the app which the metrics apply.

renderedImps

IAS confirmed number of rendered impressions which excludes general invalid traffic.

renderedPct

Percent of rendered impressions out of all all tracked ads.

campaignId

The ID for the campaign displayed only if groups includes 'camp'.

campaignName

The name for the campaign displayed only if groups includes 'camp'.

publisherId

Displays the publisher ID; this field is only outputed when 'pub' is added as a groups input parameter value.

publisherName

The name of the publisher; this field is only outputed when 'pub' is added as a groups input parameter value.

placementId

The placement ID which is displayed only when groups includes 'plac'.

placementName

The placement name ID which is displayed only when groups includes 'plac'.

recordCount

The number of results.

executionTimeMS

The time, in milliseconds, the query took.

Dimensions

Endpoint

Function

Campaigns

/campaigns/{campaign_ids}/dashboard/brandsafety

Filter metrics by specific campaign

Publishers

/publishers/{publisher_ids}/dashboard/brandsafety

Filter metrics by specific publishers

Campaigns and Publishers

/campaigns/{campaign_ids}/publishers/{publisher_ids}/dashboard/brandsafety

Filter metrics by specific campaigns and publishers

Param

Description

Variable Type and Example

Default Value

period

You can specify a named keyword or dates to define the report period. Options include:

Named keywords: yesterday, today, latestDay, twoDaysAgo, last7days, last30days, thisWeek, lastWeek, lastMonth, thisMonth, thisQuarter, lastQuarter.

Date: you can use a range or a specific date.

String:

period=yesterday

period=twodaysago

Array:

period=[2011-02-01..2011-02-15] (elipses delimited for a date range)

period=[2011-02-01,2011-03-04] (comma delimited for specific dates)

last7days

groups

Granularity of grouping for result set. Options:

camp - the campaign

pub - the publisher (Primary seller); using pub returns the properties publisherId and publisherName. The reporting service then groups the output data by each publisher ID.

plac - the placement (ad unit). Groups results via an external placement ID, extPlacementId, defined when the campaign is configured. If an IAS generated ID is present (iasPlacementID) then the IAS generated ID is used. Since not all clients pass in an external placement ID, the extPlacementId might be missing.

date or daily

weekly

monthly

mediaApplicationAndFormat

mediaChannel

mediaFormat

site - returns metrics grouped at a domain/URL level

app - returns metrics grouped at the app level

Array. Colon delimited for groups:

groups=[camp:pub:daily] - the result set contains one record for each campaign, publisher and date combination.

groups=[camp] - the result set contains one record per campaign

cutoff

Omits records from the result set that have totalImpressions < cutoff. Note that cutoff is applied after grouping the results.

Integer:

when groups=[camp:pub:daily] the result set will contain records that have totalImpressions >= cutoff for each day, publisher and campaign combination.

When groups=[camp] the result set will contain records that have totalImpressions >= cutoff for each campaign.

sortIndex

Sorts results by the given column. Any column in the result set can be specified here.

String:

sortIndex=totalImpressions

totalEligibleForBrandSafetyImps

sortOrder

Sorts records in the ascending or descending order of the sortIndex.

asc - for ascending order

desc - for descending order

String:

sortOrder=asc

sortOrder=desc

desc

rows

Limits the number of records returned per page in the result set to this number.

When "app" or "site" default = '5000' Else = '200000'

page

Shows a specific page of records. rows and pages parameters can be used in combination to retrieve result sets in smaller chunks. In order to receive all records, increase the page number until you don't receive any additional results for that page.

Integer If a report is supposed to return 12,500 records, then rows=5000&page=1, returns the first 5,000 rows rows=5000&page=2, returns the next 5,000 rows rows=5000&page=3, returns the last 2,500 rows.

1

includeChangeRate

Allows the response to include the percentage change rate for a specified period compared to the value of the metric from the previous period. includeChangeRate is not supported with 'daily' or 'date' group. Similarly, it does not work for individual dates if specified in 'period'. includeChangeRate works for a named period or a date range.

Boolean (true/false): includeChangeRate=true

false

Objects and Keys

Description

brandsafety

brandsafety is a JSONArray with one JSONObject for each bandsafety contained in the result set, with the following properties listed in the cells immediately below.

totalEligibleForBrandSafetyImps

The number of eligible ads for brand safety which includes sophisticated and general invalid traffic.

passedImps

The number of ads that passed brand safety checks.

passedPct

The percentage of passed ads with regard to the total eligible ads.

failedImps

The number of ads that failed brand safety checks.

failedPct

The percentage of failed ads with regard to the total number of eligible ads.

blockedImps

The number of ads that were blocked by IAS.

blockedPct

The percentage of blocked ads with regard to the failed ads.

failedByContentImps

The number of ads that were failed for content reasons.

failedByContentPct

The percentage of failed by content ads with regard to the total eligible ads.

failedByKeywordImps

The number of ads that were failed because of keywords.

failedByKeywordPct

The percentage of failed because of keywords ads with regard to the total eligible ads.

failedByUrlImps

The number of ads that were failed because of a URL being in an exclusion list.

failedByUrlPct

The percentage of failed by URL ads because of a URL being in an exclusion list with regard to the total eligible ads.

failedByGeoImps

The number of ads that failed because of geography checks.

failedByGeoPct

The percentage of 'failed because of geography' ads with regard to the total eligible ads.

failedByFraudImps

The number of ads that failed for invalid traffic.

failedByFraudPct

The percentage of 'failed because of invalid traffic' ads with regard to total eligible ads.

failedByVisibilityImps

The number of ads that failed for visibility.

failedByVisibilityPct

The percentage of failed by visibility ads with regard to the total eligible ads.

failedByLanguageImps

The number of ads that failed for language reasons.

failedByLanguagePct

The percentage of 'failed because of language' ads with regard to the total eligible ads.

site

When site is set in the groups query parameter, site is the domain/URL which the metrics apply.

app

When app is set in the groups query parameter, app is the name of the app which the metrics apply.

unblockableImps

Number of video ads which were meant to be blocked due to brand safety, but couldn't be blocked.

blockingStatus

Returns a string to indicate how a placement, campaign, or media partner is set up. The blockingStatus is useful with identifying potential issues with the campaign performance or tag setup. Possible values are:

Monitoring

Blocking

Mixed

campaignId

The ID for the campaign displayed only if groups includes 'camp'.

campaignName

The name for the campaign displayed only if groups includes 'camp'.

publisherId

Displays the publisher ID; this field is only outputed when 'pub' is added as a groups input parameter value.

publisherName

The name of the publisher; this field is only outputed when 'pub' is added as a groups input parameter value.

placementId

The placement ID which is displayed only when groups includes 'plac'.

placementName

The placement name ID which is displayed only when groups includes 'plac'.

mediaChannel

The viewability by device type and is displayed only when groups includes 'mediaChannel'. Possible values are: - 1 (Desktop) - 2 (Mobile) - 3 (Tablet) - 0 (Unknown, when the media channel is not known) Any value other than 1, 2, or 3 is an unknown media channel (0).

mediaFormat

The viewability by format which is displayed only when groups includes mediaFormat. Possible Values: - 1 (Display) - 2 (Video)

mediaApplicationAndFormat

The viewability by environment and format which is displayed only when groups contains 'mediaApplicationAndFormat'. The value is a concatenation of the media application and format, where AF: A = 0 (Unknown), 1 (Browser), 2 (In-app) F = 0 (Unknown), 1 (Display), 2 (Video) Possible values: 11 (Browser Display) 12 (Browser Video) 21 (In-app Display) 22 (In-app Video) 01 (Unknown Display when the media app is unknown) 02 (Unknown Video when the media app is unknown) 10 (Browser Unknown when the format is unknown) 20 (In-app Unknown when the format is unknown) 00 (Unknown Unknown when both the app and format is unknown)

hitDate

The date in which IAS pulled the data and is displayed only when groups includes 'date' or 'daily'.

recordCount

The number of results.

executionTimeMS

The time, in milliseconds, the query took.

path

The path of the query.

query

The query parameters used to generate the report.

Dimensions

Endpoint

Function

Campaigns

/campaigns/{campaign_ids}/dashboard/fraud

Filter metrics by specific campaign

Publishers

/publishers/{publisher_ids}/dashboard/fraud

Filter metrics by specific publishers

Campaigns and Publishers

/campaigns/{campaign_ids}/publishers/{publisher_ids}/dashboard/fraud

Filter metrics by specific campaigns and publishers

Param

Description

Variable Type and Example

Default Value

period

You can specify a named keyword or dates to define the report period. Options include:

Named keywords: yesterday, today, latestDay, twoDaysAgo, last7days, last30days, thisWeek, lastWeek, lastMonth, thisMonth, thisQuarter, lastQuarter.

Date: you can use a range or a specific date.

String:

period=yesterday

period=twodaysago

Array:

period=[2011-02-01..2011-02-15] (elipses delimited for a date range)

period=[2011-02-01,2011-03-04] (comma delimited for specific dates)

last7days

groups

Granularity of grouping for result set. Options:

camp - the campaign

pub - the publisher (Primary seller); using pub returns the properties publisherId and publisherName. The reporting service then groups the output data by each publisher ID.

plac - the placement (ad unit). Groups results via an external placement ID, extPlacementId, defined when the campaign is configured. If an IAS generated ID is present (iasPlacementID) then the IAS generated ID is used. Since not all clients pass in an external placement ID, the extPlacementId might be missing.

date or daily

weekly

monthly

mediaApplicationAndFormat

mediaChannel

mediaFormat

site - returns metrics grouped at a domain/URL level

app - returns metrics grouped at the app level

Array. Colon delimited for groups:

groups=[camp:pub:daily] - the result set contains one record for each campaign, publisher and date combination.

groups=[camp] - the result set contains one record per campaign

cutoff

Omits records from the result set that have totalImpressions < cutoff. Note that cutoff is applied after grouping the results.

Integer:

when groups=[camp:pub:daily] the result set will contain records that have totalImpressions >= cutoff for each day, publisher and campaign combination.

When groups=[camp] the result set will contain records that have totalImpressions >= cutoff for each campaign.

sortIndex

Sorts results by the given column. Any column in the result set can be specified here.

String:

sortIndex=totalImpressions

fraudulentImps

sortOrder

Sorts records in the ascending or descending order of the sortIndex.

asc - for ascending order

desc - for descending order

String:

sortOrder=asc

sortOrder=desc

desc

rows

Limits the number of records returned per page in the result set to this number.

When "app" or "site" default = '5000' Else = '200000'

page

Shows a specific page of records. rows and pages parameters can be used in combination to retrieve result sets in smaller chunks. In order to receive all records, increase the page number until you don't receive any additional results for that page.

Integer If a report is supposed to return 12,500 records, then rows=5000&page=1, returns the first 5,000 rows rows=5000&page=2, returns the next 5,000 rows rows=5000&page=3, returns the last 2,500 rows.

1

includeChangeRate

Allows the response to include the percentage change rate for a specified period compared to the value of the metric from the previous period. includeChangeRate is not supported with 'daily' or 'date' group. Similarly, it does not work for individual dates if specified in 'period'. includeChangeRate works for a named period or a date range.

Boolean (true/false): includeChangeRate=true

false

Objects and Keys

Description

fraud

fraud is a JSONArray with one JSONObject for each fraud contained in the result set, with the following properties listed in the cells immediately below.

totalImps

The gross total number of ads which includes general invalid traffic.

dsDomainSpoofingTotal Impressions

The number of impressions that are low quality inventory disguised as high-quality legitimate-sites, or send incorrect referrer information to hide their identity.

dsDomainSpoofing TotalPct

The percentage of impressions that are low quality inventory disguised as high-quality legitimate-sites, or send incorrect referrer information to hide their identity.

fraudulentImps

The total invalid traffic which includes sophisticated and general invalid traffic but does not include incentivized browsing traffic.

fraudulentPct

Percentage of invalid traffic which includes sophisticated and general invalid traffic but does not include reduced value inventory (for example incentivized browsing traffic).

nonFraudulentImps

The total valid traffic.

nonFraudulentPct

The percentage of invalid traffic.

fraudulentUnblockedImps

The total unblocked invalid traffic.

fraudulentUnblockedPct

The percentage of unblocked invalid traffic.

fraudulentBlockedImps

The total blocked invalid traffic.

fraudulentBlockedPct

The percentage of blocked invalid traffic.

unblockedImps

The total number of ads that were not blocked. This includes general and sophisticated invalid traffic.

unblockedImpsPct

The percentage of ads that were not blocked. This includes general and sophisticated invalid traffic.

blockedImps

The total number of ads that were blocked.

blockedPct

The percentage of ads that were blocked.

nonHumanTrafficImps

The total number of non-human traffic ads.

nonHumanTrafficPct

The percentage of non-human traffic ads.

nhtSittingDuckBotImps

The total number of non human traffic (NHT) which resides on end-user devices (sitting duck). Detection avoidance pursued through aggressive use of traffic-filtering services falsely claiming to defeat invalid traffic prevention services.

nhtSittingDuckBotPct

The percentage of sitting duck bot ads.

nhtStandardBotImps

The total number of NHT standard bot ads which includes common strains of Internet Explorer-based malware, primarily on residential computers. The bot's focus is on scale rather than compiling cookies or evading detection.

nhtStandardBotPct

The percentage of standard bot ads.

nhtVolunteerBotImps

The total number of NHT volunteer bot ads which resides in cloud services, allowing 24/7 operations and eliminating load on the machine. Volunteer bots implement basic detection-evasion measures such as user agent spoofing.

nhtVolunteerBotPct

The percentage of volunteer bot ads.

nhtProfileBotImps

The total number of NHT profile bot ads. Profile bots focus on developing valuable user profiles by spending time on premium sites and evade detection through user agent spoofing and use of public proxy servers.

nhtProfileBotPct

The percentage of profile bot ads.

nhtMaskedBotImps

The total number of NHT masked bot ads. Masked bots go to great lengths to evade detection and obscure activity. Numerous aspects of the browser environment are manipulated.

nhtMaskedBotPct

The percentage of masked bot ads.

nhtNomadicBotImps

The total number of NHT nomadic bot ads. Nomadic bots use proxy servers or VPNs to hide their network location and are difficult to track with typical user identification techniques.

nhtNomadicBotPct

The percentage of nomadic bot ads.

nhtOtherBotImps

The number of other bot ads which includes other invalid traffic, including uncommon types of non-human traffic.

nhtOtherBotPct

The percentage of other bot ads.

hiddenAdsImps

The number of ads for hidden ads.

hiddenAdsPct

The percentage of hidden ads.

locationSpoofingImps

The number of ads from location spoofing.

locationSpoofingPct

The percentage of location spoofing ads.

lsProxyServerImps

The number of location spoofing proxy server ads.

lsProxyServerPct

The percentage of location spoofing proxy server ads.

incentivizedBrowsingImps

The number of incentivized browsing ads. This is traffic which is not strictly speaking invalid but which is generated in a way counter to the advertiser's interests and which the advertiser likely would not have bought if there had been full transparency.

incentivizedBrowsingPct

The percentage of incentivized browsing ads.

givtImps

The number of general invalid traffic (GIVT) ads identified through basic means which all ad tech companies should be capable of implementing, including matching against a standard user agent list.

givtPct

The percentage of GIVT ads.

sivtImps

The number of sophisticated invalid traffic (SIVT); this is traffic which falsifies user, page, or delivery characteristics in such a way as to require specially developed techniques to detect it.

rviImps

The number of reduced value inventory, RVI, (for example incentivized browsing traffic) ads. This is traffic which is not strictly speaking invalid but which is generated in a way counter to the advertiser's interests and which the advertiser likely would not have bought if there had been full transparency.

rviPct

The percentage of reduced value inventory ads.

totalImpsChangeRate

The percentage change rate in total ads compared with the previous period.

fraudulentImpsChangeRate

The percentage change rate in invalid traffic compared with the previous period.

fraudulentPctChangeRate

The percentage change rate in invalid traffic percentage compared with the previous period.

nonFraudulentImpsChangeRate

The percentage change rate in valid traffic compared with the previous period.

fraudulentUnblockedImpsChangeRate

The percentage change rate in unblocked invalid traffic compared with the previous period.

fraudulentBlockedImpsChangeRate

The percentage change rate in blocked invalid traffic compared with the previous period.

unblockedImpsChangeRate

The percentage change rate in unblocked ads compared with the previous period.

givtImpsChangeRate

The percentage change rate in general invalid traffic ads compared with the previous period.

sivtPctChangeRate

The percentage change rate in sophisticated invalid traffic ads percentage compared with the previous period.

rviPctChangeRate

The percentage change rate in RVI percentage compared with the previous period.

nonHumanTrafficImpsChangeRate

The percentage change rate in non-human traffic ads compared with the previous period.

hiddenAdsImpsChangeRate

The percentage change rate in hidden ads compared with the previous period.

locationSpoofingImpsChangeRate

The percentage change rate in location spoofing ads compared with the previous period.

lsProxyServerImpsChangeRate

The percentage change rate in proxy server ads compared with the previous period.

incentivizedBrowsingImpsChangeRate

The percentage change rate in incentivized browsing ads compared with the previous period.

site

When site is set in the groups query parameter, site is the domain/URL which the metrics apply.

app

When app is set in the groups query parameter, app is the name of the app which the metrics apply.

campaignId

The ID for the campaign displayed only if groups includes 'camp'.

campaignName

The name for the campaign displayed only if groups includes 'camp'.

publisherId

Displays the publisher ID; this field is only outputed when 'pub' is added as a groups input parameter value.

publisherName

The name of the publisher; this field is only outputed when 'pub' is added as a groups input parameter value.

placementId

The placement ID which is displayed only when groups includes 'plac'.

placementName

The placement name ID which is displayed only when groups includes 'plac'.

mediaChannel

The viewability by device type and is displayed only when groups includes 'mediaChannel'. Possible values are: - 1 (Desktop) - 2 (Mobile) - 3 (Tablet) - 0 (Unknown, when the media channel is not known) Any value other than 1, 2, or 3 is an unknown media channel (0).

mediaFormat

The viewability by format which is displayed only when groups includes mediaFormat. Possible Values: - 1 (Display) - 2 (Video)

mediaApplicationAndFormat

The viewability by environment and format which is displayed only when groups contains 'mediaApplicationAndFormat'. The value is a concatenation of the media application and format, where AF: A = 0 (Unknown), 1 (Browser), 2 (In-app) F = 0 (Unknown), 1 (Display), 2 (Video) Possible values: 11 (Browser Display) 12 (Browser Video) 21 (In-app Display) 22 (In-app Video) 01 (Unknown Display when the media app is unknown) 02 (Unknown Video when the media app is unknown) 10 (Browser Unknown when the format is unknown) 20 (In-app Unknown when the format is unknown) 00 (Unknown Unknown when both the app and format is unknown)

hitDate

The date in which IAS pulled the data and is displayed only when groups includes 'date' or 'daily'.

recordCount

The number of results.

executionTimeMS

The time, in milliseconds, the query took.

path

The path of the query.

query

The query parameters used to generate the report.

Dimensions

Endpoint

Function

Campaigns

/campaigns/{campaign_ids}/dashboard/viewability

Filter metrics by specific campaign

Publishers

/publishers/{publisher_ids}/dashboard/viewability

Filter metrics by specific publishers

Campaigns and Publishers

/campaigns/{campaign_ids}/publishers/{publisher_ids}/dashboard/viewability

Filter metrics by specific campaigns and publishers

Param

Description

Variable Type and Example

Default Value

customMetricsId

ID of the custom viewability methodology. Note: Contact your Customer Service representative for details on which customMetricsId to use.

Integer

?customMetricsId=2

period

You can specify a named keyword or dates to define the report period. Options include:

Named keywords: yesterday, today, latestDay, twoDaysAgo, last7days, last30days, thisWeek, lastWeek, lastMonth, thisMonth, thisQuarter, lastQuarter.

Date: you can use a range or a specific date.

String:

period=yesterday

period=twodaysago

Array:

period=[2011-02-01..2011-02-15] (elipses delimited for a date range)

period=[2011-02-01,2011-03-04] (comma delimited for specific dates)

last7days

groups

Granularity of grouping for result set. Options:

camp - the campaign

pub - the publisher (Primary seller); using pub returns the properties publisherId and publisherName. The reporting service then groups the output data by each publisher ID.

plac - the placement (ad unit). Groups results via an external placement ID, extPlacementId, defined when the campaign is configured. If an IAS generated ID is present (iasPlacementID) then the IAS generated ID is used. Since not all clients pass in an external placement ID, the extPlacementId might be missing.

date or daily

weekly

monthly

mediaApplicationAndFormat

mediaChannel

mediaFormat

site - returns metrics grouped at a domain/URL level

app - returns metrics grouped at the app level

Array. Colon delimited for groups:

groups=[camp:pub:daily] - the result set contains one record for each campaign, publisher and date combination.

groups=[camp] - the result set contains one record per campaign

cutoff

Omits records from the result set that have totalImpressions < cutoff. Note that cutoff is applied after grouping the results.

Integer:

when groups=[camp:pub:daily] the result set will contain records that have totalImpressions >= cutoff for each day, publisher and campaign combination.

When groups=[camp] the result set will contain records that have totalImpressions >= cutoff for each campaign.

sortIndex

Sorts results by the given column. Any column in the result set can be specified here.

String:

sortIndex=totalImpressions

totalNetEligibleImps

sortOrder

Sorts records in the ascending or descending order of the sortIndex.

asc - for ascending order

desc - for descending order

String:

sortOrder=asc

sortOrder=desc

desc

rows

Limits the number of records returned per page in the result set to this number.

When "app" or "site" default = '5000' Else = '200000'

page

Shows a specific page of records. rows and pages parameters can be used in combination to retrieve result sets in smaller chunks. In order to receive all records, increase the page number until you don't receive any additional results for that page.

Integer If a report is supposed to return 12,500 records, then rows=5000&page=1, returns the first 5,000 rows rows=5000&page=2, returns the next 5,000 rows rows=5000&page=3, returns the last 2,500 rows.

1

includeChangeRate

Allows the response to include the percentage change rate for a specified period compared to the value of the metric from the previous period. includeChangeRate is not supported with 'daily' or 'date' group. Similarly, it does not work for individual dates if specified in 'period'. includeChangeRate works for a named period or a date range.

Boolean (true/false): includeChangeRate=true

false

Objects and Keys

Description

viewability

viewability is a JSONArray with one JSONObject for each viewability contained in the result set, with the following properties listed in the cells immediately below.

totalNetMeasuredImps

The total number of in view and out of view ads with general invalid traffic removed, where IAS was able to collect viewability data.

totalNetInViewImps

The number of viewable ads including flagged ads.

totalNetInViewPct

Percentage of in-view ads over measured ads.

totalNetOutOfViewImps

The number of out of viewable ads including flagged ads not in view.

totalNetOutOfViewPct

Percentage of out of view ads over measured ads.

totalNetEligibleImps

The total number of in view ads with all invalid traffic removed that were not blocked.

totalNetMeasuredPct

Measured ads as a percentage of total eligible ads with all invalid traffic removed.

totalNetEligibleImpsChangeRate

Percentage change rate in total ( valid traffic) ads compared with the previous period.

totalNetMeasuredImpsChangeRate

Percentage change rate in measured (valid traffic) ads compared with the previous period.

totalNetMeasuredPctChangeRate

Percentage change rate in measured (valid traffic) ads percentage compared with the previous period.

totalNetInViewImpsChangeRate

Percentage change rate in in-view ads compared with the previous period.

totalNetInViewPctChangeRate

Percentage change rate in in-view ads percentage compared with the previous period.

totalNetOutOfViewImpsChangeRate

Percentage change rate in out-of-view ads compared with the previous period.

totalNetOutOfViewPctChangeRate

Percentage change rate in out-of-view ads percentage compared with the previous period.

customMetricsId[id]totalNetInViewImps

The number of display in view ads as defined by the organization identified by the input parameter customMetricsId.

customMetricsId[id]totalNetInViewPct

The percentage of display in view ads as defined by the organization identified by the input parameter customMetricsId.

site

When site is set in the groups query parameter, site is the domain/URL which the metrics apply.

app

When app is set in the groups query parameter, app is the name of the app which the metrics apply.

campaignId

The ID for the campaign displayed only if groups includes 'camp'.

campaignName

The name for the campaign displayed only if groups includes 'camp'.

publisherId

Displays the publisher ID; this field is only outputed when 'pub' is added as a groups input parameter value.

publisherName

The name of the publisher; this field is only outputed when 'pub' is added as a groups input parameter value.

placementId

The placement ID which is displayed only when groups includes 'plac'.

placementName

The placement name ID which is displayed only when groups includes 'plac'.

mediaChannel

The viewability by device type which is displayed only when groups includes 'mediaChannel'. Possible values are: - 1 (Desktop) - 2 (Mobile) - 3 (Tablet) - 0 (Unknown, when the media channel is not known) Any value other than 1, 2, or 3 is an unknown media channel (0).

mediaFormat

The viewability by format which is displayed only when groups includes mediaFormat. Possible Values: - 1 (Display) - 2 (Video)

mediaApplicationAndFormat

The viewability by environment and format which is displayed only when groups contains 'mediaApplicationAndFormat'. The value is a concatenation of the media application and format, where AF: A = 0 (Unknown), 1 (Browser), 2 (In-app) F = 0 (Unknown), 1 (Display), 2 (Video) Possible values: 11 (Browser Display) 12 (Browser Video) 21 (In-app Display) 22 (In-app Video) 01 (Unknown Display when the media app is unknown) 02 (Unknown Video when the media app is unknown) 10 (Browser Unknown when the format is unknown) 20 (In-app Unknown when the format is unknown) 00 (Unknown Unknown when both the app and format is unknown)

hitDate

The date in which IAS pulled the data and is displayed only when groups includes 'date' or 'daily'.

recordCount

The number of results.

executionTimeMS

The time, in milliseconds, the query took.

path

The path of the query.

query

The query parameters used to generate the report.

Dimensions

Endpoint

Function

Campaigns

/campaigns/{campaign_ids}/dashboard/viewabilityrendered

Filter metrics by specific campaign

Publishers

/publishers/{publisher_ids}/dashboard/viewabilityrendered

Filter metrics by specific publishers

Campaigns and Publishers

/campaigns/{campaign_ids}/publishers/{publisher_ids}/dashboard/viewabilityrendered

Filter metrics by specific campaigns and publishers

Param

Description

Variable Type and Example

Default Value

period

You can specify a named keyword or dates to define the report period. Options include:

Named keywords: yesterday, today, latestDay, twoDaysAgo, last7days, last30days, thisWeek, lastWeek, lastMonth, thisMonth, thisQuarter, lastQuarter.

Date: you can use a range or a specific date.

String:

period=yesterday

period=twodaysago

Array:

period=[2011-02-01..2011-02-15] (elipses delimited for a date range)

period=[2011-02-01,2011-03-04] (comma delimited for specific dates)

last7days

groups

Granularity of grouping for result set. Options:

camp - the campaign

pub - the publisher (Primary seller); using pub returns the properties publisherId and publisherName. The reporting service then groups the output data by each publisher ID.

plac - the placement (ad unit). Groups results via an external placement ID, extPlacementId, defined when the campaign is configured. If an IAS generated ID is present (iasPlacementID) then the IAS generated ID is used. Since not all clients pass in an external placement ID, the extPlacementId might be missing.

date or daily

weekly

monthly

mediaApplicationAndFormat

mediaChannel

mediaFormat

site - returns metrics grouped at a domain/URL level

app - returns metrics grouped at the app level

Array. Colon delimited for groups:

groups=[camp:pub:daily] - the result set contains one record for each campaign, publisher and date combination.

groups=[camp] - the result set contains one record per campaign

cutoff

Omits records from the result set that have totalImpressions < cutoff. Note that cutoff is applied after grouping the results.

Integer:

when groups=[camp:pub:daily] the result set will contain records that have totalImpressions >= cutoff for each day, publisher and campaign combination.

When groups=[camp] the result set will contain records that have totalImpressions >= cutoff for each campaign.

sortIndex

Sorts results by the given column. Any column in the result set can be specified here.

String:

sortIndex=totalImpressions

totalNetEligibleImps

sortOrder

Sorts records in the ascending or descending order of the sortIndex.

asc - for ascending order

desc - for descending order

String:

sortOrder=asc

sortOrder=desc

desc

rows

Limits the number of records returned per page in the result set to this number.

When "app" or "site" default = '5000' Else = '200000'

page

Shows a specific page of records. rows and pages parameters can be used in combination to retrieve result sets in smaller chunks. In order to receive all records, increase the page number until you don't receive any additional results for that page.

Integer If a report is supposed to return 12,500 records, then rows=5000&page=1, returns the first 5,000 rows rows=5000&page=2, returns the next 5,000 rows rows=5000&page=3, returns the last 2,500 rows.

1

includeChangeRate

Allows the response to include the percentage change rate for a specified period compared to the value of the metric from the previous period. includeChangeRate is not supported with 'daily' or 'date' group. Similarly, it does not work for individual dates if specified in 'period'. includeChangeRate works for a named period or a date range.

Boolean (true/false): includeChangeRate=true

false

Objects and Keys

Description

viewabilityRendered

viewabilityRendered is a JSONArray with one JSONObject for each viewability contained in the result set, with the following properties listed in the cells immediately below.

totalNetRenderedImps

Rendered impressions with SIVT and GIVT removed.

totalNetEligibleRenderedImps

Rendered impressions eligible for viewability with SIVT and GIVT removed. NOTE: This metric is currently same as totalNetRenderedImps, but in the future it will account for unmeasurable impressions (Impressions that ignore non-JavaScript and non-measureable video environments).

totalNetMeasuredRenderedImps

Measured, rendered impressions with SIVT and GIVT are removed.

totalNetMeasuredRenderedPct

Percentage of measured rendered impressions with SIVT and GIVT removed.

totalNetUnmeasuredRenderedImps

Unmeasured rendered impressions with SIVT and GIVT removed.

totalNetUnmeasuredRenderedPct

Percentage of unmeasured rendered impressions with SIVT and GIVT removed.

totalNetInViewRenderedImps

In view rendered impressions with SIVT and GIVT removed.

totalNetInViewRenderedPct

Percentage of in view rendered impressions with SIVT and GIVT removed.

totalNetOutOfViewRenderedImps

Out of view rendered impressions with SIVT and GIVT removed.

totalNetOutOfVIewRenderedPct

Percentage of out of view rendered impressions with SIVT and GIVT removed.

totalNetImpressionDistributionInViewRenderedPct

Percentage of in view rendered impressions with GIVT and SIVT removed, out of all eligible impressions whether they were measured or not.

totalNetImpressionDistributionOutOfViewRenderedPct

Percentage of out of view rendered impressions where GIVT and SIVT are removed, out of all eligible impressions whether they were measured or not.

netRenderedImps

Rendered impressions with GIVT removed.

netMeasuredRenderedImps

Measured, rendered impressions with GIVT are removed.

netMeasuredRenderedPct

Percentage of measured rendered impressions with GIVT removed.

netUnmeasuredRenderedImps

Unmeasured rendered impressions with GIVT removed.

netUnmeasuredRenderedPct

Percentage of unmeasured rendered impressions with GIVT removed.

netInViewRenderedImps

In view rendered impressions with GIVT removed.

netInViewRenderedPct

Percentage of in view rendered impressions with GIVT removed.

netOutOfViewRenderedImps

Out of view rendered impressions with GIVT removed.

netOutOfViewRenderedPct

Percentage of out of view rendered impressions with GIVT removed.

netImpressionDistributionInViewRenderedPct

Percentage of in view rendered impressions with GIVT removed, out of all eligible impressions whether they were measured or not.

netImpressionDistributionOutofViewRenderedPct

Percentage of out of view rendered impressions where GIVT are removed, out of all eligible impressions whether they were measured or not.

site

When site is set in the groups query parameter, site is the domain/URL which the metrics apply.

app

When app is set in the groups query parameter, app is the name of the app which the metrics apply.

campaignId

The ID for the campaign displayed only if groups includes 'camp'.

campaignName

The name for the campaign displayed only if groups includes 'camp'.

publisherId

Displays the publisher ID; this field is only outputed when 'pub' is added as a groups input parameter value.

publisherName

The name of the publisher; this field is only outputed when 'pub' is added as a groups input parameter value.

placementId

The placement ID which is displayed only when groups includes 'plac'.

placementName

The placement name ID which is displayed only when groups includes 'plac'.

mediaChannel

The viewability by device type which is displayed only when groups includes 'mediaChannel'. Possible values are: - 1 (Desktop) - 2 (Mobile) - 3 (Tablet) - 0 (Unknown, when the media channel is not known) Any value other than 1, 2, or 3 is an unknown media channel (0).

mediaFormat

The viewability by format which is displayed only when groups includes mediaFormat. Possible Values: - 1 (Display) - 2 (Video)

mediaApplicationAndFormat

The viewability by environment and format which is displayed only when groups contains 'mediaApplicationAndFormat'. The value is a concatenation of the media application and format, where AF: A = 0 (Unknown), 1 (Browser), 2 (In-app) F = 0 (Unknown), 1 (Display), 2 (Video) Possible values: 11 (Browser Display) 12 (Browser Video) 21 (In-app Display) 22 (In-app Video) 01 (Unknown Display when the media app is unknown) 02 (Unknown Video when the media app is unknown) 10 (Browser Unknown when the format is unknown) 20 (In-app Unknown when the format is unknown) 00 (Unknown Unknown when both the app and format is unknown)

hitDate

The date in which IAS pulled the data and is displayed only when groups includes 'date' or 'daily'.

recordCount

The number of results.

executionTimeMS

The time, in milliseconds, the query took.

path

The path of the query.

query

The query parameters used to generate the report.

Dimensions

Endpoint

Function

Campaigns

/campaigns/{campaign_ids}/qualifiedads

Filter metrics by specific campaign

Publishers

/publishers/{publisher_ids}/qualifiedads

Filter metrics by specific publishers

Campaigns and Publishers

/campaigns/{campaign_ids}/publishers/{publisher_ids}/qualifiedads

Filter metrics by specific campaigns and publishers

Param

Description

Variable Type and Example

Default Value

qualifiedAdsCriteria

Allows user to customize Qualified Ads criteria based on viewability, invalid traffic, geo, and brand safety.

Array. Colon delimited for groups:

qualifiedAdsCriteria=[viewability:fraud:geo:brandsafety]

qualifiedAdsCustomMetricsId

ID of the custom viewability methodology. Note: Contact your Customer Service representative for details on which qualifiedAdscustomMetricsId to use.

Integer:

Example: for a GroupM team: qualifiedAdsCustomMetricsId=2

period

You can specify a named keyword or dates to define the report period. Options include:

Named keywords: yesterday, today, latestDay, twoDaysAgo, last7days, last30days, thisWeek, lastWeek, lastMonth, thisMonth, thisQuarter, lastQuarter.

Date: you can use a range or a specific date.

String:

period=yesterday

period=twodaysago

Array:

period=[2011-02-01..2011-02-15] (elipses delimited for a date range)

period=[2011-02-01,2011-03-04] (comma delimited for specific dates)

last7days

groups

Granularity of grouping for result set. Options:

camp - the campaign

pub - the publisher (Primary seller); using pub returns the properties publisherId and publisherName. The reporting service then groups the output data by each publisher ID.

plac - the placement (ad unit). Groups results via an external placement ID, extPlacementId, defined when the campaign is configured. If an IAS generated ID is present (iasPlacementID) then the IAS generated ID is used. Since not all clients pass in an external placement ID, the extPlacementId might be missing.

date or daily

weekly

monthly

mediaApplicationAndFormat

mediaChannel

mediaFormat

site - returns metrics grouped at a domain/URL level

app - returns metrics grouped at the app level

Array. Colon delimited for groups:

groups=[camp:pub:daily] - the result set contains one record for each campaign, publisher and date combination.

groups=[camp] - the result set contains one record per campaign

deliveryEnvironment

Filters result by the specified delivery environments. By default all delivery environments will be included. Possible values include: 'desktop', 'mobileweb', and 'mobileapp'.

Array. Colon delimited for groups:

deliveryEnvironment=[mobileweb:mobileapp]

[desktop:mobileweb:mobileapp]

cutoff

Omits records from the result set that have totalImpressions < cutoff. Note that cutoff is applied after grouping the results.

Integer:

when groups=[camp:pub:daily] the result set will contain records that have totalImpressions >= cutoff for each day, publisher and campaign combination.

When groups=[camp] the result set will contain records that have totalImpressions >= cutoff for each campaign.

sortIndex

Sorts results by the given column. Any column in the result set can be specified here.

String:

sortIndex=totalImpressions

eligibleForQualifiedAds

sortOrder

Sorts records in the ascending or descending order of the sortIndex.

asc - for ascending order

desc - for descending order

String:

sortOrder=asc

sortOrder=desc

desc

rows

Limits the number of records returned per page in the result set to this number.

When "app" or "site" default = '5000' Else = '200000'

page

Shows a specific page of records. rows and pages parameters can be used in combination to retrieve result sets in smaller chunks. In order to receive all records, increase the page number until you don't receive any additional results for that page.

Integer If a report is supposed to return 12,500 records, then rows=5000&page=1, returns the first 5,000 rows rows=5000&page=2, returns the next 5,000 rows rows=5000&page=3, returns the last 2,500 rows.

1

includeChangeRate

Allows the response to include the percentage change rate for a specified period compared to the value of the metric from the previous period. includeChangeRate is not supported with 'daily' or 'date' group. Similarly, it does not work for individual dates if specified in 'period'. includeChangeRate works for a named period or a date range.

Boolean (true/false): includeChangeRate=true

false

Objects and Keys

Description

totalTrackedAds

The total number of ads processed by IAS.

eligibleForQualifiedAds

When Qualified Ads criteria excludes viewability: The total number of ads processed by IAS. When Qualified Ads criteria includes viewability: The number of ads that were measured for viewability or failed another selected criteria (such as brand safety, invalid traffic, or geo) out of all ads.

eligibleForQualifiedPct

When Qualified Ads criteria excludes viewability: The percentage of total tracked ads out of all ads. When Qualified Ads criteria includes viewability: The percentage of ads that were measured for viewability or failed another selected criteria (such as brand safety, invalid traffic, or geo).

qualifiedAds

The number of ads that passed all selected Qualified Ads criteria.

Note: For Proprietary Platforms, ads can fail only for metrics covered by each integration. Some Proprietary Platforms may not cover geo and/or brand safety.

qualifiedPct

The percentage of ads that passed all selected Qualified Ads criteria (out of Eligible for Qualified Ads).

Note: For Proprietary Platforms, ads can fail only for metrics covered by each integration. Some Proprietary Platforms may not cover geo and/or brand safety.

nonQualifiedPct

The percentage of Eligible for Qualified Ads that failed for Qualified Ads (failed at least one of the selected Qualified Ads criteria).

nonQualifiedAds

The number of Eligible for Qualified Ads that failed for Qualified Ads (failed at least one of the selected Qualified Ads criteria).

nonQualifiedForViewabilityAds

The number of Not Qualified Ads that failed for Viewability.

nonQualifiedForViewabilityPct

The percentage of Not Qualified Ads that failed for Viewability.

nonQualifiedForBrandSafetyAds

The number of Not Qualified Ads that failed for Brand Safety.

nonQualifiedForBrandSafetyPct

The percentage of Not Qualified Ads that failed for Brand Safety.

nonQualifiedForFraudAds

The number of Not Qualified Ads that failed for Invalid Traffic.

nonQualifiedForFraudPct

The percentage of Not Qualified Ads that failed for Invalid Traffic.

nonQualifiedForGeoAds

The number of Not Qualified Ads that failed for Geo.

nonQualifiedForGeoPct

The percentage of Not Qualified Ads that failed for Geo.

blockableNonQualifiedAds

Not Qualified Ads that are eligible for blocking.

blockedNonQualifiedAds

Number of blockable Not Qualified Ads that were actually blocked.

blockedNonQualifiedPct

Percentage of blockable Not Qualified Ads that were actually blocked.

totalTrackedAdsChangeRate

The percentage change rate in Total Tracked Ads compared with the previous period.

eligibleForQualifiedAdsChangeRate

The percentage change rate in Eligible For Qualified Ads compared with the previous period.

eligibleForQualifiedPctChangeRate

The percentage change rate in the percentage of Eligible for Qualified Ads out of all ads, compared with the previous period.

qualifiedAdsChangeRate

The percentage change rate in Qualified Ads compared with the previous period.

qualifiedPctChangeRate

The percentage change rate in the percentage of Qualified Ads out of Eligible for Qualified Ads, compared with the previous period.

nonQualifiedAdsChangeRate

The percentage change rate in Not Qualified Ads compared with the previous period.

nonQualifiedPctChangeRate

The percentage change rate in the percentage of Not Qualified Ads out of Eligible for Qualified Ads, compared with the previous period.

nonQualifiedForViewabilityAdsChangeRate

The percentage change rate in Not Qualified Ads that failed for viewability compared with the previous period.

nonQualifiedForViewabilityPctChangeRate

The percentage change rate in the percentage of Not Qualified Ads that failed for viewability out of all Not Qualified Ads, compared with the previous period.

nonQualifiedForFraudAdsChangeRate

The percentage change rate in Not Qualified Ads that failed for invalid traffic compared with the previous period.

nonQualifiedForFraudPctChangeRate

The percentage change rate in the percentage of Not Qualified Ads that failed for invalid traffic out of all Not Qualified Ads, compared with the previous period.

nonQualifiedForGeoAdsChangeRate

The percentage change rate in Not Qualified Ads that failed for geo compared with the previous period.

nonQualifiedForGeoPctChangeRate

The percentage change rate in the percentage of Not Qualified Ads that failed for geo out of all Not Qualified Ads, compared with the previous period.

blockableNonQualifiedAdsChangeRate

The percentage change rate in Not Qualified Ads that are eligible for blocking compared with the previous period.

blockedNonQualifiedAdsChangeRate

The percentage change rate in blockable Not Qualified Ads that were actually blocked compared with the previous period.

blockedNonQualifiedPctChangeRate

The percentage change rate in the percentage of blockable Not Qualified Ads that were actually blocked, compared with the previous period.