API

This document is a write up on Version 2.0 of the Strands API. You can use the API to interact with the Strands Recommender System. The most popular uses are the Behavioral Tracking and Getting Recommendations.

Note: the API is available just for situations where specific integration needs would require its use. The javascript API is the recommended integration mechanism and should be considered before moving forward with a direct or hybrid API integration.


Capturing User Behavior

API Recommendations

E-Mail Integrations

User Profiles & Personalization

>Back to top

 

Capturing User Behavior

Once we have imported your catalog, the Strands Recommender™ can start providing recommendations based on the item properties. But this is not enough to provide a fully personalized experience to your customers.

When provided with information on how your users interact with your system, the recommender can learn and improve the quality of its recommendations over time.

To achieve this a set of common user actions has been defined as the following events that have to be submitted to us as they happen.

>Back to top

 

Tracking via Web-Services

The following set of calls provide the recommender with information about relevant activities carried out by the site users. Note that all parameter names are lowercase and that unless otherwise requested no response will be returned.

>Back to top

 


Item visited

  1. Description: Send this whenever an item page is visited by a user
  2. URL: http://bizsolutions.strands.com/api2/event/visited.sbs
  3. Parameters:
    • apid (required). The API ID from your account page in the dashboard
    • item (requried). The unique identifier for the item
    • user (requried). The identifier of the user who has visited the item
    • needresult (optional). Set to “true” if you want to get an XML/JSON response (defaults to false if undefined)
  4. Usage example:
    http://bizsolutions.strands.com/api2/event/visited.sbs?apid=YOUR_APID&item=VISITED_ITEMID&user=VISITING_USERID

>Back to top

 


Recommendation Clicked

  1. Description: Tracks a click on a recommended item. This implies that a recommendation request has been issued in advance using the API and that the clicked item was part of the result set returned by the recommender. Note that certain parameters received together with the recommended item list are required to submit this event.
  2. URL: http://bizsolutions.strands.com/api2/event/clickedrecommendation.sbs
  3. Parameters:
    • apid (required). The API ID from your account page in the dashboard
    • item (required). The unique identifier for the clicked item
    • user (required). The identifier of the user who has clicked on the item.
    • rrq (required). The identifier of the recommendation request issued before and originating the click (parameter reqId received in the recommendation request’s response).
    • tpl (required). The template used in the recommendation request issued before and originating the click (parameter tpl received in the recommendation request’s response).
    • needresult (optional). Set to “true” if you want to get an XML/JSON response (defaults to false if undefined)
  4. Usage example:
    http://bizsolutions.strands.com/api2/event/clickedrecommendation.sbs?apid=YOUR_APID&item=CLICKED_ITEMID&user=CLICKING_USER&rrq=RECREQUEST_ID
    &tpl=REC_TEMPLATE

>Back to top

 


Item added to favorites

  1. Description: Use this whenever an item is added to a favorites list
  2. URL: http://bizsolutions.strands.com/api2/event/addtofavorites.sbs
  3. Input parameters:
    • apid (required). The API ID from your account page in the dashboard
    • item (required). The unique identifier for the item
    • user (required). The user ID that has added the item
    • needresult (optional). Set to “true” if you want to get an XML/JSON response (defaults to false if undefined)
  4. Example:
    http://bizsolutions.strands.com/api2/event/addtofavorites.sbs?apid=YOUR_APID&item=AN_ITEMID&user=SOME_USERID

>Back to top

 


Item added to wishlist

  1. Description: Use this whenever an item is added to a user’s wishlist.
  2. URL: http://bizsolutions.strands.com/api2/event/addwishlist.sbs
  3. Parameters:
    • apid (required). The API ID from your account page in the dashboard
    • item (required). The unique identifier for the item
    • user (required). Your user ID that has added the item to the wishlist
    • needresult (optional). Set to “true” if you want to get an XML/JSON response (defaults to false if undefined)
  4. Example:
    http://bizsolutions.strands.com/api2/event/addwishlist.sbs?apid=YOUR_APID&item=AN_ITEMID&user=SOME_USERID

>Back to top

 


