Page Comparison

...

Parameter	Required?	Description	Example
`startDate`	Required	Start date of the data	"2020-03-01"
`endDate`	Required	End date of the data	"2020-03-01"
`publishers`	Required	Publishers you wish to pull data for	["publisherKey1", "publisherKey2"]
`fields`	Required	Metric fields you wish to pull	["wins", "clicks"]
`groupBy`	Optional	Add in case you wish to group your data by any dimensions listed.	["publisher_name", "site_name"]
`filterBy`	Optional. If specified a value of no more than 3 filterBy objects as defined by separate table below	Add in case you wish to filter your data by any dimensions listed below (up to 3)	[ {field: "publisher_name	The `filterBy` section is a place where you can specify filters (up to 3) for your API call. See the Filtering Results later in this document for more information on how to use filters.	`[ {field: "publisher_name", value: "Test Pub", operator: "EQUALS"}, {field: "site_name", value: "Some site name", operator: "NOT_EQUALS"} ]`
`timezone`	Optional	Must be a valid IANA timezone. If not specified, results are returned by UTC timezone. (list here)	`"America/Chicago"`
`debug`	Optional	Requests also return timestamp and a query ID that can be shared with Sharethrough for debugging purposes	"debug": true

filterBy object

...

operator

...

Optional.

When not specified, only matching results are returned - that is, the operator is assumed to be “EQUALS”.

Possible values for this property are

...

“EQUALS”

Filter object

If you decide to use filters for your API call, you first specify a filterBy section in your request payload, and within that, you create filters. Each filter should be shaped like this (table below). See the Filtering Results section further down for more information on how to use filtering with your API calls.

operator

Optional.

When not specified, only matching results are returned - that is, the operator is assumed to be “EQUALS”.

Possible values for this property are

“EQUALS”
“NOT_EQUALS”
“CONTAINS”
“IN”
“NOT_IN”

field

Required

This is the name of the dimension field on which you wish to filter.

value

Required

Evaluated against the field in manner determined by filter.

...

Field	API Representation	Description
Impression Requests	`impression_requests`	Total impression requests that the site sends to Sharethrough.
Server Impressions	`server_impressions`	When a bid wins our internal auction. For the majority of our supply we need to send this winning bid to participate in the publisher's downstream Header Bidding auction against other exchanges.
Header Bidding Wins	`wins`	Sharethrough wins the impression in the publisher ad server/HB wrapper auction and a signal is sent to the page, the impression is loaded but the assets are not yet rendered.
Rendered Impressions	`rendered_impressions`	The served ad creative is rendered on the page. This is the payable event for publishers.
Viewable Impressions	`viewable_impressions`	The ad comes at least 50% in view for at least 1 second.
Earnings	`pub_earnings`	Programmatic only. The estimated amount of revenue you’ve earned through the Sharethrough Exchange (STX)
CPM	`cpm`	The eCPM for the entries returned by the query.
Clicks	`clicks`	The total number of times users clicked on ads
CTR	`ctr`	Click-through rate (= clicks /rendered impressions) The percentage of rendered impressions that a user clicks on
Fill Rate	`fill_rate`	= (rendered impressions/impressions requests)*100 The percentage of ad calls being filled with a creative for a given placement
Viewability Rate	`viewability_rate`	= viewable impressions/ rendered impressions The percentage of paid impressions that are viewable
Render Rate	`render_rate`	= (rendered impressions/ received impressions)*100 Once an impression is won and loaded, the percentage of times the assets are actually appearing/rendered on a page.
Video Starts	`video_starts`	When 50% of the video placement is in view (no minimum time) and there is no error, the player starts
Video Start Rate	`video_start_rate`	= (Video starts/Rendered impressions)*100 The percentage of videos that come into view and start once the final auction is won and the ad is rendered.
Video Views (3+ seconds)	`video_views_3secs`	How many users reached 3 seconds during the video
Video Views (10+ seconds)	`video_views_10secs`	How many users reached 10 seconds during the video
Video Views (15+ seconds)	`video_views_15secs`	How many users reached 15 seconds during the video
Video Views (30+ seconds)	`video_views_30secs`	How many users reached 30 seconds during the video
25% Content Completion	`video_completion_25`	How many users reached 25% of the video
50% Content Completion	`video_completion_50`	How many users reached 50% of the video
75% Content Completion	`video_completion_75`	How many users reached 75% of the video
95% Content Completion	`video_completion_95`	How many users reached 95% of the video

Filtering Results

In addition to specifying which fields you would like in your returned data, you can also further refine your results by filtering them.

You do this by adding one or more filters to a filterBy section in your request payload. Filters and the filterBy section are completely optional.

Simple Example - filter data to only show results involving video inventory

In this example, we use a single filter to limit what we get to earnings and cpm that involve video inventory:

Code Block

language	json

{
  "startDate":"2024-01-15",
  "endDate":"2024-01-15",    
    "fields": [
        "pub_earnings",
        "cpm"
    ],
    "groupBy": [
        "inventory_type"
    ],
    "filterBy": [{
        "field": "inventory_type",
        "value": "video",
        "operator": "EQUALS"
    }],
    "publishers": [
        "YOUR_PUB_KEY_HERE"
    ]
}

More Complex Example - multiple filters

We can further refine results by adding additional filters. Here, we add a second one that further states we’re only interested in video-related results for a hypothetical site:

Code Block

language	json

{
  "startDate":"2024-01-15",
  "endDate":"2024-01-15",    
    "fields": [
        "pub_earnings",
        "cpm"
    ],
    "groupBy": [
        "inventory_type"
    ],
    "filterBy": [{
        "field": "inventory_type",
        "value": "video",
        "operator": "EQUALS"
    },{
        "field": "site_name",
        "value": "some_hypothetical_site",
        "operator": "EQUALS"
    }],
    "publishers": [
        "YOUR_PUB_KEY_HERE"
    ]
}

Be sure to include all filters within the brackets ([ and ]) that follow filterBy.

Info
Note that when we combine filters, we are “AND-ing” them together. In other words: in the example above, the API call will only return results where BOTH filter conditions are true (result is video-related AND it’s for the “some_hypothetical_site” site).

Further ways of filtering

In the examples above, we created filters using the “EQUALS” value for the operator of each filter, which matches results to exactly whatever was specified for the value property of the filter.

We can also filter in other ways.

NOT_EQUALS

Use this to limit results to anything that does NOT have exactly this value.

Example - show us results for anything BUT “some_hypothetical_site”:

Code Block

language	json

{
  “field”: “site_name”,
  “value”: “some_hypothetical_site”,
  “operator”: “NOT_EQUALS”
}

CONTAINS

Use this to limit results to anything that has the letters specified.

Info
Note that filtering with CONTAINS is case-sensitive.

Example - show us results where ‘foo’ is in the name of the site_name field:

Code Block

language	json

{
  “field”: “site_name”,
  “value”: “foo”,
  “operator”: “CONTAINS”
}

Remember that because the CONTAINS filter operates on a case-sensitive basis, results will include sites with names like “foobar” and “barfoo”, but will NOT contain “Foobar” or “barFoo” (“foo” != “Foo”).

IN

Use this as a quick way to specify multiple values you want to specify for your results. You do this by including all possible values within a pair of brackets ([ and ]).

Example - show us results for US, Canada and Australia:

Code Block

language	json

{
  “field”: “country”,
  “value”: ["US","CA","AU"],
  “operator”: “IN”
}

NOT_IN works in much the same way, except that any values included in the brackets are excluded from results.

Example - show us results for anyplace BUT the US, Canada and Australia:

Code Block

language	json

{
  “field”: “country”,
  “value”: ["US","CA","AU"],
  “operator”: “NOT_IN”
}

Token Management

Please reach out to support@sharethrough.com if you need a token activated or deactivated.

...

Versions Compared

Old Version 24

New Version 25

Key

filterBy object

Filter object

Filtering Results

Simple Example - filter data to only show results involving video inventory

More Complex Example - multiple filters

Further ways of filtering

NOT_EQUALS

CONTAINS

IN

Token Management