ContextAnywhere Web Service

Introduction

The ContextAnywhere Web Service offers a platform for creating innovative Web solutions and services based on Chitika's contextual ad service, accessible with a web services API. With the robust XML interface, you will have access to the more than 500K advertisers in Chitika's "network of networks" system. This web service allows you to incorporate contextual CPC text ads into your application or web solution.

Key Features:

Leave the targeting to us: Our system spiders the page content and does a realtime content analysis. Every ad shown will be relevant to the content being viewed by the user. This leads to higher click through and revenue.
Learn over time: Our behavioral logic kicks in over time and fine tunes the system for what's working and what's not. The system "learns" the collective behaviour of the audience for a given site and then fine tunes its ad selection.
No sales team needed: As a developer, you dont need to create your own ad sales operation. By tapping into Chitika's "network of networks" system, you get access to more than 500K advertisers from over 10 CPC ad networks.
Performance Based: When users click on the CPC text ads, it generates revenue and you get a share.
Downstream affiliates: The system is designed to support downstream affiliates. So if you are an application developer and want to track each of your user's separately, the web service supports this. Your reports will reflect each user's activity.

Programming Guide

The Programming Guide contains overview and conceptual information about how to make requests for ads from the ContextAnywhere Web Service.

The guide will show you how to access services and how to interpret the output that is returned to you. If you have not yet registered as a ContextAnywhere developer and received your client ID, you might want to do that now, so that you can try out the XML examples embedded throughout this documentation.

Making HTTP Requests

This section explains how to use make an HTTP call to make requests to the ContextAnywhere Web Service. HTTP allows you to make calls to ContextAnywhere by passing parameter keys and values in a URL (Uniform Resource Locator). ContextAnywhere returns its response in XML (Extensible Markup Language) format. You can experiment with ContextAnywhere requests and responses using nothing more than a Web browser that is capable of displaying XML documents. Simply enter the ContextAnywhere URL into the browser's address bar, and the browser displays the raw XML response.

The Base URL

The URL for the ContextAnywhere interface is:

http://ca.chitika.net/showads

The interface returns XML formatted data for easier programmatic parsing. It also accepts additional parameters, which allows for account logging, output types etc.

Request Parameters

The base URL is followed by a series of parameters that define the request. Parameters are separated from the base URL and each other by an ampersand (&) character. Each parameter consists of a key and a value, separated from each other by an equals sign (=). Note that parameters and their values are case-sensitive; for example, output=xml works correctly, but Output=Xml produces an error.

The following example shows a simple HTTP request that returns ads for a page http://goldned.tripod.com/:

http://ca.chitika.net/showads?output=xml

&client=[your client ID here]

&url=http%3A%2F%2Fgoldned.tripod.com%2F

The parameters in the example are described below:

client=[your client ID here]

client is required in all ContextAnywhere requests. You must sign up for ContextAnywhere and get a client ID before you can use ContextAnywhere.

url=http%3A%2F%2Fgoldned.tripod.com%2F

url tells ContextAnywhere the page the user is browsing on. This page will be analyzed. In the example, the request asks for ads for the page "http://goldned.tripod.com/".

