β V2 Supply API Endpoint - Sharethrough Publisher API Documentation

Please note that this publisher API endpoint is currently in BETA. Please contact your RevOps Manager or support@sharethrough.com if you have questions regarding this 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.

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. 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”, value: “Test Pub”}, {field: “site_name”, value: “Some site name”} ]
`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”
“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
Site	`site_name`	Collection of placements that often correspond to a website or application. Example: "Cats.com"
Primary Domain	`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"
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.
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)

Fields

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

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
        }
    ]
}