Sociocast Core REST API

Purpose

This area is for application developers who want detailed information about the Sociocast REST API, in order to better understand the various methods and/or plan on building custom libraries against the API. This section is targeted for developers who have an understanding of RESTful web services and basic understanding of HTTP request/response frameworks. Additionally, many of the examples utilize cURL and JSON, so knowledge of these two are important. To learn more about Sociocast and/or other relevant topics in this section, we recommend the following links:

• Sociocast Developer Documentation
• General Concepts in Sociocast
• Sociocast Libaries on GitHub
• Simple JSON Overview
• cURL

Authentication

To access the Sociocast REST API you will need your API key and secret (apikey and apisecret). These were provided to you when you signed up for Sociocast and are also available via the Sociocast Console. For entity calls you will also need your client ID (clid), although this is not used for API authentication.

If you do not have a Sociocast account, please sign up on our website.

Sandbox

To access the API in a sandbox environment, use the following URL:

http://api-sandbox.sociocast.com/[API_VERSION]/

The sandbox is a development environment intended for testing the correctness of your API calls. Its predictive capabilities are limited and the data cannot be viewed in the Sociocast Console.

Production

Once you are ready to use the API in a live environment, use the following URL:

http://api.sociocast.com/[API_VERSION]/

The current [API_VERSION] is 1.0.

Signing API Requests

For security reasons, the Sociocast REST API requires that calls to the service be signed. The following parameters must always be included API calls (in addition to any others):

Note that the apisecret is not part of the request - it is used only to generate the sig (see below).

The request is only valid when received at or near the time specified by ts. A +/-5 minute wiggle period is permitted on the Sociocast server on either side of the current timestamp to allow for reasonable clock drift and other delays. Requests received outside this period are denied.

Any request with an invalid signature will receive an HTTP 401 Unauthorized response code. The body is a JSON object with the following values:

An example error response:

{
	"error_status":"401",
	"errors":{"InvalidTimestamp":"Timestamp is outside of allowed range."}
}

Generating the Signature

Each API request must attach a valid signature, the sig parameter, in the query string of the request. The sig value is calculated by generating a SHA-256 digest from:

• The apikey
• The apisecret
• The current timestamp (ts) at which the request is made

The message to be hashed is a parameter string containing the apikey, apisecret, and ts, in that order. Here's a JavaScript implementation using the CryptoJS library to compute the SHA-256 digest:

var message = "apikey=" + key + "&apisecret=" + secret + "&ts=" + timestamp;
var sig = CryptoJS.SHA256(message).toString(CryptoJS.enc.Hex);

Example API Request

The following is an example of a GET /content/profile API request using a timestamp of 1200603038 (Thu, 17 Jan 2008 20:50:38 +0000), an apikey of 2fvmer3qbk7f9jnq and an apisecret of qvxkmw57pec7:

http://api.sociocast.com/1.0/content/profile?url=http://techcrunch.com/&apikey=2fvmer3qbk7f9jnqneg58bu2&sig=6951a4655b27fd657160681b59f5218ff3e47857e4d4ff3310bf24dca0379972&ts=1200603038

Note that url in the above example was a parameter for content profile requests and was not used to calculate the signature.

Overview of REST API Methods

The POST /entity/observe REST API call sends an observation for a specific eid. The call accepts a JSON Object with the following required strings:

As mentioned above, the obs string takes a JSON Object as a value. The following table lists the reserved strings for the obs JSON Object which provide Sociocast clients with additional features and functionality.

In addition to the strings in the table above, you will also need to include statespace keys. Please read the Statespaces overview for how these strings work. In summary, Statespace keys determine the "features" of your predictions. The following table explains the usage of Statespace keys.

In addition to the strings in the table above, the following strings in the table below are reserved keys and should not be used in entity observations, within the obs JSON Object.

{
	"ts":1351819662, 
	"eid":"91ea3bc9-e947-48c1-9546-9b4b187da8c5", 
	"evt":"view", 
	"clid":"C89",
	"obs":
	{
		"url":"http://www.abc.com",
		"band":"Dave Matthews Band",
		"song":"Satellite"		
	} 
}

The POST /entity/attributes REST API call allows you to set, add, and delete attributes for a specific eid. The call accepts a JSON Object with the following required strings:

{
	"clid":"C1",
	"eid":"91ea3bc9-e947-48c1-9546-9b4b187da8c5",
	"eid.owner_name":"John Smith",
	"add":{
		"age":"18 - 34",
		"bluekai_segment":["Auto Intender", "Fashion Buyer"]
	}
}

The POST /entity/profile REST API call allows you to retrieve a profile for an entity. The call accepts a JSON Object with the following required strings:

{
	"eid":"462856674",
	"clid":"C89",
	"humread":true,	
	"attributes":["cls.ctx", "hhi", "eid.appnexusId", "bluekai_segments"]
}

{
	"eid":"462856674",
	"attributes":{
		"cls.ctx":{"Music":0.987,"Fashion":0.654},
		"hhi":["$84,000+"], 
		"eid.appnexusId":"2795629cb47294758438b",
		"bluekai_segments":{"Auto Intender":1,"Travel Intender",1}
	}
}

The GET /content/profile REST API call allows you to retrieve the classification of a URL's content. The profile may contain one or more categories within the Sociocast Taxonomy, along with a confidence score for that category.

Every classification category has both an ID and a human-readable name (both strings). Either can be retrieved with this call, however the IDs are the default; IDs are generally much shorter and therefore more efficient to use.

Typically this call is unnecessary if using entity profiles, as content classifications are also processed for URLs in entity observe calls. However, it is fine to use both if business needs require separate calls.

The API call requires the following URL parameters:

The response depends on whether the URL is in Sociocast's classification cache. As there is a brief delay for URL classification, only cached profiles are immediately retrieved. Otherwise, the first GET call causes the URL to be added to Sociocast's crawling queue and an empty classification will be returned.

The response body of any successful call is a JSON object with the following values:

When (and only when) the URL is in the cache, the HTTP response code will be 200 OK. Here's an example (with human-readable names):

{
 	"url":"http://www.cnn.com/2012/06/26/tech/social-media/facebook-uproar/index.html?hpt=hp_c1"
	"classification":{"Music":0.9856, "Fashion":0.85}
}

When the URL is not in the cache, the HTTP response will be 202 Accepted. The JSON response will be structured as above, but the classification value will always be empty. You should be able to retrieve the URL classification in under two minutes.

Please note that a 202 Accepted response is also returned when the URL classification failed, such as when the contents could not be retrieved. While Sociocast will automatically retry classification of the URL for errors which are frequently transient, it cannot be guaranteed that a 200 OK response will ever be returned for a given URL.

Support or Contact

Having trouble with Sociocast REST API? Contact support@sociocast.com and we’ll help you sort it out.