Shopping Cart Updated

  1. Description: Use this whenever the contents of shopping cart change.
  2. URL: http://bizsolutions.strands.com/api2/event/updateshoppingcart.sbs
  3. Input parameters:
    • apid (required). The API ID from your account page in the dashboard.
    • item (required). You must include an item field for each unique item in the cart.
    • user (required). The ID of the user who has added the item to shopping cart
    • needresult (optional). Set to “true” if you don’t want to get an XML/JSON response (defaults to false if undefined)
  4. Example:

    http://bizsolutions.strands.com/api2/event/updateshoppingcart.sbs?apid=YOUR_APID&item=FIRST_ITEM_IN_CART&item=SECOND_
    ITEM&item=THIRD_ITEM&user=SOME_USERID

    (Even when adding a 3rd item all are sent for consistency)

>Back to top

 


Item(s) purchased

  1. Description: Send this whenever an order is completed.
  2. URL: http://bizsolutions.strands.com/api2/event/purchased.sbs
  3. Parameters:
    • apid (required). The API ID from your account page in the dashboard.
    • user (required). ID of the user who has purchased the item.
    • orderid (required). Order identifier to group purchased events, that is, items purchased at the same transaction.
    • item (required). Format is itemid::price::quantity. You must include an item field for each unique item in the order. Price means the price of a single item, using “.” as the decimal separator. Item Id, price and quantity are all required fields.
    • currency (optional). Choose between “USD”, “GBP”, “EUR”, “YEN”, “CAD”.
    • needresult (optional). Set to “true” if you don’t want to get an XML/JSON response (defaults to false if undefined)
  4. Example:
    http://bizsolutions.strands.com/api2/event/purchased.sbs?apid=YOUR_APID&item=ITEM1_ID%3A%3A10.0%3A%3A2&item=ITEM2_ID%3A%3A25.0%3A%3A1&
    currency=USD&user=SOME_USERID&orderid=SOME_ORDER_IDENTIFIER

>Back to top

 


Content searched

  1. Description: Send this whenever a search result is clicked.
  2. URL: http://bizsolutions.strands.com/api2/event/searched.sbs
  3. Input parameters:
    • apid (required). The API ID from your account page in the dashboard.
    • searchstring (required). String searched by the user
    • user (required). The ID of the user that made the search
    • item (required). The unique identifier for the clicked item
    • language (optional). The language/locale for the string
    • needresult (optional). Set to “true” if you don’t want to get an XML/JSON response (defaults to false if undefined)
  4. Example:
    http://bizsolutions.strands.com/api2/event/searched.sbs?apid=YOUR_APID&item=ITEM_CLICKED&user=RESEARCHER&searchstring=Where%20am%20I

>Back to top

 


User logged

  1. Description: Informs the recommender about a login event in order to link his previous anonymous actions to the right user profile. A complete description of how to use this event is here.
  2. URL: http://bizsolutions.strands.com/api2/event/userlogged.sbs
  3. Input parameters:
    • apid (required). The API ID from your account page in the dashboard
    • user (required). The logged user ID
    • olduser (required). The anonymous user ID used before the login
    • needresult (optional). Set to “true” if you don’t want to get an XML/JSON response (defaults to false if undefined)
  4. Example:
    http://bizsolutions.strands.com/api2/event/userlogged.sbs?apid=YOUR_APID&user=LOGGED_USERID&olduser=PREV_ANON_USERID

>Back to top

 

Tracking Response Format

An empty message body is returned for tracking calls by default in order to speed them up.

But if you are interested in monitoring the process a response can be triggered by setting the “needresult” parameter to “true” in the request URL.

This response will consist of an error code and a description of its meaning.

  1. Generic tracking URL:
    http://bizsolutions.strands.com/api2/event/{EVENT_NAME}.sbs?{OTHER_PARAMS}&needresult=true
  2. XML Response format:
    <result>
    <code>0</code>
    <description>Event tracked: {EVENT_NAME}</description>
    </result>
  3. JSON Response format:
    {“result”:{“code”:0,”description”:”Event tracked: {EVENT_NAME}”}}

A response code of 0 means success. Error codes are as follows:

  1. 0 – Event tracked
  2. 1 – Error in the request parameters
  3. 2 – Error validating customer’s apid
  4. 3 – Unexpected error

>Back to top

 


API Recommendations

The API lets you retrieve the recommendations directly from your server backend in order to render them before serving the pages to your visitors. The logic behind the recommendations has to be configured beforehand in the dashboard using our wizards, and the resulting template identifier (tpl) needs to be included with each request.


>Back to top

 

