BittAds: Ad serving made easy

BittAds XML API

For advanced integration with your website or application, an XML API is available.

Note: the XML API is meant for advanced technical solutions.
For normal integration with your website, please log in and visit the tags page in your account.

Authentication

For all interfaces except request ads, you need to authenticate with standard HTTP Basic Authentication. You can use your normal BittAds username (email address) and password for this. If you prefer not to use your normal username and password, you can just create a new user in your network and use that for the XML requests.

Available interfaces

The following XML interfaces are available:

Request ads
List networks/zones/shapes/locations/users
Read ad status

Request ads

Besides using the normal Javascript banner tags, it is also possible to fetch ads through XML. You can then serve them to the user in any way you like.

The BittAds ad server can be queried with an HTTP GET request. The details of the query are expressed as GET parameters. The result will be XML.

The BittAds server can be queried at the following URL:

http://server.bittads.com/ad-xml.ucw

The following GET parameters are required:

instance: The network id. Found on the "Manage Network" page in your account.
zone: The name of the zone.
shape-locs: A JavaScript list of the shape/location pairs that you would like to get ads for.
For example: [["default shape", "frontpage"], ["leaderboard", "forum"]]
confirm-view: Either "yes" or "no". The default is "no".

The following GET parameters are optional:

user-name: The id of the user. This is used to uniquely identify the user, for instance when an ad should not be shown more than once per user per day. If not supplied, an identifier will be generated by the BittAds server. Unless you have a good reason for supplying your own identifier, it is recommended to leave it to BittAds.
keywords: A JavaScript list of the page's relevant keywords. This can be used to target ads only to pages with certain keywords.
For example: ["news", "pop", "the beatles"]
number: Number of ads to be served. Use a number to specify how many ads you want or "all" to get all eligible ads. This option will take all filters into consideration such as zone, shape-locs, keywords and so on.
Note: When using the number parameter only one shape/locs is allowed at a time.
For example: number=10
Another example: number=all

The following URL is a request for an ad to put in the shape 'exampleshape' in the location 'exampleloc', in the zone 'examplezone' and for the network with id '1':

http://server.bittads.com/ad-xml.ucw?instance=1&zone=examplezone&shape-locs=[['exampleshape',
	'exampleloc']]

When the confirm-view parameter is "yes", the view of the ad will not be counted immediately, and for each ad a URL is provided with which to confirm the view. This is useful in situations where you don't know yet, at the time of the request, whether the ad will actually be shown to the user. By requesting the confirm URL, or having the client request it, you confirm that the ad was actually shown. A GET request to the confirm URL will yield a 1-by-1 transparent GIF image. One way, then, to make this request, is to add HTML like this to the page:

<img src="[the confirm url]" style="position: absolute; width: 1px; height: 1px;">

You can also make a POST request to the confirm URL, in which case it will not return the image data.

An example response looks like this:


<?xml version="1.0" encoding="UTF-8"?>  
<ads user-name="1197277102p89642">  
   <ad id="1" shape="example" location="example">  
      &lt;a href='http://www.bittads.com' title='BittAds'  
      target=&quot;_blank&quot;&gt; &lt;img src='http://www.bittads.com/logo.gif'  
      border='0'&gt; &lt;/a&gt;  
   </ad>  
</ads>

When using http://server.bittads.com/ad-xml.ucw to fetch ads, make sure to pass on any cookies that you get from server.bittads.com to the user, and to pass on any cookies starting with "bitt" from the user to server.bittads.com. These cookies are needed for ad options like "show this ad only once per user".

List networks/zones/shapes/locations/users

This interface requires authentication.

For a list of networks that you have access to, do a GET request to:

http://server.bittads.com/xml/networks

An example response looks like this:


<?xml version="1.0" encoding='UTF-8'?>
<networks user="user@example.com">
   <network>1</network>
   <network>3</network>
   <network>152</network>
</networks>

For a list of zones in a network, do a GET request to:

http://server.bittads.com/<network>/xml/zones

An example response looks like this:


<?xml version="1.0" encoding='UTF-8'?>
<zones network="3">
   <zone>
      default zone
   </zone>
   <zone>
      finance
   </zone>
