V2 Supply API Endpoint - Sharethrough Publisher API Documentation

Overview

The Sharethrough Reporting API offers publishers a programmatic way to access performance data. It's a HTTP API that follows a RESTful design pattern. You can retrieve results in a CSV or JSON format.

Note: If you are unable to access this data through an API connection, please contact your Account Manager who can give you a URL to access these fields in a UI. From there, you can download your own reports.

If you have access to the current API, your token is valid for this V2 Supply API Endpoint. If you need a new token, please reach out to support@sharethrough.com or through your Sharethrough contact.

Authentication

The Sharethrough Reporting API uses API Keys to authenticate requests. Authentication to the API is performed via HTTP Basic Auth.

Be sure to not share your API key to keep your data secure. Also, all API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Endpoint

Method

POST: https://reporting-api.sharethrough.com/v2/programmatic/supply

Required Header

Authorization: Bearer $TOKEN_STRING

Optional Header

Accept: text/csv (if you want results in CSV format, for JSON just omit the header)

Request Body

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.	The `filterBy` section is a place where you can specify filters (up to 3) for your API call. See the Filtering Results section 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

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.

Results

Format: We support JSON and CSV Outputs
Date Range: Historical information is available up for 1 year
All numbers are reported in time zone UTC (+00:00), unless the 'timezone' attribute is specified in the request body
Data available in the API is processed hourly. For a full day's worth of data, we recommend pulling next day.

HTTP Response Codes

Sharethrough uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Code	Definition	Conditions when used
`200`	General Success	Successful
`400`	Bad Request	The API cannot process this request. This is usually because the request payload is malformed (i.e. missing fields, or improper/non-existent fields or filters specified)
`401`	Unauthorized	No valid API key provided
`403`	Forbidden	The API key doesn’t have permissions to perform the request
`404`	Not found	The requested resource doesn’t exist
`500`, `502`, `503`, `504`	Server errors	Something went wrong on Sharethrough’s end

Dimensions

The table below describes the types of dimensions that can be accessed through the API. You can group and/or filter by one or more (up to 6) of the following values:

Dimension	API Representation	Notes
Publisher Name	`publisher_name`	Name of the publisher
DSP Name	`dsp_name`	DSP name.
Site	`site_name`	Collection of placements that often correspond to a website or application. Example: "Cats.com"
Primary Domain	`primary_domain`	The primary domain associated with the incoming web request.
Notable Domain	`notable_domain`	The notable domain associated with the incoming web request. Example: “www.cats.com”
Country	`country`	Two or three letter code abbreviation for the country. Example: "US"
Placement Name	`placement_name`	Name given to the placement or ad slot.
Placement Key	`placement_key`	Integration key associated with incoming request. Example: "bQRKnWWz6KnFqsGmttQmCoGP"
Creative Type	`creative_type`	Possible values for filtering are:"article", "banner", "carousel", "clickout", "native-outstream", "native-video", "outstream", "scroller", "slideshow".
Device Type	`device_type`	Possible values for filtering are: "Connected Device" "Connected TV" "Mobile/Tablet" “Personal Computer" "Phone" “Set Top Box” “Tablet”
Date	`date`	Date which the impression was first requested. Example: "2020-08-10"
Hour	`hour`	Hour an impression was requested. Possible values 1-24.
Inventory Type	`inventory_type`	Use this dimension to group or filter results by particular media formats. Possible values for this dimension are "display" "video" "native"
Supply Integration	`supply_name`	The name of the supply integration path to filter by. There are many possible values to supply as filters for this property. Below is a partial list of examples: "Google OB" "Index Exchange" "Microsoft" "Prebid Client-side" "Prebid Server" "Tag on Page" "Verizon"
Type	`site_type`	The type of the site (i.e. app or web). Possible values are “AppProperty” “WebProperty”
App Bundle ID	`bundle_id`	The bundle ID for a given app. This is a string whose format varies across providers (e.g. “com.something.else” for Android, “1234567” for iOS, etc.)
OS Type	`os_type`	The operating system of the user, as determined by user agent. Possible values are “Android” “Chrome OS” “MacOS” “Windows” “iPadOS” “iPhoneOS”
Placement Size	`placement_size`	Size of the placement when set up by STR (display only placements)
Adelaide AU Group	`adelaide_au_group`	Use this field to break out results by Adelaide Attention Score. Attention Score can take the values of “High”, “Medium”, or “Low”. Note: not available when `cpm` or `dsp_name` are included as fields in the request payload.
Adverifai Score Bucket	`adverifai_score_bucket`	Use this field to break out results by Adverifai’s score bucket. Score buckets are basically score ranges that increment by 0.05 and go from 0 to 1. So, for example, one site might have a score of 0.15, while another might be 0.22. These two entries would be broken out into separate buckets.
Advertiser Domain	`advertiser_domain`	Use this field to break out results as Advertiser name coming from the DSP and set up in the DSP. Note: not available when `cpm` or `dsp_name` are included as fields in the request payload.
Jounce Directness	`jounce_directness`	Use this field to break out results by directness as defined by Jounce. Possible values are Direct Outsourced Yield Management Proprietary Placement Content Syndication Rebroadcasting Non-Transparent Not Classified
Jounce SPO Segment	`jounce_spo_segment`	Use this field to break out results by SPO Segment as defined by Jounce. Possible values are Premium Publisher-Controlled Premium Intermediary-Controlled Multi-Hop Reselling Made For Advertising Cheap Reach The value is [not_in_jounce_table] when the combination of Publisher Key, Bundle ID App Only and Primary Domain is not classified by Jounce
Open vs Deal	`open_vs_deal`	Use this field to break out results by whether they are “open” or a “deal”. Open means that the advertiser served impression on STX without targeting a deal. Deal means that the advertiser served impression on STX by targeting a deal. Note: not available when `cpm` or `dsp_name` are included as fields in the request payload.

Fields (Metrics)

The table below describes the header bidding metrics that can be accessed through the API: At least one field is required in the request:

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:

{
  "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:

{
  "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.

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”:

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

CONTAINS

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

Note that filtering with CONTAINS is case-sensitive.

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

{
  “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:

{
  “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:

{
  “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.

Example Request & Response

Request

{
    "publishers": ["1234567"],
    "startDate": "2020-02-16",
    "endDate": "2020-02-18",
    "groupBy": ["date"],
    "fields": ["rendered_impressions", "viewable_impressions", "clicks", "pub_earnings"],
}

Response

{
    "results": [
        {
            "DATE": "2020-02-17",
            "RENDERED_IMPRESSIONS": 3265224,
            "VIEWABLE_IMPRESSIONS": 1553567,
            "CLICKS": 8334,
            "PUB_EARNINGS": 43966411
        },
        {
            "DATE": "2020-02-18",
            "RENDERED_IMPRESSIONS": 3064240,
            "VIEWABLE_IMPRESSIONS": 1519001,
            "CLICKS": 7723,
            "PUB_EARNINGS": 43069528
        },
        {
            "DATE": "2020-02-16",
            "RENDERED_IMPRESSIONS": 3146531,
            "VIEWABLE_IMPRESSIONS": 1412046,
            "CLICKS": 7106,
            "PUB_EARNINGS": 443284816
        }
    ]
}