Engine v1 api doc

gistfile1.txt

AdOS API
========
The AdOS api allows you to bulk request image based ads via a json-based interface. 

Request Format
--------------
The basic format of a request is: GET http://engine.adzerk.net/api/v1?request={ url encoded request data }

The request data should be an array of placement objects. A placement object can contain the following fields
  * divName [String] an arbitrary unique id for the placement
  * adTypes [Array<Number>] the set containing all adTypes that the placement supports
  * zoneIds [Array<Number>] the set containing all zone ids that the placement supports
  * networkId [Number] the id of the network that the placement is restricted to searching
  * siteId [Number] the id of the site that the placement is restricted to searching
  * campaignId [Number] the id of the campaign that the placement is restricted to searching
  * flightId [Number] the id of the flight that the placement is restricted to searching
  * adId [Number] the id of the ad that the placement is restricted to searching
  * clickUrl [String] if set, overrides the clickUrl for the ad matched to the placement

Not all fields are mandatory, but you must specify a divName, a siteId, and one or more adTypes.

Response Format
---------------
The API server will return a JSON object with key value pairs matching a divName to an ad object. An object contains the following fields
  * click [String] the url to GET on a click
  * veripixel [String] the url to GET on a successful showing of the ad
  * image [String] the url of the image to display
  * metadata [Object] an object containing additional data (flightId, campaignId, etc.)

The response will be of type 'application/json', and no additional parsing will be required.

Example
-------
If we wanted to get a single ad of type 5 (medium rectangle), in the site with id 22032, you would generate the following:
[{"networkId":4161, "divName":"1", "adTypes":[5]}]

You can then issue the request (by urlencoding the above): 
GET http://engine.adzerk.net/api/v1?request=%5B%7B%22siteId%22%3A22032%2C%22divName%22%3A%221%22%2C%22adTypes%22%3A%5B5%5D%7D%5D

Let's make this API using the curl command line tool:
→ curl http://engine.adzerk.net/api/v1\?request\=%5B%7B%22siteId%22%3A22032%2C%22divName%22%3A%221%22%2C%22adTypes%22%3A%5B5%5D%7D%5D
{
  "1": {
    "image": "http://static.adzerk.net/Advertisers/833dac2aaa0a41dcb9e81620365e237f.jpg",
    "click": "http://engine.adzerk.net/r?e=eyJ0cyI6MTM2MTU1ODk0MDQzNSwiYXYiOjE1NDA4LCJhdCI6NSwiY20iOjIyMzE4LCJjaCI6NzczMSwiY3IiOjU3NjA5LCJkbSI6MywiZmMiOjgyMjI0LCJmbCI6NDE1OTYsImt3IjoiIiwibnciOjQxNjEsInJ2IjowLCJwciI6MTkzMDEsInN0IjoyMjAzMiwiZGkiOiJmNzc0NTVjNWZiMGM0YzdhYjJkZWYwMWNkOWFmMjVhOSIsInVyIjoiaHR0cDovL2FkemVyay5jb20ifQ&s=DFbivPOcW-K9HLMtMBYZJGMSK90",
    "veripixel": "http://engine.adzerk.net/i.gif?e=eyJ0cyI6MTM2MTU1ODk0MDQzNiwiYXYiOjE1NDA4LCJhdCI6NSwiY20iOjIyMzE4LCJjaCI6NzczMSwiY3IiOjU3NjA5LCJkbSI6MywiZmMiOjgyMjI0LCJmbCI6NDE1OTYsImt3IjoiIiwibnciOjQxNjEsInJ2IjowLCJwciI6MTkzMDEsInN0IjoyMjAzMn0&s=DT-4oCvIz66d043eRtO7VIkdNPM",
    "metadata": {
      "type": "impression",
      "timestamp": 1361558940436,
      "adId": 82224,
      "advertiserId": 15408,
      "adType": 5,
      "campaignId": 22318,
      "channelId": 7731,
      "creativeId": 57609,
      "decisionId": "f77455c5fb0c4c7ab2def01cd9af25a9",
      "deliveryMode": 3,
      "flightId": 41596,
      "noTrack": false,
      "networkId": 4161,
      "priorityId": 19301,
      "revenue": 0,
      "siteId": 22032,
      "isTrackingConversions": false,
      "keywords": [],
      "isFrequencyCapped": false,
      "isPayoutCapped": false,
      "isPublisherPayoutExempt": false
    }
  }
}

Multiple Ads
------------
To request multiple ads, simply pass additional placements with unique divNames. So to continue our previous example, if we wanted to also request an ad of type 6 (Wide skyscraper), we would generate the following JSON:
[{"networkId":4161, "divName":"1", "adTypes":[5]}, {"networkId":4161, "divName":"2", "adTypes":[6]}]