Fork me on GitHub

Welcome to Sociocast on GitHub! Sociocast makes it easy to utilize high-accuracy predictive analytics in your products and applications.

Quick Links

Jump to Authentication »
Jump to REST API Methods »
Jump to POST /entity/observe »
Jump to POST /entity/attributes »
Jump to POST /entity/profile »
Jump to GET /content/profile »

Sociocast Libraries & SDKs

Sociocast JS Library »
Sociocast JS Helper Library »
Sociocast Android Library »
Sociocast iOS Library »

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:

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):

Parameter Value Description
apikey String Your API key, an alphanumeric string assigned to you when you created your Sociocast account.
ts Number The current timestamp at which the request is made, reflecting the number of seconds since Unix Epoch Time (i.e. January 1 1970 00:00:00 GMT).
sig String The signature, a SHA-256 digest generated from the apikey, apisecret, and ts (explained below).

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:

String Value Description
error_status String The HTTP response code (in this case, always "401").
errors Object A list of error IDs with an associoated message (a string).

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 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

POST /entity/observe

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:

String Value Description
eid String The entity ID for the entity.
clid String Your client ID as provided to you by Sociocast. You can also grab this from the Sociocast Console.
ets Long The timestamp when the event took place in Unix Epoch time.
evt String The event type. This can be any arbitrary string (i.e. "view", "search", "click", etc).
obs JSON Object The entity observation, composed of string : value pairs. The string values of this JSON Object can also be of type JSON Array (i.e. multivalued). The entity observation is "what" is being observed for the entity.

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.

String Value Description
url String The URL of the entity observation, if available. Sociocast automatically crawls and classifies all URLs. Once crawled and classified, the classifications will be available in the entity profile via the cls.ctx JSON Object string.
txt String Any body of textual data associated with the entity observation. Sociocast will automatically classify textual data. Once classified, the classifications will be available in the entity profile via the cls.ctx JSON Object string.
revenue Double Revenue associated with the entity observation (i.e. for example an entity purchase an item that costs 99.25 dollars).
url.ua String The User Agent of the HTTP Referrer if available.
clusid JSON Array The list of Cluster IDs into which the entity observation should be placed. For more info, see Clusters.
geo JSON Array The longitude and latitude of the entity observation, if available (i.e. "[51.519682,-109.599609]"). The JSON Array should be of length 2.

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.

String Value Description
{statespace}.id String The unique identifier for the string (for instance, "product.id", "game.id", or "publisher.id"). The value for this string should be the uniquely identifiable ID for the string value (for instance, "'product.id':'12345'").
{statespace}.name String The human-readable name for the string (for instance, "'product.name':'Sony Walkman'"). Additionally, {statespace}.name can accept a Taxonomy (please read Taxonomy overview for how Taxonomies work). For instance, "'product.name':'Music.Players.Sony Walkman'").

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.

String Description
cls.ctx Used internally to hold URL and textual classifications.
cls.atm Used internally to hold classification atoms (i.e. rule-based named entities for the Sociocast classifier).
wgt Used internally to hold the edge weight between two entities.
srchtrms Used internally to hold search terms that are retrieved from the Google referrer URL.
sessid Used internally to mark the entity's session ID for the sequence of entity observations in a particular session.
utm_* The prefix utm is used internally to hold Google UTM keywords which are extracted from referrer URLs.
src Used internally to hold the sources (i.e. source entities in the entity graph) for a particular entity.
snk Used internally to hold the sink (i.e. sink entities in the entity graph) for a particular entity.
ref Used internally to hold the referrer URL from the HTTP header, if available.

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

POST /entity/attributes

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:

String Value Description
eid String The entity ID for the entity.
eid.{secondary} String Any secondary entity ID for the entity. For instance, "'eid.appnexux':'362946cd63956394a'".
clid String Your client ID as provided to you by Sociocast. You can also grab this from the Sociocast Console.
set JSON Object A JSON Object with the string : values of the attributes you would like to set for the eid. The existing string values will be replaced.
add JSON Object A JSON Object with the string : values of the attributes you would like to add for the eid. values will be appended to the existing string within the Sociocast platform.
del JSON Object A JSON Object with the string : values you would like to delete for the eid.

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

POST /entity/profile

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:

String Value Description
eid String The entity ID for the entity.
clid String Your client ID as provided to you by Sociocast. You can also grab this from the Sociocast Console.
attributes JSON Array The attributes you would like to retrieve for the eid.
humread Boolean Whether to retrieve human-readable values for the cls.ctx string (i.e. the Taxonomy). If you send true you will receive human-readable values.

An example entity profile JSON Object may be:
{
	"eid":"462856674",
	"clid":"C89",
	"humread":true,	
	"attributes":["cls.ctx", "hhi", "eid.appnexusId", "bluekai_segments"]
}
The JSON response returns a JSON Object with the eid and attributes strings. Depending on whether the attribute is a statespace string or a regular string, you will get back a JSON Array or JSON Object for the particular attribute string. For instance, the HTTP JSON response for the above entity profile request might look like this:
{
	"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}
	}
}

GET /content/profile

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:

Parameter Value Description
url String The URL for which the profile should be retrieved.
humread Boolean By default, each classification category is represented in the profile by its ID (a String). If you send true you will instead receive the human-readable names.

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:

Name Value Description
url String The URL for which the profile was requested.
classification Object The Sociocast Taxonomy categories (in either human-readable form or by ID) mapped to a number between 0 and 1 which represents the confidence score of the classification. This may be empty.
For example, {"Music":0.9856} represents a confidence score of 98.56% for the Music category.

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.