Revcontent API Documentation - Standard Publisher

API Documentation

The Revcontent API enables you to receive the same ad fill you would see in our traditional ad placements in a more flexible format, json or XML. API usage requires Full Advertising Disclosure.

API requests can be in either JSON or XML format.

URI / Endpoint

# Content-Type application/json or text/xml
GET http://trends.revcontent.com/api/v2/



 
Property Type Default Description
api_key string   Your account's assigned API Key.
pub_id integer   Your assigned account ID.
widget_id integer   The ID of the widget associated with this request.
domain string   The URL encoded domain name associated with this widget.
user_ip string Request IP The end user's IP address required because responses are tailored to end users geography. 
If not provided, the request IP is used. If you are calling the API with client-side code, like Javascript, we can detect the user's IP. However, if you are using back-end code, you will have to pass the user's IP.
user_agent string Request User Agent The end user’s user agent is used to report segmented stats based on device type.
If not provided, the request user agent is used. If you are calling the API with client-side code, like Javascript, we can detect the user’s user agent. However, if you are using back-end code, you will have to pass the user’s user agent.
Note: This value must be URL-encoded into valid ASCII format.
referer string empty The end user's URL-encoded webpage URL that the request is being made from.
width integer 1280 The end user's screen width.
img_w integer 420 The default creative image width.
img_h integer 315 The default creative image height.
format string JSON The format of the response.
sponsored_count integer 25 Number of sponsored content items you would like in the response.
sponsored_offset integer 0 The sponsored content item that you would like the response to start from.
internal_count integer 5 Number of internal content items you would like in the response.
internal_offset integer 0 The internal content item that you would like the response to start from.
viewed string empty Should a view be registered for the widget and creatives. See Viewability below.
This tracks viewability on the entire request. For a more detailed viewability, please check below in regards to using the view response pixel to specify which specific creatives trigger viewability.
tracking string auto Manual will NOT record the impression
tracking_method string empty "get" will return the full impression GET URL to be used instead of POST. Only applies if tracking=manual
empty string empty Should an impression be registered for the widget and creatives. See Advanced Usage below.
pick_one string 1 If tracking=manual, pick_one can be passed to collect an impression tracking pixel.
*Properties in red are required


Example
JSON
 
#JSONP var script = document.createElement('script'); script.src = 'http://trends.revcontent.com/api/v2/?api_key=your_api_key&pub_id=111&widget_id=222&domain=yourdomain.com&user_ip=71.100.91.34&referer=www.revcontent.com&format=json&sponsored_count=25&sponsored_offset=0&internal_count=3&internal_offset=2&callback=my_callback&tracking=manual&pick_one=1';; document.body.appendChild(script);
 
 
CURL
 
## Sample cURL call with No Cache-control curl GET -v --cookie "__ID=72a78990b27cffce148fb" -X -H "Cache-Control: no-cache" http://trends.revcontent.com/api/v2/?api_key=your_api_key&pub_id=111&widget_id=222&domain=yourdomain.com
 


Response

The expected response values in the return payload are shown below.

 
Property Description
impression Encoded impression string
headline Content headline
url Content destination URL
image URL of the content image
brand Who is providing the content
content_type Content type: article or video
type Type: sponsored or internal
uid Unique content ID to the system
view URL to hit once the ads on that widget come into view. You will need to append the following variables:
:referer - The page that the ad is on, url encoded.
:p[] - an array of the ads that came into view. Example if the first three ads came into view, you would send us: p[]=0&p[]=1&p[]=2




Example
JSON
 
[ { "impression":"CGX0eStWi7jzeDMY5ovjO5cIxisjGeS5podquxKFp%2FwtGhttHpV3XYWKc1HdMoNOYP3ML6PtQlCtYx7r%2BPJTIjMQRDEppgtmZbaSYdPwwrL1uSGJE2Ud62NA1jAeAueyYH%2BdHfFjctFzyp...", "brand": "Trending Solutions", "headline": "20 Mind-Blowing Facts You Didn't Know", "image": "//img.revcontent.com/?url=https://revcontent-production.s3.amazonaws.com/content/images/1430757674.jpg&pos=face&h=315&w=420", "url": "//trends.revcontent.com/click.php?d=eJwVk8kVxDAIQ1tiMVs5GEz%2FJYSc5mWwsZA%2BRaQQl1ztRMQNj2nKAxGiKOivuueBPbmY8t", "type": "sponsored", "content_type": "article", "uid": "sponsored_248" }, ... ]
 


Viewability
Views must be tracked. A view occurs when a widget 
or new creative comes into the users viewport.

Viewed Parameter
The viewed parameter allows a request to be made that will register a view for the widget and creatives within the limit and offset. Pass viewed=true to track views for a widget and its creatives. Pass empty=true as well if impressions should be ignored. This will track a view for 
entire widget. To record a view for specific widget and/or adset, you will need to use the `view` link parameter that is returned in the response for each widget. The view link parameter accepts 2 additional params (referer, url encoded and an array of which creative spots are viewed: ex first three ads: p[]=0&p[]=1&p[]=2

Advanced Usage
For more advanced implementations widget and creative impressions must be managed. The API provides helper parameters for common use cases.

Empty Parameter
The empty parameter allows a request to be made without registering either widget or creative impressions. Pass empty=true to return a response without registering any impressions.

Fill Parameter and offset rule
Sometimes it is necessary to only register creative impressions while ignoring the widget impression. If either the sponsored_offset or trending_offset is greater than 0 the system will automatically only register creative impressions. This behavior can be forced by using the fill param passing fill=true

Tracking Parameter

Default is auto. If manual is passed, it will NOT record this impression until the impression data is posted back to /v2/track.php passing in field name of “d”. Viewed can be triggered in the passback as well. Passed in a POST or a GET.
d=long_impression_string
viewed=1 or do not send viewed at all.

Impression Tracking
When calling the API using a GET call with tracking parameter set to manual (tracking=manual), you are also able to pass a parameter (pick_one=1). If pick_one is set, content will get a new property attached referred to as “impression”. Users are able to use this as an impression tracking pixel when calling the track..php call. This enables a user to trigger an impression on a certain piece of content. Each content and subsequent click link would be position =1.