# HTTP We provide an HTTP API for requesting ads from our delivery server. This API may be used, for example, to enable server-side fetching of ads. ## Usage ### GET Requests ```http GET https://delivery.adnuntius.com/i{{params}} ``` | Parameter | Required? | Example value(s) | Default Value | Description | | --------- | --------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | auId | Yes, unless making a POST request (see below) | ab123456789 (string) | None | The Tag ID for the Ad Unit to fetch ads from | | tzo | No | -120 (number) | 0 | Timezone, offset from UTC in minutes | | userId | No | ab123456789 (string) | If not provided, this value will be read from the Adnuntius cookie | Identifies a unique user; used for segment targeting, rate limiting, and unique user counting | | siteId | No | ab123456789 (string) | None | A unique identifier for the site where the ad will be shown. This will be used, if required by your DMP, for segment targeting | | tt | No | composed, multi, vast2 | None | The Tag Type. The composed and multi tag-types can only be used with a POST request (see below) | | format | No | html, xml, json, image, email (string) | html | Specifies the format of the returned ads | ### Post Requests ```http POST https://delivery.adnuntius.com/i{{params}} ``` The parameters listed above in the **Get Requests** section are also supported on POST requests. #### POST Body | Parameter | Example value | Description | | --------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | | adUnits | - | An array of objects for the adunits that you wish to request. | | auId | ab123456789 (string) | The ad unit tag id in question. | | targetId | adn-123456789 (string) | The id of the HTML element you wish your ad to be placed in. | | metaData | `{"network!usi": "aaaa", "i": "0AAAAAZa9gZwGAQAAAACEPAA="}` | Pass in meta-data (such as frequency capping data) returned by a previous request. | Example POST Body: ```javascript { "adUnits":[ { "auId":"abc123", "targetId":"adn-abc123" }, { "auId":"xyz987", "targetId":"adn-xyz987" } ], "metaData": { "i": "0AAAAAZa9gZwGAQAAAACEPAA=", "network!usi": "aaaa" } } ``` ## Examples ### GET request #### Request ```http GET http://delivery.adnuntius.com/i?tzo=-120&auId=abc123&userId=xyz987 ``` #### Response ```markup
``` ### POST request #### Request ```http POST http://delivery.adnuntius.com/i?tzo=-120&userId=xyz987&tt=composed ``` POST Body: ```javascript { "adUnits":[ { "auId":"abc123", "targetId":"adn-abc123" }, { "auId":"xyz987", "targetId":"adn-xyz987" } ], "metaData": { "network!usi": "aaaa", "i": "0AAAAAZa9gZwGAQAAAACEPAA=" } } ``` #### Response ```javascript { "adUnits": [ { "auId": "abc123", "targetId": "adn-abc123", "html": "\n\n\n \n \n\n \n\n\n
\n
\n\"\"/\n\n\n\n\n
\n
\n\n \n \n \n \n \n\n \n \n\n\n \n\n\n", "matchedAdCount": 1, "rts": [ "yyyyyy" ] } { "auId": "xyz987", "targetId": "adn-xyz987", "html": "\n\n\n \n \n\n \n\n\n
\n
\n\"\"/\n\n\n\n\n
\n
\n\n \n \n \n \n \n\n \n \n\n\n \n\n\n", "matchedAdCount": 1, "rts": [ "zzzzzz" ] } ], "metaData": { "network!usi": "aaaa", "network!sessionId": "bbbb", "i": "0AAAAAZa9gZwGAQAAAACEPAA=" }, "duplicateFilter": "ccccc", "segments": [], "keywords": [] } ``` ### Targeting Parameters You can include targeting information with the HTTP request to the ad server that can control which line items or creatives match your request. #### Key-value targeting Key values can be sent to the ad server through HTTP like this: ```http http://delivery.adnuntius.com/i?tzo=-120&auId=00000000000481f7&kv=%5B%7B%22myKey%22%3A%5B%22myValue1%22%2C%22myValue2%22%5D%7D%5D ``` The `kv=` will be a URL encoded Json of what you wish to send. In the above case it's this: ```javascript kv: [{'myKey': ['myValue1', 'myValue2']}] ``` #### Category Targeting Category targeting can be sent to the adserver using the `c=` parameter. ```http &c=category1&c=sport%2Fbasketball&c=politics ``` Woud be the equivalent of sending this in the ad request: ```javascript c: ['category1', 'sport/basketball', 'politics'] ``` the content of the category should be URL encoded.