API Reference

We recommend using the framework, or building an extension off of the framework, but you can also access the API directly.

The base URL for the serving API is srv.buysellads.com. HTTPS is supported by default.

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
forcenads Integer. Request a different number of ads to be returned than is set as the default (the default usually 1).


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.