| Table of Contents |
|---|
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.
...
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
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.
| Note |
|---|
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 |
|---|---|---|---|
| Required | Start date of the data | "2020-03-01" |
| Required | End date of the data | "2020-03-01" |
| Required | Publishers you wish to pull data for | ["publisherKey1", "publisherKey2"] |
| Required | Metric fields you wish to pull | ["wins", "clicks"] |
| Optional | Add in case you wish to group your data by any dimensions listed. | ["publisher_name", "site_name"] |
| Optional. | The |
|
| Optional | Must be a valid IANA timezone. If not specified, results are returned by UTC timezone. (list here) |
|
| 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 for more information on how to use filtering with your API calls.
...
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 |
|---|---|---|
| General Success | Successful |
| 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) |
| Unauthorized | No valid API key provided |
| Forbidden | The API key doesn’t have permissions to perform the request |
| Not found | The requested resource doesn’t exist |
| 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 |
| Name of the publisher |
DSP Name |
| DSP name. |
Site |
| Collection of placements that often correspond to a website or application. Example: "Cats.com" |
Primary Domain |
| The primary domain associated with the incoming web request. |
Notable Domain |
| The notable domain associated with the incoming web request. Example: “www.cats.com” |
Country |
| Two or three letter code abbreviation for the country. Example: "US" |
Placement Name |
| Name given to the placement or ad slot. |
Placement Key |
| Integration key associated with incoming request. Example: "bQRKnWWz6KnFqsGmttQmCoGP" |
Creative Type |
| Possible values for filtering are:"article", "banner", "carousel", "clickout", "native-outstream", "native-video", "outstream", "scroller", "slideshow". |
Device Type |
| Possible values for filtering are:
|
Date |
| Date which the impression was first requested. Example: "2020-08-10" |
Hour |
| Hour an impression was requested. Possible values 1-24. |
Inventory Type |
| Use this dimension to group or filter results by particular media formats. Possible values for this dimension are
|
Supply Integration |
| 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:
|
Type |
| The type of the site (i.e. app or web). Possible values are
|
App 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 |
| The operating system of the user, as determined by user agent. Possible values are
|
Placement Size |
| Size of the placement when set up by STR (display only placements) |
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 |
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 |
| Use this field to break out results as Advertiser name coming from the DSP and set up in the DSP. Note: not available when |
Jounce Directness |
| Use this field to break out results by directness as defined by Jounce. Possible values are
|
Jounce SPO Segment |
| Use this field to break out results by SPO Segment as defined by Jounce. Possible values are
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 |
| 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 |
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 |
| Total impression requests that the site sends to Sharethrough. |
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 |
| 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 |
| The served ad creative is rendered on the page. This is the payable event for publishers. |
Viewable Impressions |
| The ad comes at least 50% in view for at least 1 second. |
Earnings |
| Programmatic only. The estimated amount of revenue you’ve earned through the Sharethrough Exchange (STX) |
CPM |
| The eCPM for the entries returned by the query. |
Clicks |
| The total number of times users clicked on ads |
CTR |
| Click-through rate (= clicks /rendered impressions)
The percentage of rendered impressions that a user clicks on |
Fill Rate |
| = (rendered impressions/impressions requests)*100 The percentage of ad calls being filled with a creative for a given placement |
Viewability Rate |
| = viewable impressions/ rendered impressions The percentage of paid impressions that are viewable |
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 |
| When 50% of the video placement is in view (no minimum time) and there is no error, the player starts |
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) |
| How many users reached 3 seconds during the video |
Video Views (10+ seconds) |
| How many users reached 10 seconds during the video |
Video Views (15+ seconds) |
| How many users reached 15 seconds during the video |
Video Views (30+ seconds) |
| How many users reached 30 seconds during the video |
25% Content Completion |
| How many users reached 25% of the video |
50% Content Completion |
| How many users reached 50% of the video |
75% Content Completion |
| How many users reached 75% of the video |
95% Content Completion |
| 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 | ||
|---|---|---|
| ||
{
"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:
...
| 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.
...
| Code Block | ||
|---|---|---|
| ||
{
“field”: “site_name”,
“value”: “some_hypothetical_site”,
“operator”: “NOT_EQUALS”
} |
CONTAINS
Use this to limit results to anything that has the letters specified.
...
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 ]).
...
| Code Block | ||
|---|---|---|
| ||
{
“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
| Code Block | ||
|---|---|---|
| ||
{
"publishers": ["1234567"],
"startDate": "2020-02-16",
"endDate": "2020-02-18",
"groupBy": ["date"],
"fields": ["rendered_impressions", "viewable_impressions", "clicks", "pub_earnings"],
} |
Response
| Code Block | ||
|---|---|---|
| ||
{
"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
}
]
} |