Sharethrough Publisher API Documentation [Deprecated Jan 2024]

1 Overview
2 Authentication
3 API Endpoint
- 3.1 Method
- 3.2 Required Header
- 3.3 Optional Header
4 Request Body
- 4.1 filterBy object
5 HTTP Response Codes
6 Dimensions
7 Fields
8 Token Management
9 Example Request & Response
- 9.1 Request
- 9.2 Response

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

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	Optional - if not specified, all publishers that you have access to will be returned	Publishers you wish to pull data for	["publisherKey1", "publisherKey2"]
fields	Required - At least 1 metric field is required	Metric fields you wish to pull	["wins", "clicks"]
groupBy	Optional	Add in case you wish to group your data by any dimensions listed. Below (up to 6). If not specified, there will be a single row of results representing the totals of the different metrics/fields across all your inventory	["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 (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. Defaults to “EQUALS”

When not specified, only matching results are returned.

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
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
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"
DSP Name	dsp_name	Name of a particular demand source to which to limit results.
Device Type	device_type	Possible values for filtering are: "Console", "Desktop", "Smallscreen", "Smartphone", "Tablet".
Advertiser Domain	ad_domains	The advertising domains that are serving ads on your inventory Multiple domains will appear as an array
Creative Type	creative_type	Possible values for filtering are:"article", "banner", "carousel", "clickout", "native-outstream", "native-video", "outstream", "scroller", "slideshow"
Date	date	Date which the impression was first requested. Example: "2020-08-10"
Hour	hour	Hour the impression was first requested. Example: "20:00".
Supply Integration	supply_name	Supply integration paths. Possible values for filtering are: "Google OB", "Index Exchange", "Microsoft", "Prebid Client-side", "Prebid Server", "Tag on Page", "Verizon", "http://media.net "
Type	site_type	Website or Application (App)
IOS Bundle ID	ios_bundle_id	IOS Bundle ID
Android Bundle ID	android_bundle_id	Android's bundle ID
OS Type	os_type	Operating systems - IOS or Android
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:

Fields	API Representation	Description
Impression Requests	impression_requests	The site sends an impression request to Sharethrough. Note: The following fields cannot be pulled with impression requests since they are unknown at the time of the impression: · Creative_type · Advertiser_domain · Creative_key
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) Note: Your earnings are derived from rendered impressions
CPM	cpm	Programmatic only. Value = (Pub earnings * 1000)/Rendered impressions
Clicks	clicks	The total number of times users clicked on ads
CTR	ctr	= 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 Note:* The following fields cannot be pulled with fill rate since they are unknown at the time of the impression: · Creative_type · Advertiser_domain · Creative_key
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"],
    "debug": true
}

Response

{
    "metadata": {
        "rows": 3
        "statementId": "0192c81b-01c3-1eb5-0000-00a82fa532a2",
        "elapsedMs": 24829
    },

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