Getting item recommendations

  1. Description: Retrieves a list of personalized item recommendations based on (a) the current user’s profile, (b) the input item(s) if provided, and (c) a preconfigured recommender template logic

    Note: The user has to match the one used for tracking; read more on the topic in the user section later on.

  2. URL: http://bizsolutions.strands.com/api2/recs/item/get.sbs
  3. Formats: 3 different formats are offered: XML, JSON and JSONP
  4. Parameters:
    • apid (required). The API ID from your account page in the dashboard.
    • user (required). The ID of the user for whom the recommendations are displayed. It is mandatory to include a user identifier in order to personalize the recommendations. Check the user profile section for further details
    • item (optional). This parameter enables personalised item-item recommendations when provided. One or more item IDs can be specified as the base for the recommendations and the parameter has to be included as many times as different IDs are desired
    • tpl (required). Recommendation Template configuration identifier
    • format (optional). Defaults to XML. Accepted values are xml and json
    • jsoncallback (optional). JSON callback function name. When definded together with the JSON format triggers the JSONP formatting of the response where the jsoncallback function wraps the normal JSON response (returned as the argument to the callback funtion)
    • amount (optional). Desired number of recommendations. If not present the amount returned will be the one specified in the widget look configuration of the template.
    • metadata (optional). Either true or false to decide wether to retrieve the available product metadata together with each product ID. Defaults to true for JSON format and false for XML.
    • explanation (optional). Defaults to false, you can designate true in order to show the single most important reason for why that item was recommended.
    • dfilter (optional). Dynamic filter. This parameter provides the means to further filter the recommendations when the filtering property cannot (or is not desired to) be defined as part of the logic associated to the template. Only items matching the dfilter criteria will be returned.

      Format:

      {catalog_property_name}:{property_value_1};;{property_value_2};;;;{property_value_n}

      Name and value (list) are to be separated by a colon “:” and if more than one possible value is desired for that catalog property, other values can be added separated by double semi-colons “;;” (meaning a logical OR between the property values). If filtering by more than one catalog property is desired, other dfilter parameters can be included to cover this scenario (meaning a logical AND in this case between the different property types).

      A typical use-case would be a recommendation widget for a category page. Instead of creating a single template for each category with a specific filter for the category itself, a single template can be created and the dfilter dynamically set to match the current category.

  5. Examples:

    Normal recs (requested as JSON will include metadata by default):

    http://bizsolutions.strands.com/api2/recs/item/get.sbs?apid=YOUR_API&tpl=HOME_TPL&user=SOME_USER&format=json&item=SOME_ITEM

    Filtering for a category page where shown recs will be either of the category “Bags” or “Accesories” and having gender Female (with default XML format and no metadata):

    http://bizsolutions.strands.com/api2/recs/item/get.sbs?apid=YOUR_API&tpl=CAT_TPL&user=SOME_USER&item=SOME_ITEM&dfilter=XCAT:Bags
    ;;Accesories&dfilter=XGEN:Female

    This last example assumes that “XCAT” and “XGEN” are the way categories and gender are defined in your catalog feed and that “Bags”,”Accesories” and “Female” are valid values for them.

  6. Response format:

    JSON with metadata:

    {“result”:{
    “description”:”Success”,
    “code”:0,
    “reqId”:”12345″,
    “tpl”:”CAT_TPL”,
    “recommendations”:[{
    "metadata":{"name":"x","description":"y","price":1.0,
    "link":"http://www.x.com/y.html",
    "picture":"http://www.x.com/y.jpg",
    "properties":{
    "XCAT":["Bags"],
    “XGEN”:["Female"]
    }},
    “itemId”:”100″
    }]
    }}

    XML with metadata:

    <?xml version=”1.0″ encoding=”UTF-8″?>
    <result>
    <description>Success</description>
    <code>0</code>
    <reqId>787324722</reqId>
    <tpl>tpl-1</tpl>
    <recommendations>
    <recommendation>
    <itemId>1017</itemId>
    <metadata>
    <name>x</name>
    <description>y</description>
    <link>http://www.x.com/y.html</link>
    <picture>http://www.x.com/y.jpg</picture>
    <price>1.0</price>
    <properties>
    <property name=”XCAT”>Bags</property>
    <property name=”XGEN”>Female</property>
    </properties>
    </metadata>
    </recommendation>
    </recommendations>
    </result>

    Error Codes:

    • 0 – Success
    • 1 – Error in the request parameters
    • 2 – Error validating customer’s apid
    • 3 – Unexpected error

