Ad Serving API Quick Start

With the Ad Serving API, you can retrieve ad(s) to display. We do the hard work of decisioning and pacing based on the serving criteria for all of your ads, all you need to do is call the API and we give you exactly what needs to serve for that specific API call. Let's dive in!

First things first, to construct the API call you need to locate the "data-serve" attribute for the ad zone you want to call.

You can find the data-serve attribute for each zone listed on your "Inventory" page: https://pro.buysellads.com/p/zones

Now that you have the data-serve attribute you have everything you need to call one of the Ad Serving API Endpoints:

Endpoint: /ads/ZONEKEY.<format>

Formats allowed JSON, JS, HTML (eg .json, .js, .html)
Behavior Serves up to the "number of ads per page" ads with all data. If the request type is JS, it will render the ads with their specified template.

Tracks an impression and zone hit.
Allowed query-string parameters ignore Whether or not to track this impression
freqcap Frequency capping data
track Specify to NOT track via the bsawt cookie
callback Provided it is alphanumeric, allows you to specify the function name (when js)
country ID of specified GEO, if applicable (otherwise, it is determined by the ad server)
browser ID of specified browser, if applicable (otherwise, it is determined by the ad server)
os ID of specified operating system, if applicable (otherwise, it is determined by the ad server)
ignorebanner ID (admanbanner) to never serve
maxpriority Max priority level to serve
segment Allows specification of one segmentation string to serve ads that require it
forwardedip Allows specification of the IP address (for use with geo/region/location targeting, if any)
useragent Pass useragent=<user agent string> to any ad serving call



Endpoint: /ads/all/id/ZONEKEY.json

Formats allowed JSON
Behavior Returns all ads within the zone (with creative data) that match the current targeting (segment/geo/br/etc) and writes them out as a JSON string.

Does not track an impression, but tracks a zone hit.
Allowed query-string parameters callback Provided it is alphanumeric, allows you to specify the function name (when js)
country ID of specified GEO, if applicable (otherwise, it is determined by the ad server)
browser ID of specified browser, if applicable (otherwise, it is determined by the ad server)
os ID of specified operating system, if applicable (otherwise, it is determined by the ad server)
ignorebanner ID (admanbanner) to never serve
maxpriority Max priority level to serve
segment Allows specification of one segmentation string to serve ads that require it
useragent Pass useragent=<user agent string> to any ad serving call



Endpoint: /ads/all/ids/ZONEKEY;ZONEKEY;ZONEKEY

Formats allowed None, always JS
Behavior Renders ads with their specified templates, encapsulated in a JS function for rendering via our adcode.

Tracks an impression for each valid zone and zone hit for each valid zone.
Allowed query-string parameters ignore Whether or not to track impressions for this request.
freqcap Frequency capping data
ignorebanner ID (admanbanner) to never serve
forcebanner ID (admanbanner) to force serving
ignoretargeting Whether or not to ignore specified targeting data of ads
maxpriority Max priority level of ads to serve
segment_ZONEKEY Allows specification of one segmentation string to serve ads that require it; per-zone
forwardedip Allows specification of the IP address (for use with geo/region/location targeting, if any)
useragent Pass useragent=<user agent string> to any ad serving call



Endpoint: /ads/rss/get/id/ZONEKEY

Formats allowed n/a
Behavior Redirects the request to the image(s) that should be serving for a specific RSS zone. Requires `rss_enabled` to be in the kv store for the zone.

Tracks an impression if the zone is valid and for the served image.
Allowed query-string parameters a ("article ID") Allows us to set a cookie (for click redirects, etc etc). This parameter is REQUIRED.



Endpoint: /ads/whoami

Formats allowed text
Behavior Displays data about the requesting user: USERID (IP_ADDRESS, USER_AGENT; COUNTRY / BROWSER / OS / REGION / CITY)
Allowed query-string parameters forwardedip Allows specification of the IP address (for use with geo/region/location targeting, if any)



Endpoint: /ads/tracked

Formats allowed text, JS
Behavior Dumps data about banners and creatives the requesting user has viewed or clicked.
Allowed query-string parameters callback If alphanumeric, the data is encapsulated in a JS function for programmatic processing.