The Social Digits API

This page contains all the basics of our RESTfull API. This documentation is meant for a technical audience so we expect that you are familiar with web APIs, REST and JSON.

Plugins and language bindings
We strongly recommend that you use our thesocialdigits.js JavaScript library for all front end integration with our API since it both simplifies integration and automatically handles tracking and personalization.

Communication

The Social Digits API is a RESTful API. All communication is done by sending JSON objects as either HTTP POST- or GET-requests. All responses are likewise returned as JSON objects in the response body.

The exact content of the request and response objects are specified by the individual API method documentation.

HTTP POST

POST requests are send by placing the JSON object in the request body. Remember to set the Content-Type header as:

Content-Type: application/json

HTTP GET

GET requests are send by URL encoding the JSON object and send it as the query parameter payload. JSONP is supported by providing the callback functions name as the parameter callback.

Authentication

To use the API you must authenticate yourself. This is done by using your unique API key which you can find under your account settings. The API key must be passed along with each request to our API as specified in the APIs documentation.

Personalization

For personalizing the results of our recommendations or search results to the individual customer you must pass along a unique visitor-ID. This ID must be consistent and unique for the individual customer (eg. a cookie or a hash of the customers IP and user-agent string).

Tip
If the customers browser communicates directly with our servers (eg. if you use our jQuery plugin) we generate the visitor-ID automatically if it is not provided in the request. This is done via advanced finger printing and does thus not rely on cookies while still being a very effective tracking approach. We highly recommend this.

Customer Tracking

To track the impact of our service each request to the API must contain a visitor-ID as described under personalization. All you have to do to fully enable tracking is to make a call to our add_sale API method when the customer has completed an order. This will allow our system to detect which products were recommended by us and will be available in real-time at your administration panel.

To improve tracking even further many APIs allow you to add a label argument. This label will be associated with the result and measurable through the administration panel.

Filtering results

All results can be easily filtered using simple filter queries. If a filter query is sent along with a request only products that passes the filter will be returned. You can filter on any attribute you specify in the data feed.

Filtering is done by comparing a product attribute with a specific value. The following comparison operators can be used:

=, !=, <, >, <=, >=, contains

All the first 6 comparison operators behave as you would expect in any programming language. The last one is for testing membership of a list of values.

Examples

Only return products that are on sale:

sale = 1

Only select products that are on sale and has a rating above 0.5:

sale = 1 and rating > 0.5

Only select products with size medium or from brand 4 that cost less than 30$:

sizes contains 'medium' or (brand = 4 and price < 30)

Errors

All successful requests to the API will have a entry named status in the returned JSON object with the value "ok".

{
    "status": "ok",
    ...
}

If an error occurs during a request (either due to incorrect arguments or an internal error) the API will always return an JSON object with the following entries:

Entry Content
status Will always have the value "error" in case of errors.
type The type of error. See the table below.
message A short description of the error.
id The ID of the error to be used when contacting our tech support.
moreInfo A URL to a error report page providing more detailed information about the error. The report will only be available for 3 days.

Example of an authentication error due to a unknown API key.

{
    "status": "error",
    "type": "AuthenticationError",
    "message": "Incorrect API key",
    "id": 123,
    "moreInfo": http://developers.thesocialdigits.com/error/123
}

Example of a parsing error.

{
    "status": "error",
    "type": "ParsingError",
    "message": "Missing argument: key",
    "id": 456,
    "moreInfo": http://developers.thesocialdigits.com/error/456
}

Example of an internal error.

{
    "status": "error",
    "type": "InternalError",
    "message": "An internal error occurred",
    "id": 789,
    "moreInfo": http://developers.thesocialdigits.com/error/789
}

Here is a table of the current error types. Currently there are four types of errors but more may be added.

Error type Meaning
AuthenticationError You request could not be authenticated. This is caused by an invalid API key or an disabled account.
ParsingError The request is either not valid JSON or some of the parameters are missing or has a wrong type.
LogicalError A type for allot of miscellaneous errors. Often its used to detect restrictions on arguments that can be controlled by syntax alone.
InernalError An unexpected error occurred. These errors are logged internally and manually verified and fixed.

Data types

Since JSON is strongly typed so is all communication with our service. That means that if your product IDs eg. are integers, they must be passed as integers across all API calls. this also means that you are guaranteed to get the expected type back.

All types are specified by you in the data feed.

Below is a description of all types used by our service.

Primitives

Type Value
null The null value is used to indicate the absence of a value. Can only be used if explicitly defined in the documentation.
boolean Can have the value true or false.
int An integer of unlimited size.
float An floating point value.
string A UTF-8 encoded string.

Collections

Type Value
list A array where all the elements have the same type.
dict A dictionary (or associative array) where all keys and values must have the same type.

Special types

Type Value
product_id A unique identifier for a product. Can be either a int or a string but must be consistent throughout all communication with our service.
visitor_id A unique identifier for a visitor. Can be either a int or a string but must be consistent throughout all communication with our service.
customer_id A unique identifier for a customer. Can be either a int or a string but must be consistent throughout all communication with our service.
sale_id A unique identifier for a sale. Can be either a int or a string but must be consistent throughout all communication with our service.
category_id A unique identifier for a category. Can be either a int or a string but must be consistent throughout all communication with our service.
api_key A string with your personal API key.
filter A string with a filter expression. Only products where the expression evaluates to true are returned.
language_id A unique identifier for a language. Must be a string of one of the following values: danish, dutch, english, finnish, french, german, italian, norwegian, portuguese, russian, spanish or swedish.
status A string indicating the status of the request. It has the value ok if the request executed as planned else error if an error occurred.
strength A string having one of the values: strong, medium or weak.
timestamp A unix timestamp as a int.

Measuring API usage

The usage of the API is measured in results rather than hits. This slightly more complicated measurements makes it possible for a more diverse API usage.

The number of results returned in a request is defined as follows:

  • If the JSON object returned contains a key "result" the request always counts as a single result.
  • If the JSON object returned contains a key "results" the number of result corresponds to the number of entries in the keys corresponding value.
  • All other cases does not count as a result.