You may only specify one URL per request. This parameter must be URL-encoded (e.g. URL-encoded space characters (%20). Other non-alphanumeric characters must also be URL-encoded. A very common encoded octet is that of the space character in the US-ASCII set. A space is ASCII value 32 (decimal), 20 (hexadecimal). Therefore, to encode “free email” into the request URL to our servers, you would need to replace the space with “%20”, resulting in “free%20email” as your final encoded string. We recommend that inside the code logic that sends the request to our server, you have a function or routine that that checks all the characters in the mt parameter for alphanumeric validity. If any character is not alphanumeric, it must be replaced with its hexadecimal ASCII value preceded by a percent sign. This is known as “% HEX HEX” notation. You may find reference charts for URL encoding at W3 Schools.

XML Response

The ContextAnywhere interface returns XML formatted data with text ads. Here is a sample XML response. The data enclosed in the XML tags is XML encoded. Thus you MUST handle this data as XML and decode it accordingly. Reading the data as text will cause errors and will result in lost revenue and bad user experience. The following is an explanation of the data returned in this XML block:

<realcontext> tag

This is the root node of the XML response.

<accountid> tag

This will usually be blank. It will be non-blank if you have been assigned a separate numeric accountid.

<client> tag

This is the client id assigned to you. It should display your id (or else your account will not be credited for revenue)

<default> tag

This element indicates whether the system had to resort to contingency measures. For example, if the page could not be downloaded.

<ip> tag

The IP address of the end user browsing the page.

<adid> tag

Contains a id of the ad in this XML response.

<bidprice> tag

Contains the Chitika revenue. Your revenue share is a percentage of this amount.

<title> tag

Contains a the title of the advertisement.

<url> tag

Contains the landing URL of the advertisement. This is the URL which the user will eventually land on after being directed to our click URL. It is important that you do not direct your users to this URL as it will not pass through our click counting system, and you will not receive credit for the clicks.

<domain> tag

The domain from the url tag. This is for your convenience (in case you want to display the domain instead of the url).

<description> tag

Contains the description of the advertisement.

<clickurl> tag

Contains the click URL, or the URL you should send users to when they click on one of the advertisements. This URL is a dynamically generated URL that resides on our server cluster and counts the clicks to each advertisement so that you can receive credit for your traffic. You will have to wrap this URL in an HTML href tag to make it clickable. ****The click url should never be altered !

API Reference

This section lists the application programming interface (API) supported by the ContextAnywhere service. There is a sample request to help you get started. Use the sample request as a starting point for developing your own requests. Keep in mind that you should substitute your own client ID into the requests before using them.

Sample Request

http://ca.chitika.net/showads?output=xml

&client=[your client ID here]

&url=[Valid URL]

Request Parameters

The ContextAnywhere service takes the following parameters. Required parameters must be provided for the request to succeed.

NAME	DESCRIPTION	TYPE	VALUE
output	The mime type returned. For ContextAnywhere, this must be set to "xml". The default is html thus it is important to set it to xml if you wish to get xml results.	REQUIRED	xml
client	The client id assigned to you. This is required (or else we wont be able to track your revenue)	REQUIRED	Your Chitika Client ID
url	The URL of the page visited by the user. It is important that the text string is url encoded properly. Please note that if both query and url are set, the query will take precedence.	REQUIRED (unless query below is specified)	Valid URL-encoded URL
query	The query the user is searching for. It is important that the text string is url encoded properly.	OPTIONAL	Valid URL-encoded query string
ip	A text string representing the IP address of the user who initiated the search. *THIS PARAMETER IS NOT THE IP ADDRESS OF YOUR SERVERS.* This is extremely important to include in order for you to receive full credit for all searches and clickthroughs.	REQUIRED	Valid IP Address
numads	An integer value representing the number of ads requested. The default is 2.	OPTIONAL	Valid Integer
type	The type of the page. The system currently supports html and rss. The default is html	OPTIONAL	html
partner	The partner id assigned to you. If you have signed a separate partnership agreement with Chitika, you will be assigned a partner id. By becoming a Chitika partner, you can have users sign up to the Chitika service and get a cut of their revenue. For example, a software developer who creates a blog application that allows users to signup for Chitika ads would have a partner id.	OPTIONAL	Your Chitika Partner ID
sid	3^rd party tracking tag. This tag allows you to specify a 3^rd party tracking id. It is usually used by clients to track their downstream affiliates.	OPTIONAL	Valid URL-encoded string < 16 chars.

Sample Response

The ContextAnywhere interface returns XML formatted data with text ads. Here is a sample XML response.

<?xml version="1.0" encoding="ISO-8859-1"?>
<realcontext>
  <accountid></accountid>
  <client>demo</client>
  <default>false</default>
  <ip>160.79.123.42</ip>
  <records>
    <record>
      <adid>1</adid>
      <bidprice>1.02</bidprice>
      <clickurl>http://ads.chitika.net/track?target=http%3A%2F%2Fsample.com</clickurl>
      <description>Compare prices from over 40,000 stores.  At BizRate.com .. snip .. snip</description>
      <domain>bizrate.com</domain>
      <title>Bridal Gowns: Compare Prices</title>
      <url>http://www.bizrate.com</url>
    </record>
    <record>
      <adid>2</adid>
      <bidprice>1.01</bidprice>
      <clickurl>http://ads.chitika.net/track?target=http%3A%2F%2Fsample</clickurl>
      <description>Save time & money every time you shop online: DealTime is a free .. snip .. snip .. </description>
      <domain>dealtime.com</domain>
      <title>Bridal Gowns Products - Lowest Prices At DealTime!</title>
      <url>http://www.dealtime.com/xKW-bridal gown/NS-1/linkin_id-3028601/GS.html</url>
    </record>
  </records>
</realcontext>

Frequently Asked Questions

What is my revenue share ?

Your share is 60% of the revenue that Chitika earns. The clicks and revenue are available in the online reports.

I have a blog software program. Can I incorporate your ads into the program and have my users sign up with your system ?

Yes. We will assign you a partner id and you will get a cut of any revenue generated via your program. In the web service call, you will have to specify your partner id so that all revenue via your program can be tracked back to you and your account will be credited.

I have proprietary code to create my RSS/Atom feed. Can I use this web service to add text ads ?

Yes. You can either use the html interface that we suport or you can use this web service to add text ads to your feed and/or web page.

Can I cache the XML response ?

No. This XML response should NOT be cached. Each response is unique by IP address and a lot of other factors. Clicks generated from cached responses will be rejected and no revenue will be generated.

What is the partner id for ?

The partner id allows you to create applications in which your application's users can sign up with our service (e.g. A blog software program). By specifying a partner id, any revenue generated from your program will earn you a cut. The exact revenue share varies on a case by case basis depending on the type of application, the traffic and other factors.

Do you support both RSS and Atom formats ?

Yes. Both formats are supported as well as plain html. If the url is a blog feed (like RSS or Atom), you should specify the type as “rss” in the web service call.

I need help. Who can I contact ?

Drop us a mail at info [at] chitika dot com

Give me some ideas. How are others using this service ?

Web applications: A web developer has used this application to integrate ads into his DHTML toolbar.
Desktop applications: A desktop application developer has used the web service to integrate contextual CPC ads into his browser add-on application. Another developer has used the web service to integrate ads into a desktop program that resides in the taskbar.
Blog Plugins: A web developer has used the web service to create plugins for blog software like Movable Type and Wordpress. Using the web service, he has integrated contextual CPC ads into these popular blogging programs.