Please note that this feature requires a unique API key and password. Please contact your account representative for more information.
Introduction
Content.ad offers this REST API for a publisher to receive a list of all advertisements that may appear in a widget in either XML or JSON format. Please read the FAQs below before implementing the API.
Implementation FAQ
How often should we call this feed API?
The feed should be called no more than once every 10 minutes to populate a cache. The feed is not designed to be called on every impression. Ads in the Content.ad network are dynamic and can be paused or hit caps throughout the day. Processing in 10 minute intervals will prevent clicks to inactive ads from getting excluded.
What does the performance score indicate?
The performance score is a general guideline to use for optimization, taking into account estimated CTR and CPC. It will not accurately predict relative performance across all networks and should only be used as a guide.
What is the difference between the “ClickURL” and the “LandingPage” parameters?
The “ClickURL” value is where the end user should be directed when clicking on an ad. The “Landing Page” value is a clean URL for internal use, such as spidering or semantic analysis.
What are the "ContentRating" values?
The higher the value, the more restrictive the rating. The values we use are: 10 = G, 20 = PG, 30 = PG-13, 40 = R
What are the "Aggressiveness" values?
Similar to “ContentRating”, but specific to the aggressiveness of the image. The values we use are: 10 = None, 20 = Low, 40 = High
What are tags for?
Content.ad tags are separated into two types: categories and excludes (in that order). Categories are based on IAB standards with some differences to better match the Content.ad network. Excludes are subjects that networks commonly restrict to certain contexts. Topics and demographics are deprecated. Not all ads have every type of tag. A list of all Content.ad tags can be found here.
What are the "ContentType" values?
Noncommercial = links to content that does not have obvious commercial intent.
Advertorial = links to a sponsored article that is not hosted by the product's advertiser.
Advertisement = links directly to an advertiser landing page.
Can we pass user, click or publisher information to Content.ad for reporting?
You can add query string parameters named “clientid” and “clientid2” to a ClickURL with any string values you like (up to 64 characters). Please contact support if you need raw click reporting that includes these values.
How can we create different optimization and reporting groups?
CPC optimization takes place on the domain level and is based on the domain ID passed into the feed API call. Reporting is broken out at a widget level and is based on the widget ID provided in the ClickURL. You can create and edit widgets and domains in the Content.ad admin, but you will need to contact your account representative to have them configured properly. All domains must be approved by the Content.ad team before showing sponsored content.
How can we use this feed with multiple widgets?
Each ClickURL in the feed includes the widget GUID for tracking. In order to track multiple widgets using a single API response, you can omit the widget GUID from the call, which will return a [wid] macro in each ClickURL. Simply replace the macro with the desired widget GUID. Important: The wid is a required parameter in the click URL. If omitted or incorrect, Content.ad is unable to track your performance correctly.
Setting Up the API Call
Your account representative will provide you with your domain ID and widget GUID to be placed into the API call below:
https://rest.content.ad/feeds/ad?domainID=[Domain ID]&widgetId=[Widget GUID]Optional Query String Parameters
Example XML Result Set
<Feed xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Count>148</Count>
<Ads>
<Ad>
<ID>123</ID>
<ClickUrl>http://content.ad/click-tracking</ClickUrl>
<LandingPage>http://example.com/interesting-article</LandingPage>
<SponsoredBy>example.com</SponsoredBy>
<ContentType>advertorial</ContentType>
<ContentRating>20</ContentRating>
<Aggressiveness>10</Aggressiveness>
<Targeting>US,CA</Targeting>
<CpcDesktop>0.0198</CpcDesktop>
<CpcMobile>0.0198</CpcMobile>
<CpcTablet>0.0198</CpcTablet>
<PerformanceScore>2.1842</PerformanceScore>
<Summary>If you've been on a cruise before, you know the allure and if you've never been on a cruise, you don't know what you're missing.</Summary>
<Tags>
<Tag>Travel</Tag>
</Tags>
<Variations>
<Variation>
<Title>How Cruise Ships Fill Their Unsold Cabins</Title>
<SmallImage>http://d2o3gnwdwywtvm.cloudfront.net/150x150/vtgwomanwalkinginwater.jpg</SmallImage>
<LargeImage>http://d2o3gnwdwywtvm.cloudfront.net/300x250/vtgwomanwalkinginwater.jpg</LargeImage>
<Weight>16</Weight>
</Variation>
<Variation>
<Title>How Cruise Ships Fill Their Unsold Cabins</Title>
<SmallImage>http://d2o3gnwdwywtvm.cloudfront.net/150x150/vtgredbikinigirl150x150wship.jpg</SmallImage>
<LargeImage>http://d2o3gnwdwywtvm.cloudfront.net/300x250/vtgredbikinigirl150x150wship.jpg</LargeImage>
<Weight>1</Weight>
</Variation>
</Variations>
</Ad>
</Ads>
</Feed>Example JSON Result Set
{
"Count": "1",
"Ads":
[
{
"ClickUrl": "http://content.ad/click-tracking",
"LandingPage": "http://example.com/interesting-article",
"SponsoredBy": "example.com",
"ContentType": "advertorial",
"ContentRating": "20",
"Aggressiveness": "10",
"Targeting": "",
"CpcDesktop": "0.0198",
"CpcMobile": "0.0198",
"CpcTablet": "0.0198",
"PerformanceScore": "2.1842",
"Summary": "If you've been on a cruise before, you know the allure and if you've never been on a cruise, you don't know what you're missing.",
"Tags": ["Travel"],
"Variations":
[
{
"Title": "Interesting Article You May Like",
"SmallImage": "http://example.content.ad/150x150/sample-image-1.jpg",
"LargeImage": "http://example.content.ad/300x250/sample-image-1.jpg",
"Weight": "16"
},
{
"Title": "Interesting Article You May Love",
"SmallImage": "http://example.content.ad/150x150/sample-image-2.jpg",
"LargeImage": "http://example.content.ad/300x250/sample-image-2.jpg",
"Weight": "1"
},
]
}
]
}