</zones>

For a list of shapes in a network, do a GET request to:

http://server.bittads.com/<network>/xml/shapes

An example response looks like this:


<?xml version="1.0" encoding='UTF-8'?>
<shapes network="3">
   <shape id="1">
      default shape
   </shape>
   <shape id="3">
      leaderboard
   </shape>
</shapes>

For a list of locations in a network, do a GET request to:

http://server.bittads.com/<network>/xml/locations

An example response looks like this:


<?xml version="1.0" encoding='UTF-8'?>
<locations network="3">
   <location id="2">
      default location
   </location>
   <location id="3">
      frontpage-top
   </location>
</locations>

For a list of users that have access to a network, do a GET request to:

http://server.bittads.com/<network>/xml/users

An example response looks like this:


<?xml version="1.0" encoding='UTF-8'?>
<users network="3">
   <user confirmed="true" view="true" create="true" manageUsers="true" manageZones="true">
      alice@example.com
   </user>
   <user confirmed="false" view="true" create="false" manageUsers="false" manageZones="false">
      bob@example.com
   </user>
</users>

The attribute confirmed is false if the user has been invited but has not yet accepted the invitation, and is true otherwise. The remaining attributes specify the user's global permissions.

Read ad status

This interface requires authentication.

It is possible to read the status of a particular ad by doing an HTTP GET request to the ad status URL:

http://admin.bittads.com/<network>/ad/<ad-id>/xml/version/1

Replace <network> with your network id, and <ad-id> with the id of the ad. You can find both by logging into your account and going to the status page of the ad in question. The URL of the status page will look something like http://admin.bittads.com/123/ad/456/status - here 123 is the network id, and 456 is the ad-id.

/version/1 indicates the XML format version used; leave this as it is.

The ad status URL will return XML like this:

<?xml version="1.0" encoding='UTF-8'?>  
<ad id="1" 
    name="demo ad" 
    startTime="2009-09-18T00:00:00+04:00" 
    endTime="2009-09-25T12:00:00+04:00" 
    limitType="unlimited" 
    hurryMode="false" 
    optimizeCreatives="true" 
    archived="false" comment="" 
    serves="2000000" 
    views="2100000" 
    clicks="42000" 
    clients="1500000" 
    ctr="0.02%" 
    clientsRate="0.03%"  
    lastView="2009-10-20T01:31:14+07:00" 
    zones="forum,news" 
    shape="728x90" />

The meaning of the attributes is as follows:

id: The id of the ad.
name: The name of the ad.
startTime: The start date/time of the ad, in ISO 8601 format. If the ad has an unlimited running period, this attribute will be empty.
endTime: The planned end date/time of the ad, in ISO 8601 format. If the ad has an unlimited running period, this attribute will be empty.
limitType: One of the following:
hurryMode: Whether this ad is shown as quickly as possible (true), or spread evenly over time (false).
optimizeCreatives: Whether or not, when the ad has multiple creatives, to show better-performing creatives more often.
archived: Whether or not the ad is archived.
comment: The comment, if any, supplied for this ad in the administration interface.
serves: The number of times the ad has been requested. Note that this is not the same as the number of views: when an ad is requested but the view is not onfirmed by the client (normal Javascript banner tag) or the server (XML API ad request), it will count toward serves but not views. This helps filter out robots nd browsers not capable of displaying the ad.
views: The number of times the ad has been viewed.
clicks: The number of clicks recorded for this ad.
clients: The number of unique clients that have seen this ad.
ctr: The recorded click through rate for this ad (clicks / views). Two decimals of precision.
clientsRate: The click through rate, as a percentage of unique clients (clicks / clients). Two decimals of precision.
lastView: The last time this ad has been viewed by a client.
zones: A semicolon-separated list of the zones that this ad is in.
shape: The shape of the ad.

Help

If you have any questions, just mail us at support@bittads.com – we're always happy to help.

Product Information

Customer support

Contact us

Streamtech B.V.
Loire 128
2491 AJ, The Hague
The Netherlands

Phone: +31 70 31.22.806
Fax: +31 70 31.22.801