|Guides API Examples|
|API Basics Communication Authentication Personalization Customer Tracking Filtering results Errors Data Types Measuring API usage CampaignsTargeted campaignsCampaign productsRecommendationsProduct alternativesCurrently watched productsProduct bundlesCategory top productsCustomer related productsPopular productsRelated productsVisitor historyVisitor relatedSearchSearch suggestionsProduct search engineMiscellaneousAdd a productAdd a saleProduct attributesLogs a clickRemove a product||
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
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.
POST requests are send by placing the JSON object in the request body. Remember to set the Content-Type header as:
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.
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.
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).
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.
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.
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:
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.
Only return products that are on sale:
Only select products that are on sale and has a rating above 0.5:
Only select products with size medium or from brand 4 that cost less than 30$:
All successful requests to the API will have a entry named status in the returned JSON object with the value "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:
Example of an authentication error due to a unknown API key.
Example of a parsing error.
Example of an internal error.
Here is a table of the current error types. Currently there are four types of errors but more may be added.
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.
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: