{"__v":6,"_id":"55f88ebd5840d119004346bf","category":{"__v":8,"_id":"55e76b8196131b2f00bf4b72","pages":["55e8b2c13fef5017000dbd9a","55e8b365f0f1850d00d24a5b","55f88ebd5840d119004346bf","55f8ab55c449610d002daf87","5603759a8d58900d0051e9ee","560375cd90ee490d004403da","5633b5ebc49a7c19001fd091","567353ae47f7010d005bfdc9"],"project":"5429beef1163360800ed31fa","version":"5429beef1163360800ed31fd","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-02T21:34:57.232Z","from_sync":false,"order":2,"slug":"apis","title":"Integrating with APIs"},"editedParams":true,"editedParams2":true,"parentDoc":null,"project":"5429beef1163360800ed31fa","user":"5429becb1163360800ed31f8","version":{"__v":20,"_id":"5429beef1163360800ed31fd","project":"5429beef1163360800ed31fa","createdAt":"2014-09-29T20:19:59.904Z","releaseDate":"2014-09-29T20:19:59.904Z","categories":["5429beef1163360800ed31fe","55e74e1f5d36b32b002563fa","55e7500a73169617001f2e86","55e76b8196131b2f00bf4b72","55e89569cdbb8a350096df9c","55f8935eb089b71700a8364e","55f8a67d3bb4bb0d0022d093","55f9dbefc7ef770d00d9bf6d","5601c21a22ecf60d002b27b3","5601c21ff12aee0d001bb06e","5601c2256c7b610d00280db5","5601c22c22ecf60d002b27b4","5603738d0c78b00d0039af47","5626f70bfcbbc621004ebf52","566f7a1ae144ab0d00e9732f","566f85ca7820960d00c3b93d","56708ce43a32d20d00c45cbf","56708d436995210d003aad8e","5736471abe10a9200030732c","57a82c7aff9bd30e00a6f1c1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-15T21:33:49.275Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","code":"GET \"http://api.adsnative.com/v1/ad.json?zid=ping\"","language":"curl"}]},"method":"get","results":{"codes":[{"name":"","code":"{\n  \"ad\": {\n      \"backgroundColor\": \"#fefff2\",\n      \"brandImageUrl\": \"http://dev-www.adsnative.com/media/brand_images/1/82cc86ad-9070-4b90-9006-1fbca6697694.jpg\",\n      \"embedUrl\": \"http://api.adsnative.com/v1/creative.html?crid=xyz&sid=sid123\",\n      \"imageSrc\": \"http://files-www2.adsnative.com/media/1/xyz.jpg\",\n      \"promotedBy\": \"Tesla\",\n      \"promotedByTag\": \"Promoted by\",\n      \"promotedByUrl\": \"http://api.adsnative.com/v1/ad.click?u=http%3A%2F%2Fxyz.com%2F&sid=sid123\",\n      \"summary\": \"Tesla teased electric motorheads earlier this week by announcing an event that would show off its curious battery swapping system...\",\n      \"target\": \"_parent\",\n      \"title\": \"Tesla Shows Off A 90-Second Battery Swap System, Wants It At Supercharging Stations By Year's End\",\n      \"trackingTags\": \"\",\n      \"type\": \"story\",\n      \"url\": \"http://api.adsnative.com/v1/ad.click?u=http%3A%2F%2Fxyz.com%2F&sid=sid123\"\n  },\n  \"cid\": \"cid123\",\n  \"count\": 1,\n  \"crid\": \"crid123\",\n  \"sid\": \"sid123\",\n  \"status\": \"OK\",\n  \"uuid\": \"uuid123\",\n  \"zid\": \"ping\"\n}","language":"json","status":200},{"name":"No campaigns found","code":"{\n    \"status\": \"FAIL\",\n    \"message\": \"no campaigns found\",\n    \"uuid\": \"e3b50f82-f570-44d0-8c17-638059c9edf2\"\n}","language":"json","status":200},{"name":"No adunits configured","status":200,"language":"json","code":"{\n    \"status\": \"FAIL\",\n    \"message\": \"no valid ad units found for this domain\",\n    \"uuid\": \"e3b50f82-f570-44d0-8c17-638059c9edf2\"\n}"},{"status":500,"language":"json","code":"{\n    \"status\": \"Internal Server Error\",\n    \"code\": \"500\",\n    \"description\": \"Something is broken. We are looking into it!\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"55f892dca3271b0d00498dc6","ref":"","in":"query","required":true,"desc":"This is the ad placement token that can be found in your dashboard","default":"","type":"array_string","name":"zid"},{"_id":"55f892dca3271b0d00498dc5","ref":"","in":"query","required":true,"desc":"client’s ipaddress to be used for city, region or country targeting","default":"","type":"string","name":"ip"},{"_id":"55f892dca3271b0d00498dc4","ref":"","in":"query","required":true,"desc":"client’s user agent","default":"","type":"string","name":"ua"},{"_id":"55f892dca3271b0d00498dc2","ref":"","in":"query","required":true,"desc":"client’s unique identifier to be used for frequency capping. AdsNative will attempt to set a uuid value in a cookie if parameter is not passed.","default":"","type":"string","name":"uuid"},{"_id":"567355a647f7010d005bfdcc","ref":"","in":"query","required":true,"desc":"In case of desktop and mobile web, it's the current page url where the ad unit is going to be shown, and in case of mobile apps it is the domain value with http. For example, http://example.com","default":"","type":"string","name":"url"},{"_id":"55f892dca3271b0d00498dc3","ref":"","in":"query","required":false,"desc":"client’s accept-language settings (e.g. ‘en-us’) to be used for language specific targeting","default":"","type":"string","name":"al"},{"_id":"55f892dca3271b0d00498dc1","ref":"","in":"query","required":false,"desc":"keyword targeting","default":"","type":"array_string","name":"kw"},{"_id":"56f8d223826ae81700f4da10","ref":"","in":"query","required":false,"desc":"Pass key name of the key-value pair and corresponding value. Replace [KEY_NAME] with configured 'key' handle name","default":"","type":"array_string","name":"ck_[KEY_NAME]"}],"url":"/ad.json"},"isReference":true,"order":0,"body":"Note:\n1. If the API request is made from browser client-side then the params - ua, ip, al and uuid parameters are optional.\n2. For parameters of values which are marked as array of string, you can pass multiple values by passing those params multiple times. For example, you can multiple zids to receive response for multiple placements such as ?zid=zone1&zid=zone2. Keywords as ?kw=sports&kw=baseball. Custom key-values as ?ck_tag=sports&ck_tag=baseball.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Parameters\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"status\",\n    \"0-1\": \"The status of the ad response. Returns ‘OK’ when a valid ad is present.\",\n    \"1-1\": \"Number of native ads returned.\",\n    \"2-1\": \"content type of the native ad. It’s either ‘story’ or ‘video’.\",\n    \"3-1\": \"title of the native ad.\",\n    \"4-1\": \"summary part of the native ad.\",\n    \"5-1\": \"URL of the image attached with native ad.\",\n    \"6-1\": \"Returns the IFRAME embed code of a video player, in case the ‘type’ of the ad is ‘video’. This embed code video works on all platforms. For native, platforms it need to be wrapped in a Web View.\",\n    \"7-1\": \"click URL for the whole native ad.\",\n    \"8-1\": \"after click action for the native ad. If it’s ‘_blank’, it should be opened in new window/view. If it’s ‘_parent’ or empty, it should be opened in the same window/view.\",\n    \"9-1\": \"Background color value set in Adsnative Dashboard for the ad unit. This allows you to control the background color of the ad unit from AdsNative Dashboard. You can choose to ignore this value\",\n    \"10-1\": \"URL of the brand image/logo.\",\n    \"11-1\": \"Name of the brand promoting the content.\",\n    \"12-1\": \"Prefix for the brand name configured in AdsNative Dashboard for the current ad unit. For e.g. ‘Promoted by’ or ‘Sponsored by’.\",\n    \"13-1\": \"click URL that needs to be called in case user clicks on either brand name or brand image.\",\n    \"14-1\": \"tags for tracking impression and third-party tracking. These are typically image or script tags that can droppped anywhere in the web page or in case of native platforms, within a 1x1 Web View. If you are looking for an alternative method for your platform, please contact AdsNative team for more options.\",\n    \"15-1\": \"tags for tracking viewability according to MRC50 standards. [Here](http://mediaratingcouncil.org/081815%20Viewable%20Ad%20Impression%20Guideline_v2.0_Final.pdf) is the reference to MRC viewability standards and we expect publishers follow the same standards to track ad viewability.\\n\\nWe also open sourced the JS implementation to track the viewability on web platforms - [https://github.com/picatcha/OpenAdViewability](https://github.com/picatcha/OpenAdViewability) which you can use.\",\n    \"1-0\": \"count\",\n    \"2-0\": \"type\",\n    \"3-0\": \"title\",\n    \"4-0\": \"summary\",\n    \"5-0\": \"imageSrc\",\n    \"6-0\": \"embedUrl\",\n    \"7-0\": \"url\",\n    \"8-0\": \"target\",\n    \"9-0\": \"backgroundColor\",\n    \"10-0\": \"brandImageUrl\",\n    \"11-0\": \"promotedBy\",\n    \"12-0\": \"promotedByTag\",\n    \"13-0\": \"promotedByUrl\",\n    \"14-0\": \"trackingTags\",\n    \"15-0\": \"viewableTags\"\n  },\n  \"cols\": 2,\n  \"rows\": 16\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Cookie Matching\"\n}\n[/block]\nIf the scope of the AdsNative Ad Server usage is limited to direct campaigns then generally there is no requirement to sync user cookies with AdsNative. Publisher can choose to pass uniquely generated ID per user in 'uuid' parameter. If you plan to integrate with various RTB based DSPs with AdsNative then please contact integrations:::at:::adsnative.com to consult about the best possible solution that fits your use case.","excerpt":"Server-side stitching Ads API is used to get ads from your campaigns, and stitch them along with your content","slug":"ads-api-web","type":"endpoint","title":"Ads API (web)"}

getAds API (web)

Server-side stitching Ads API is used to get ads from your campaigns, and stitch them along with your content

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

zid:
required
array of strings
This is the ad placement token that can be found in your dashboard
ip:
required
string
client’s ipaddress to be used for city, region or country targeting
ua:
required
string
client’s user agent
uuid:
required
string
client’s unique identifier to be used for frequency capping. AdsNative will attempt to set a uuid value in a cookie if parameter is not passed.
url:
required
string
In case of desktop and mobile web, it's the current page url where the ad unit is going to be shown, and in case of mobile apps it is the domain value with http. For example, http://example.com
al:
string
client’s accept-language settings (e.g. ‘en-us’) to be used for language specific targeting
kw:
array of strings
keyword targeting
ck_[KEY_NAME]:
array of strings
Pass key name of the key-value pair and corresponding value. Replace [KEY_NAME] with configured 'key' handle name

Examples


Result Format


Documentation

Note: 1. If the API request is made from browser client-side then the params - ua, ip, al and uuid parameters are optional. 2. For parameters of values which are marked as array of string, you can pass multiple values by passing those params multiple times. For example, you can multiple zids to receive response for multiple placements such as ?zid=zone1&zid=zone2. Keywords as ?kw=sports&kw=baseball. Custom key-values as ?ck_tag=sports&ck_tag=baseball. [block:api-header] { "type": "basic", "title": "Response Parameters" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "status", "0-1": "The status of the ad response. Returns ‘OK’ when a valid ad is present.", "1-1": "Number of native ads returned.", "2-1": "content type of the native ad. It’s either ‘story’ or ‘video’.", "3-1": "title of the native ad.", "4-1": "summary part of the native ad.", "5-1": "URL of the image attached with native ad.", "6-1": "Returns the IFRAME embed code of a video player, in case the ‘type’ of the ad is ‘video’. This embed code video works on all platforms. For native, platforms it need to be wrapped in a Web View.", "7-1": "click URL for the whole native ad.", "8-1": "after click action for the native ad. If it’s ‘_blank’, it should be opened in new window/view. If it’s ‘_parent’ or empty, it should be opened in the same window/view.", "9-1": "Background color value set in Adsnative Dashboard for the ad unit. This allows you to control the background color of the ad unit from AdsNative Dashboard. You can choose to ignore this value", "10-1": "URL of the brand image/logo.", "11-1": "Name of the brand promoting the content.", "12-1": "Prefix for the brand name configured in AdsNative Dashboard for the current ad unit. For e.g. ‘Promoted by’ or ‘Sponsored by’.", "13-1": "click URL that needs to be called in case user clicks on either brand name or brand image.", "14-1": "tags for tracking impression and third-party tracking. These are typically image or script tags that can droppped anywhere in the web page or in case of native platforms, within a 1x1 Web View. If you are looking for an alternative method for your platform, please contact AdsNative team for more options.", "15-1": "tags for tracking viewability according to MRC50 standards. [Here](http://mediaratingcouncil.org/081815%20Viewable%20Ad%20Impression%20Guideline_v2.0_Final.pdf) is the reference to MRC viewability standards and we expect publishers follow the same standards to track ad viewability.\n\nWe also open sourced the JS implementation to track the viewability on web platforms - [https://github.com/picatcha/OpenAdViewability](https://github.com/picatcha/OpenAdViewability) which you can use.", "1-0": "count", "2-0": "type", "3-0": "title", "4-0": "summary", "5-0": "imageSrc", "6-0": "embedUrl", "7-0": "url", "8-0": "target", "9-0": "backgroundColor", "10-0": "brandImageUrl", "11-0": "promotedBy", "12-0": "promotedByTag", "13-0": "promotedByUrl", "14-0": "trackingTags", "15-0": "viewableTags" }, "cols": 2, "rows": 16 } [/block] [block:api-header] { "type": "basic", "title": "Cookie Matching" } [/block] If the scope of the AdsNative Ad Server usage is limited to direct campaigns then generally there is no requirement to sync user cookies with AdsNative. Publisher can choose to pass uniquely generated ID per user in 'uuid' parameter. If you plan to integrate with various RTB based DSPs with AdsNative then please contact integrations@adsnative.com to consult about the best possible solution that fits your use case.