Note: some parameters provided in the response to the recommendation request are required in order to sumbit the following clickedrecommendation event (if the API is being used for event submission) whenever it happens. These parameters would be tpl and reqId (together with the same apid and user that triggered the recommendation).

>Back to top

 


Email Recommendations

Mass mailing with included recommendations is possible via a templating system that lets you embed the recommendation code into your mails (both HTML and plain text are supported). The recommendations are generated, displayed and tracked only when the e-mail is finally opened by your customers letting them get the freshest recommendations possible.

The layout of the e-mails can be defined in the Dashboard, and the e-mail templates are offered both from the Dashboard itself and through a web interface intended to be used by third party integrations.

The template contents are to be directly pasted into the email after a preprocessing that replaces a set of placeholders with the required parameter for the personalization of the recommendations:

  • REPLACE_WITH_RECIPIENT_USER_ID: (required) the user id of the mail recipient

As a final note remember that e-mail is not available in all customer plans.

>Back to top

 

Getting available mail templates

  1. Description: Request the list of available templates defined from the dashboard.
  2. URL: http://bizsolutions.strands.com/api2/mail/templates/list.sbs
  3. Format: XML
  4. Parameters:
    • apid (required). The API ID from your account page in the dashboard.
  5. Example:
    http://bizsolutions.strands.com/api2/mail/templates/list.sbs?apid=YOUR_API_ID


    <result>
    <code>0</code>
    <description>Success</description>
    <response>
    <templates>
    <template>
    <name>vertical</name>
    <width>400</width>
    <height>185</height>
    </template>
    <template>
    <name>horizontal</name>
    <width>630</width>
    <height>135</height>
    </template>
    </templates>
    </response>
    </result>

>Back to top

 

Getting a template

  1. Description: Request a particular template.
  2. URL: http://bizsolutions.strands.com/api2/mail/templates/get.sbs
  3. Format: XML
  4. Parameters:
    • apid (required). The API ID from your account page in the dashboard.
    • tpl (required). The template identifier.
    • {any.other.parameter} (optional). Any extra &pname=pvalue tuple appended to the template request will be added to the returned code’s URLs. This can be used to override the default user placeholder or to add more required parameters such as an item, a dfilter or a Google Analytics tracking code.
  5. Example:
    http://bizsolutions.strands.com/api2/mail/templates/get.sbs?apid=YOUR_API_ID&tpl=TEMPLATE_NAME


    <result>
    <code>0</code>
    <template width=”630″ height=”135″>
    <table cellspacing=”0″ cellpadding=”0″ border=”0″>
    <tbody>
    <tr>
    <td style=”padding-right:10px;text-align:center”><a href=”http://bizsolutions.strands.com/api/mail/link.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=0″>
    <img border=”0″ style=”width:50px;height:50px” src=”http://bizsolutions.strands.com/api/mail/img.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=0″ /></a><br/>
    <a href=”http://bizsolutions.strands.com/api/mail/link.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=0″>
    <img border=”0″ src=”http://bizsolutions.strands.com/api/mail/text.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=0″ alt=”Recommended Item 1″ /></a>
    </td>

    <td style=”padding-right:10px;text-align:center”><a href=”http://bizsolutions.strands.com/api/mail/link.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=1″>
    <img border=”0″ style=”width:50px;height:50px” src=”http://bizsolutions.strands.com/api/mail/img.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=1″ /></a><br/>
    <a href=”http://bizsolutions.strands.com/api/mail/link.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=1″>
    <img border=”0″ src=”http://bizsolutions.strands.com/api/mail/text.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=1″ alt=”Recommended Item 2″ /></a>
    </td>
    <td style=”padding-right:10px;text-align:center”><a href=”http://bizsolutions.strands.com/api/mail/link.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=2″>
    <img border=”0″ style=”width:50px;height:50px” src=”http://bizsolutions.strands.com/api/mail/img.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=2″ /></a><br/>
    <a href=”http://bizsolutions.strands.com/api/mail/link.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=2″>
    <img border=”0″ src=”http://bizsolutions.strands.com/api/mail/text.sbs?apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID&index=2″ alt=”Recommended Item 3″ /></a>
    </td>
    </tr>
    <tr>
    <td colspan=”3″ style=”text-align:center”>
    <a href=”http://recommender.strands.com”><img src=”http://recommender.strands.com/img-new/powered_strands.png” border=”0″/></a>
    </td>
    </tr>
    </tbody>
    </table>
    </template>
    <plaintext>

    You might also want to check these out:

    http://bizsolutions.strands.com/api/mail/link.sbs?index=0&apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID

    http://bizsolutions.strands.com/api/mail/link.sbs?index=1&apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID

    http://bizsolutions.strands.com/api/mail/link.sbs?index=2&apid=1234XYZ&tpl=tpl-mail1&user=REPLACE_WITH_RECIPIENT_USER_ID

    </plaintext>
    </result>

