| Table of Contents |
|---|
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
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.
...
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. 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”} ] |
| 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 |
filterBy object
| Optional. | When not specified, only matching results are returned - that is, the operator is assumed to be “EQUALS”. Possible values for this property are
|
| Required | This is the name of the dimension field on which you wish to filter. |
| 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.
...
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 |
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" |
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. |
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) |
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 |
| 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 |
Token Management
Please reach out to support@sharethrough.com if you need a token activated or deactivated.
...