...
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) |
|
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
|
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.
...
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.
...