>Back to top

 


User Profiles & Personalization

The “User” Parameter

The main focus of the Strands Social RecommenderTM is to offer your visitors an enhanced personalized experience. That is why all of its functionality needs information about them in the form of the user parameter.

A unique user identifier has to be provided for every customer action to be tracked and for each recommendation request sent. Even in the case of anonymous access to the site a unique identifier has to be assigned to each visitor and to be consistently sent for him (this is usually achieved by storing the identifier in a cookie)

The unique requirement ensures that no anonymous super-user accumulates actions from different individuals (leading to an incorrect linking of likings) and that returning users will get a better experience each time they visit your site.

And for logged customers, the userlogged event enables us to link their previous anonymous browsing behaviour to the real id under which you can also track them.

API user management

When using the Strands Recommender we are trying to track all the user activity that we can. As mentioned above, this can present some challenges when your site has users that are known members ( i.e. people that have signed up ) and unknown members ( first time visitors, returning visitors who have never signed up ). In order to track all activity whether or not the user is known or not, we have to take some special considerations.

  • Assigning an anonymous user id for unregistered users

    When users first comes to your site, you should assign them a unique identification string. A time stamp down to milliseconds is a good idea, but you can add your own as long as its unique to each user. This identification string should persist across multiple sessions, so it’s best to keep it in a cookie that will last for at least a year. Now all activity by that user will be attributed to that unique id. All behavioral actions committed by that user should then use that cookie string.

  • Assigning a logged in user id for newly registered users

    Let’s now assume that a user has decided to become a registered member of your site or that he logs in after a while. When this happens we will now have 2 identifiers for these users : a) the aforementioned user id stored in the anonymous cookie and b) the internal user’s ID in your system. The latter (a registered ID that you understand and that would add meaning to the Strands reports) should be used from now on, as long as the user is known to be logged in for all calls to the Recommender.

    In order to be able to merge these two users into a single profile, you’ll need to perform an extra step and call the userlogged API event each time the user logs into the system. After this action is called, the actions associated to the two identifiers will be merged into the logged one on our side.

  • Anonymous ID versus Session ID

    Some users have made the mistake of trying to re-use an existing Session ID already existing in their system as an Anonymous ID. At a glance this seems like a good idea, but this can lead to lost behavior tracking since Session IDs change so frequently, and ultimately cause incomplete user profiling for that user. So if your system users Session IDs, please avoid re-using them as Anonymous IDs for your non-registered/non-logged in users and do as suggested above for anonymous tracking in such cases.


>Back to top

 


Getting User Actions

  1. Description: Retrieves actions based on historical behaviour.
  2. URL: http://bizsolutions.strands.com/api2/user/activity/get.sbs
  3. Format: XML, JSON
  4. Parameters:
    • apid (required). The API ID from your account page in the dashboard.
    • user (required). The ID of the user whose actons are desired.
    • num (optional). The number of items to be returned. Default value is 5.
    • format (optional). Either XML or JSON. Defaults to XML.
    • type (optional). The event type to restrict the results to. Accepted values, depending on your implementation, are:
      • visited
      • purchased
      • clickedrecommendation
      • addshoppingcart
      • addwishlist
      • mailclicked
      • searched
      • download
      • addtofavorites
  5. Example:
    http://bizsolutions.strands.com/api2/user/activity/get.sbs?apid=YOUR_API_ID&user=YOUR_USER_ID&num=2


    <result>
    <code>0</code>
    <description>Success</description>
    <user>YOUR_USER_ID</user>
    <events>
    <item>
    <productId>192837</productId>
    <timeStamp>2010/04/04 13:16:08 -0700</timeStamp>
    <type>visited</type>
    </item>
    <item>
    <productId>192838</productId>
    <timeStamp>2010/04/03 13:16:38 -0700</timeStamp>
    <type>purchased</type>
    </item>
    </events>
    </result>
  6. The timestamp format is yyyy/mm/dd hh:mm:ss Timezone.

>Back to top