The Context Voice API provides a simple RESTful interface with either XML or JSON formatted responses.  This document provides information to developers on how to integrate with the Context Voice API.

We aimed the API to be very straightforward and to make your job as easy as possible:

You can GET reactions for a specific URL. We keep track of the hottest stories by monitoring the Twitter, Digg, Reddit (and many other services) flows. But if we don’t have it in our database you can add it with a simple POST call. That’s it. Simple huh?

Concepts

Authentication

We support both authenticated and non-authenticated calls. For more info read the Authentication page.

HTTP Requests

The Context Voice API uses a RESTful calling style that works with standard HTTP GET calls.  (Future versions of the Context Voice API will use additional HTTP methods.)  Any web programming language (PHP, Ruby, Perl, Python, Java...) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.

HTTP Status Codes

The Context Voice API uses standard HTTP status codes to indicate success or failure of API calls.  Consult the documentation for your programming language to learn how the read the status code of an HTTP call.  See the section Standard Response Codes for a description of the codes used and their meaning.

Rate Limiting

Right now we limit queries to 5,000 per day, per API key, max 2 queries/sec

You will receive an automated email when you approach your daily limit.  If your application needs more than the allotted amount of calls, contact us at hello@contextvoice.com with a description of the application and an estimate on call usage.  (You might also want to investigate the use of caching to keep the number of calls to a minimum, and make your application more responsive.)

Encoding

The API is RESTful offering two types of response formats: XML and JSON. The default response format is XML.

How to Make A Request And Process The Response

How to Make A Request And Process The Response

Here's a step-by-step example of how to make a request to the Context Voice API.  We'll try to get reactions for a fictional URL say http://www.yourblog.com/your-blogpost.htm

Example Request

You should use a GET method to get the data.

Every Context Voice API request begins with the base URL:

http://api.contextvoice.com/1.2

and ends with the URI for the command.  The part of the URI that reads {URL} is an embedded parameter—you'll need to substitute that with http://www.yourblog.com/your-blogpost.htm

Finally, you'll add a question mark ("?") plus any optional parameters you'd like to send, and of course, your API key.  The final request looks like this:

http://api.contextvoice.com/1.2/reactions/?url=http://www.yourblog.com/your-blogpost.htm&apikey=<your_API_key>

The request above will return an XML response. For JSON use:

http://api.contextvoice.com/1.2/reactions/?url=http://www.yourblog.com/your-blogpost.htm&apikey=<your_API_key>&format=json

Example Response

The XML response should look like this:

And the JSON response should look like this: