{"__v":6,"_id":"5633b5ebc49a7c19001fd091","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":"5625457f23053b2300f596c9","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-10-30T18:24:43.704Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"curl","code":"GET \"http://api.adsnative.com/v1/ad.json?widget_id=home_feed&url=http://example.com&cat=IAB1&network_key=5d73dcf63b2b42598977e36cf5d52d88&ua=Mozilla/5.0%20(Macintosh;%20Intel%20Mac%20OS%20X%2010_10_5)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/46.0.2490.71%20Safari/537.36&ip=73.223.72.169\"","name":null}]},"method":"get","results":{"codes":[{"status":200,"language":"json","code":"{\n    \"status\": \"OK\",\n    \"count\": 1,\n    \"ad\": {\n        \"promotedByUrl\": \"\",\n        \"trackingTags\": \"<img src=\\\"http:\\/\\/bevo.adsnative.com\\/im.gif?sid=d44ec1fa84084b49bf0d8eb368de00c7_6cb3226a\\\" BORDER=0 WIDTH=1 HEIGHT=1>\\n<img src=\\\"https:\\/\\/servedby.flashtalking.com\\/imp\\/3\\/50765;1343244;201;pixel;EDNNetwork;EDNContentHeadline2HowIoTHowIoTAffectsDeviceDesignersandEnergyConsumptionConsiderations\\/?cachebuster=[CACHEBUSTER]\\\">\",\n        \"ctaTitle\": \"Install Now\",\n        \"summary\": \"Learn about the right tools to use when grating and zesting lemons, limes, and oranges.\",\n        \"promotedBy\": \"\",\n        \"target\": \"_blank\",\n        \"title\": \"Test\",\n        \"url\": \"http:\\/\\/bevo.adsnative.com\\/ck?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DgnhnxBOM-pM%26feature%3Dyoutube_gdata&sid=d44ec1fa84084b49bf0d8eb368de00c7_6cb3226a\",\n        \"landingUrl\": \"https:\\/\\/www.youtube.com\\/watch?v=gnhnxBOM-pM&feature=youtube_gdata\",\n        \"ctaUrl\": null,\n        \"viewableTags\": \"<img src=\\\"http:\\/\\/bevo.adsnative.com\\/vi.gif?sid=d44ec1fa84084b49bf0d8eb368de00c7_6cb3226a\\\" BORDER=0 WIDTH=1 HEIGHT=1>\\n\",\n        \"imageSrc\": \"http:\\/\\/cdn.adsnative.com\\/media\\/2\\/ed557b36-cd4c-4068-a532-fc2f5112be12.jpg\",\n        \"promotedByTag\": \"Promoted by\",\n        \"backgroundColor\": \"#FFFFFF\",\n        \"sid\": \"d44ec1fa84084b49bf0d8eb368de00c7_6cb3226a\",\n        \"brandImageUrl\": \"\",\n        \"embedUrl\": \"http:\\/\\/api.adsnative.com\\/v1\\/creative.html?crid=LB9A3D7G&sid=d44ec1fa84084b49bf0d8eb368de00c7_6cb3226a\",\n        \"type\": \"story\"\n    },\n    \"cid\": \"VYBC3HFF\",\n    \"crid\": \"LB9A3D7G\",\n    \"zid\": \"ping\",\n    \"sid\": \"d44ec1fa84084b49bf0d8eb368de00c7\",\n    \"uuid\": \"e6d4bdb0-64e6-4609-a93f-6267d56ea6f4\"\n}","name":""},{"status":500,"language":"json","code":"{\n    \"status\": \"Internal Server Error\",\n    \"code\": \"500\",\n    \"description\": \"Something is broken. We are looking into it!\"\n}","name":""},{"name":"No campaigns found","status":200,"language":"json","code":"{\n    \"status\": \"FAIL\",\n    \"message\": \"no campaigns found\",\n    \"uuid\": \"e3b50f82-f570-44d0-8c17-638059c9edf2\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"5633b64910b6040d00879523","ref":"","in":"query","required":true,"desc":"It's a global key provided AdsNative for your entire network","default":"","type":"string","name":"network_key"},{"_id":"5633b822737ea01700ea3224","ref":"","in":"query","required":true,"desc":"It's a unique id or key assigned by the publisher for that particular placement","default":"","type":"string","name":"widget_id"},{"_id":"5633b822737ea01700ea3223","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":"5633b88927e6531900c117d1","ref":"","in":"query","required":true,"desc":"IAB Category codes for current forum/site. For example “IAB1” for “Arts & Entertainment”.","default":"","type":"array_string","name":"cat"},{"_id":"5633b88927e6531900c117d0","ref":"","in":"query","required":true,"desc":"user agent of the of the client the ad is requested for.","default":"","type":"string","name":"ua"},{"_id":"5633b88927e6531900c117cf","ref":"","in":"query","required":true,"desc":"IP address of the client the ad is requested for","default":"","type":"string","name":"ip"},{"_id":"5633b8df737ea01700ea3225","ref":"","in":"query","required":true,"desc":"Unique user identifier. In case of mobile apps it should be IDFA value.","default":"","type":"string","name":"uuid"},{"_id":"56b8c5c2ddeb231700e6983f","ref":"","in":"query","required":false,"desc":"keyword targeting","default":"","type":"array_string","name":"kw"}],"url":"/ad.json"},"isReference":true,"order":2,"body":"Note: If the API request is made from browser client-side then the params - ua, ip, al and uuid parameters are optional.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Parameters\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"status\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\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    \"1-0\": \"count\",\n    \"2-1\": \"content type of the native ad. It’s either ‘story’ or ‘video’.\",\n    \"3-1\": \"title of the native ad.\",\n    \"2-0\": \"type\",\n    \"3-0\": \"title\",\n    \"4-1\": \"summary part of the native ad.\",\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    \"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-0\": \"viewableTags\",\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  },\n  \"cols\": 2,\n  \"rows\": 16\n}\n[/block]\nNote 1: A unique placement is created at our end for each unique domain (extracted from url) and widget_id combination.\n\nNote 2: The array values should be passed as standard URL parameters with multiple key, value pairs. For example,\n\n&cat=IAB1&cat=IAB2&cat=IAB3\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Cookie/User Sync & Matching\"\n}\n[/block]\nIf the scope of using AdsNative is limited to direct-sold campaigns then there is no requirement to sync users/cookies with AdsNative. Publisher can choose to pass uniquely generated ID per user in 'uuid' parameter. If you plan to integrate with various programmatic partners (RTB based DSPs, other SSPs and Ad Networks) with AdsNative then please contact integrations:::at:::adsnative.com to consult about the best possible solution that fits your use case.","excerpt":"This API is similar to Ads API, but instead of passing individual 'zid' per placement it makes easier for publisher networks to automatically add new placements or sites they may have. This is done mainly using network_key and widget_id. network_key helps identify the entire publisher network and widget_id is any unique placement ID used by the publishers internally to identify the individual ad unit. \n\nThe new placements are created in AdsNative per unique widget_id with the IAB category information passed by the publisher and by extracting domain value from passed current page url.","slug":"enterprise-ads-api","type":"endpoint","title":"Ads API (Dynamic Placement Creation)"}

getAds API (Dynamic Placement Creation)

This API is similar to Ads API, but instead of passing individual 'zid' per placement it makes easier for publisher networks to automatically add new placements or sites they may have. This is done mainly using network_key and widget_id. network_key helps identify the entire publisher network and widget_id is any unique placement ID used by the publishers internally to identify the individual ad unit. The new placements are created in AdsNative per unique widget_id with the IAB category information passed by the publisher and by extracting domain value from passed current page url.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

network_key:
required
string
It's a global key provided AdsNative for your entire network
widget_id:
required
string
It's a unique id or key assigned by the publisher for that particular placement
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
cat:
required
array of strings
IAB Category codes for current forum/site. For example “IAB1” for “Arts & Entertainment”.
ua:
required
string
user agent of the of the client the ad is requested for.
ip:
required
string
IP address of the client the ad is requested for
uuid:
required
string
Unique user identifier. In case of mobile apps it should be IDFA value.
kw:
array of strings
keyword targeting

Examples


Result Format


Documentation

Note: If the API request is made from browser client-side then the params - ua, ip, al and uuid parameters are optional. [block:api-header] { "type": "basic", "title": "Response Parameters" } [/block] [block:parameters] { "data": { "0-0": "status", "h-0": "Parameter", "h-1": "Description", "0-1": "The status of the ad response. Returns ‘OK’ when a valid ad is present.", "1-1": "Number of native ads returned.", "1-0": "count", "2-1": "content type of the native ad. It’s either ‘story’ or ‘video’.", "3-1": "title of the native ad.", "2-0": "type", "3-0": "title", "4-1": "summary part of the native ad.", "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", "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-0": "viewableTags", "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." }, "cols": 2, "rows": 16 } [/block] Note 1: A unique placement is created at our end for each unique domain (extracted from url) and widget_id combination. Note 2: The array values should be passed as standard URL parameters with multiple key, value pairs. For example, &cat=IAB1&cat=IAB2&cat=IAB3 [block:api-header] { "type": "basic", "title": "Cookie/User Sync & Matching" } [/block] If the scope of using AdsNative is limited to direct-sold campaigns then there is no requirement to sync users/cookies with AdsNative. Publisher can choose to pass uniquely generated ID per user in 'uuid' parameter. If you plan to integrate with various programmatic partners (RTB based DSPs, other SSPs and Ad Networks) with AdsNative then please contact integrations@adsnative.com to consult about the best possible solution that fits your use case.