REST API v0.98

From Easyrec Wiki
Jump to: navigation, search

Contents

REST API

The easyrec API is able to receive actions from or send recommendations to your web application in REST style. All user actions sent to easyrec are analyzed by the ruleminer, which runs once a day by default. If significant similarities in user behaviour can be found, recommendations are generated and are accessable instantly using the recommendation web services. The evaluation service of easyrec supports the actions view, buy and rate together with the corresponding recommendation functions otherusersalsoviewed, otherusersalsobought and itemsratedgoodbyotherusers. You can use the API Test Tool for playing around with the API functions.

Note that it is not necessary to upload your item information - all information about your items is collected from the view/buy/rate actions.

The recommendations are calculated with an algorithm for market basket analysis. In order to support quick evaluation, the significance levels are set very low: as soon as two different users perform the same action on the same two items recommendations are generated API

The easyrec API allows you to call methods that respond in XML or JSON. Individual methods are detailed in this document. You can call a method by using an HTTP GET to retrieve XML

 http://localhost:8080/easyrec-web/api/1.0/[method]

along with method specific arguments. Using

 http://localhost:8080/easyrec-web/api/1.0/json/[method]

will return the result in JSON style. Click here for a demonstration on how to use easyrec together with JSON queries.

Every method requires your API Key (8ab9dc3ffcdac576d0f298043a60517a) and a tenantId (e.g. EASYREC_DEMO) as input parameters.

Where applicable, the maximum number of results returned is 15. Import API

To use the Import API, the Security Token (b08f41cfa92b430538146cf474116c6d), which is generated as soon you sign in, has to be used in every Import API call. You can copy the Token form the section on the left under the API key or you can retrieve the Token from

 [webapp path]/operator/signin?operatorId=USER&password=PASSWORD

which returns an xml like

 <?xml version="1.0" encoding="ISO-8859-1"?>
   <easyrec>
   <action>signin</action>
   <success code="105" message="User is signed in!"/>
   <token>b08f41cfa92b430538146cf474116c6d</token>
 </easyrec>

The token is invalidated when you sign out or as soon another user with the same credentials signs in. Note: During an import, make sure no one else signs in under your account, otherwise you will have to update the security token.

Encoding

Use UTF-8 encoding when sending arguments to API methods.

Actions

view

Sample Call

<yourServerURL>/api/1.0/view?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&itemdescription=Fatboy%20Slim%20-%20The%20Rockafeller%20Skank&itemurl=/item/fatboyslim&itemimageurl=/img/covers/fatboyslim.jpg&userid=24EH1723322222A3&sessionid=F3D4E3BE31EE3FA069F5434DB7EC2E34&actiontime=01_01_2009_23_59_59&itemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

sessionid
required

A required session id of a user. (e.g. "F3D4E3BE31EE3FA069F5434DB7EC2E34")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

itemdescription
required

A required item description that is displayed when showing recommendations on your Website. (e.g. "the frog")

itemurl
required

A required item url that links to the item page on your Website.
Note:Please encode &'s in url with %26

userid
optional

An optional anonymised id of a user. (e.g. "24EH1723322222A3")

itemimageurl
optional

An optional item image url that links to a image of the item.
Note:Please encode &'s in url with %26

actiontime
optional; default: the current system time

An optional action time parameter that overwrites the current timestamp of the action. The parameter has the format "dd_MM_yyyy_HH_mm_ss" (e.g."01_01_2009_23_59_59").

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <action>view</action>
  <tenantid>EASYREC_DEMO</tenantid>
  <userid>24EH1723322222A3</userid>
  <sessionid>F3D4E3BE31EE3FA069F5434DB7EC2E34</sessionid>
  <item>      
     <id>42</id>
     <itemType>ITEM</itemType>
     <description>Fatboy Slim - The Rockafeller Skank</description>
     <url>/item/fatboyslim</url>
     <imageurl/>
  </item>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="301" message="Item requires an id!"
code="303" message="Item requires a description!"
code="304" message="Item requires a URL!"
code="401" message="A session id is required!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

buy

This action should be raised if a user buys an item.

Sample Call

<yourServerURL>/api/1.0/buy?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&itemdescription=Fatboy Slim%20-%20The%20Rockafeller%20Skank&itemurl=/item/fatboyslim&itemimageurl=/img/covers/fatboyslim.jpg&userid=24EH1723322222A3&sessionid=F3D4E3BE31EE3FA069F5434DB7EC2E34&actiontime=01_01_2009_23_59_59&itemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

sessionid
required

A required session id of a user. (e.g. "F3D4E3BE31EE3FA069F5434DB7EC2E34")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

itemdescription
required

A required item description that is displayed when showing recommendations on your Website. (e.g. "the frog")

itemurl
required

A required item url that links to the item page on your Website.
Note:Please encode &'s in url with %26

userid
optional

An optional anonymised id of a user. (e.g. "24EH1723322222A3")

itemimageurl
optional

An optional item image url that links to a image of the item.
Note:Please encode &'s in url with %26

actiontime
optional; default: the current system time

An optional action time parameter that overwrites the current timestamp of the action. The parameter has the format "dd_MM_yyyy_HH_mm_ss" (e.g."01_01_2009_23_59_59").

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>buy</action>
  <userid>24EH1723322222A3</userid>
  <sessionid>F3D4E3BE31EE3FA069F5434DB7EC2E34</sessionid>
  <item>      
     <id>42</id>
     <type>ITEM</type>
     <description>Fatboy Slim - The Rockafeller Skank</description>
     <url>/item/fatboyslim</url>
     <imageurl/>
  </item>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="301" message="Item requires an id!"
code="303" message="Item requires a description!"
code="304" message="Item requires a URL!"
code="401" message="A session id is required!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

rate

Action: rate

This action should be raised if a user rates an item.

Sample Call

<yourServerURL>/api/1.0/rate?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&itemdescription=Fatboy Slim%20-%20The Rockafeller%20Skank& itemurl=/item/fatboyslim&itemimageurl=/img/covers/fatboyslim.jpg&userid=24EH1723322222A3&sessionid=F3D4E3BE31EE3FA069F5434DB7EC2E34&ratingvalue=10& actiontime=01_01_2009_23_59_59&itemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

sessionid
required

A required session id of a user. (e.g. "F3D4E3BE31EE3FA069F5434DB7EC2E34")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

ratingvalue
required

A required rating value for the item. The value must be an Integer in the range from 1 to 10. (e.g. 5)

itemdescription
required

A required item description that is displayed when showing recommendations on your Website. (e.g. "the frog")

itemurl
required

A required item url that links to the item page on your Website.
Note:Please encode &'s in url with %26

userid
optional

An optional anonymised id of a user. (e.g. "24EH1723322222A3")

itemimageurl
optional

An optional item image url that links to a image of the item.
Note:Please encode &'s in url with %26

actiontime
optional; default: the current system time

An optional action time parameter that overwrites the current timestamp of the action. The parameter has the format "dd_MM_yyyy_HH_mm_ss" (e.g."01_01_2009_23_59_59").

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>rate</tenantid>
  <action>rate</action>
  <userid>24EH1723322222A3</userid>
  <sessionid>F3D4E3BE31EE3FA069F5434DB7EC2E34</sessionid>
  <item>
     <id>42</id>
     <type>ITEM</type>      
     <description>Fatboy Slim - The Rockafeller Skank</description>
     <ratingValue>10</ratingValue>
     <url>/item/fatboyslim</url>
     <imageurl/>
  </item>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="301" message="Item requires an id!"
code="303" message="Item requires a description!"
code="304" message="Item requires a URL!"
code="305" message="Item requires a valid Rating Value!"
code="401" message="A session id required!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"


sendaction

Action: sendaction

This action can be used to send generic user actions.

Sample Call

<yourServerURL>/api/1.0/sendaction?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&actiontype=PUT_INTO_SHOPPINGCART&itemid=42&itemdescription=Fatboy Slim%20-%20The%20Rockafeller%20Skank&itemurl=/item/fatboyslim&itemimageurl=/img/covers/fatboyslim.jpg&userid=24EH1723322222A3&sessionid=F3D4E3BE31EE3FA069F5434DB7EC2E34&actiontime=01_01_2009_23_59_59&itemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

sessionid
required

A required session id of a user. (e.g. "F3D4E3BE31EE3FA069F5434DB7EC2E34")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

itemdescription
required

A required item description that is displayed when showing recommendations on your Website. (e.g. "the frog")

itemurl
required

A required item url that links to the item page on your Website.
Note:Please encode &'s in url with %26

actiontype
required

A required actiontype you want to use to send. You must create the actiontype in the web interface before you can use it in API calls.

actionvalue
optional

If your actiontype uses actionvalues this parameter is required. It is used to save the actionvalue of your action.

userid
optional

An optional anonymised id of a user. (e.g. "24EH1723322222A3")

itemimageurl
optional

An optional item image url that links to a image of the item.
Note:Please encode &'s in url with %26

actiontime
optional; default: the current system time

An optional action time parameter that overwrites the current timestamp of the action. The parameter has the format "dd_MM_yyyy_HH_mm_ss" (e.g."01_01_2009_23_59_59").

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>rate</tenantid>
  <action>rate</action>
  <userid>24EH1723322222A3</userid>
  <sessionid>F3D4E3BE31EE3FA069F5434DB7EC2E34</sessionid>
  <item>
     <id>42</id>
     <type>ITEM</type>      
     <description>Fatboy Slim - The Rockafeller Skank</description>
     <ratingValue>10</ratingValue>
     <url>/item/fatboyslim</url>
     <imageurl/>
  </item>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="301" message="Item requires an id!"
code="303" message="Item requires a description!"
code="304" message="Item requires a URL!"
code="305" message="Item requires a valid Rating Value!"
code="401" message="A session id required!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

Recommendations

other users also viewed

Users who viewed the specified item also viewed the returned items. At most 15 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/otherusersalsoviewed?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&userid=24EH1723322222A3&itemtype=ITEM&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

userid
optional

An optional anonymised id of a user (e.g. "24EH1723322222A3").
If this parameter is provided items viewed by this user are suppressed.

numberOfResults
optional

An optional parameter to determine the number of results returned.

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.) you are looking for. If not supplied the default value ITEM will be used.

requesteditemtype
optional; default:ITEM

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1.

Example Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>otherUsersAlsoViewed</action>
  <user>
     <id>24EH1723322222A3</id>
  </user>
  <baseitem>
     <item>
       <id>42</id>
       <type>ITEM</type>
       <description>Fatboy Slim - The Rockafeller Skank</description>
       <url>
         /item/fatboyslim
       </url>
       <imageurl/>
     </item>
  </baseitem>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl/>
     </item>
  </recommendeditems>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

other users also bought

Users who bought the specified item also bought the items returned by this method. At most 15 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/otherusersalsobought?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&userid=24EH1723322222A3&itemtype=ITEM&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

userid
optional

An optional anonymised id of a user (e.g. "24EH1723322222A3").
If this parameter is provided items viewed by this user are suppressed.

numberOfResults
optional

An optional parameter to determine the number of results returned.

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

requesteditemtype
optional; default:ITEM

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1. toggle Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>otherUsersAlsoBought</action>
  <user>
     <id>24EH1723322222A3</id>
  </user>   
  <baseitem>
     <item>
       <id>42</id>
       <type>ITEM</type>
       <description>Fatboy Slim - The Rockafeller Skank</description>
       <url>
         /item/fatboyslim
       </url>
       <imageurl/>
     </item>
  </baseitem>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl/>
     </item>
  </recommendeditems>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

items rated good by other users

Users who rated the specified item 'good' did the same with items returned by this method. At most 15 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/itemsratedgoodbyotherusers?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&userid=24EH1723322222A3&itemtype=ITEM&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

userid
optional

An optional anonymised id of a user (e.g. "24EH1723322222A3").
If this parameter is provided items viewed by this user are suppressed.

numberOfResults
optional

An optional parameter to determine the number of results returned.

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

requesteditemtype
optional; default:ITEM

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1. toggleExample Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>itemsRatedGoodByOtherUsers</action>
  <user>
     <id>24EH1723322222A3</id>
  </user>
  <baseitem>
     <item>
       <id>42</id>
       <type>ITEM</type>
       <description>Fatboy Slim - The Rockafeller Skank</description>
       <url>
         /item/fatboyslim
       </url>
       <imageurl/>
     </item>
  </baseitem>      
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboyz
        </url>
        <imageurl/>
     </item>
  </recommendeditems>
</easyrec>
       

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

recommendations for user

This recommendation shows items for a given user id. The latest items that where viewed by the given user are used to find related items of any association type (also viewed, bought, etc., but also custom assoc type). If a user has no viewing history or the viewed items have no related items an empty list is returned. You might want to display other recommendations like most viewed items or most bought items of the last week to the user instead. At most 15 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/recommendationsforuser?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&userid=24EH1723322222A3&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

userid
required

A required anonymised id of a user. (e.g. "24EH1723322222A3")

numberOfResults
optional

An optional parameter to determine the number of results returned.

requesteditemtype
optional

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items.If not supplied items of all item types are returned.

actiontype
optional; default:VIEW

Allows to define which actions of a user are considered when creating the personalized recommendation. Valid values are: VIEW, RATE, BUY or any other custom action type you created.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>recommendationsForUser</action>
  <user>
     <id>24EH1723322222A3</id>
  </user>  
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl/>
     </item>
  </recommendeditems>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="403" message="No Userd Id given!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

related items

This API is used to return rules generated by easyrec Plugins. At most 15 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/relateditems?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&userid=24EH1723322222A3&itemtype=ITEM&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

numberOfResults
optional

An optional parameter to determine the number of results returned.

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

assoctype
optional; default:IS_RELATED

An optional assoc type that denotes the type of recommendation (e.g. BOUGHT_TOGETHER , GOOD_RATED_TOGETHER , etc.) you want to retrieve. If not supplied the default value IS_RELATED will be used.

requesteditemtype
optional; default:ITEM

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1.

Example Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>relatedItems</action>
  <user>
     <id>24EH1723322222A3</id>
  </user>
  <baseitem>
     <item>
       <id>42</id>
       <type>ITEM</type>
       <description>Fatboy Slim - The Rockafeller Skank</description>
       <url>
         /item/fatboyslim
       </url>
       <imageurl/>
     </item>
  </baseitem>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl/>
     </item>
  </recommendeditems>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="No user ID given!"
code="912" message="Operation failed! actionType XXX not found for tenant YYY"

action history for user

This API is used to return the last actions performed by a user and can be used to present a browsing history for a user in a store.

Sample Call

<yourServerURL>api/1.0/actionhistoryforuser?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&userid=24EH1723322222A3

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

userid
required

A requried user id to identify a user of your Website. (e.g. "ID001")

numberOfResults
optional

An optional parameter to determine the number of results returned.

requesteditemtype
optional

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied items of all types are returned.

actiontype
optional;Default=VIEW

An optional type of the actions e.g. VIEW, BUY, RATE, etc.) the user performed on the returned items. If not supplied the history of viewing actions is returned.

XML Response

The response format is in XML endcoded in ISO-8859-1.

Example Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>actionhistory</action>
  <user>
     <id>24EH1723322222A3</id>
  </user>
  <baseitem>
     <item>
       <id>42</id>
       <type>ITEM</type>
       <description>Fatboy Slim - The Rockafeller Skank</description>
       <url>
         /item/fatboyslim
       </url>
       <imageurl/>
     </item>
  </baseitem>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <url>
          /item/beastieboys
        </url>
        <imageurl/>
     </item>
  </recommendeditems>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

Item Type

item types

If you want to load all item types of your tenant you can use the following API call

Sample Call

<yourServerURL>/api/1.0/itemtypes?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

XML Response

The response format is in XML endcoded in ISO-8859-1. The <value>-tag indicates how often an item was viewed. Example Response

<easyrec>
   <tenantId>EASYREC_DEMO</tenantId>
   <itemTypes>
       <itemType>FISHING_UTILITIES</itemType>
       <itemType>DVD</itemType>
       <itemType>BOOKS</itemType>
       <itemType>ITEM</itemType>
   </itemTypes>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"
code="701" message="The provided cluster does not exist!"

Cluster

clusters

This API call will return all cluster names of a given tenant.

Sample Call

<yourServerURL>/api/1.0/clusters?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

XML Response

The response format is in XML endcoded in ISO-8859-1. The <value>-tag indicates how often an item was viewed. Example Response

<easyrec>
   <tenantId>EASYREC_DEMO</tenantId>
   <clusters>
       <cluster>
           <description>The root object of every cluster hierarchy. Cannot be removed!</description>
           <name>CLUSTERS</name>
       </cluster>
       <cluster>
           <description/>
           <name>SUMMERSALE2009</name>
       </cluster>
       <cluster>
           <description/>
           <name>SUMMERSALE2010</name>
       </cluster>
       <cluster>
           <description/>
           <name>SUMMERSALE2011</name>
       </cluster>
       <cluster>
           <description/>
           <name>SPORTSPECIAL</name>
       </cluster>
   </clusters>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"
code="701" message="The provided cluster does not exist!"
code="700", message="Cluster id required!"

items of cluster

This API will return all items of a given cluster.

Sample Call

<yourServerURL>/api/1.0/itemsofcluster?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&clusterid=IST

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

clusterid
required

The response will contain the items of the cluster with the required id used here. Note: the clusterid is the name of the cluster.

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

strategy
optional

An optional parameter that allows you to specify a strategy based on which the items are selected from the given cluster. Valid values are RANDOM, NEWEST and BEST.

RANDOM: returns random items that belong to the given cluster
NEWEST: returns the items of a cluster sorted that the items added more recently are at the top of the list
BEST: returns the items with the highest association to the given cluster at the top of the list (Note: currently only useful with plugin generated clusters; items added via the Admin GUI or CSV upload all have the same association to a cluster)

The default strategy is NEWEST.

usefallback
optional

Clusters can be organized in a hierarchical way in the Admin GUI to take the form of a tree. If this usefallback is set to 'true', easyrec tries to traverse the cluster hierarchy and adds items from sibling and parent clusters to the returned recommendation in case the given cluster only has less that 'numberOfResults' matching items.

requesteditemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<easyrec>
   <action>itemsofcluster</action>
   <recommendeditems>
       <item>
           <creationDate>2010-04-26 17:36:21.0</creationDate>
           <description>Fatboyslim - The Rockafeller S</description>
           <imageUrl>http://demo.easyrec.org/img/covers/fatboyslim.jpg</imageUrl>
           <id>42</id>
           <itemType>ITEM</itemType>
           <profileData><profile>
<year>1990</year>
</profile></profileData>
           <url>http://demo.easyrec.org/item/fatboyslim/</url>
       </item>
       <item>
           <creationDate>2010-04-26 17:36:21.0</creationDate>
           <description>Beastie Boys - Intergalac</description>
           <imageUrl>http://demo.easyrec.org/img/covers/beastieboys.jpg</imageUrl>
           <id>43</id>
           <itemType>ITEM</itemType>
           <profileData><profile>
<year>1990</year>
</profile></profileData>
           <url>https://musicexplorer.researchstudio.at/explorer.form?trackid=1756860</url>
       </item>
       <item>
           <creationDate>2010-04-26 17:36:21.0</creationDate>
           <description>Gorillaz - Clint Eastwood rofl</description>
           <imageUrl>http://demo.easyrec.org/img/covers/gorillaz.jpg</imageUrl>
           <id>44</id>
           <itemType>ITEM</itemType>
           <profileData><profile>
<year>1990</year>
</profile></profileData>
           <url>http://musicexplorer.researchstudio.at/explorer.form?trackid=1369718</url>
       </item>
   </recommendeditems>
   <tenantid>EASYREC_DEMO</tenantid>
</easyrec>

createcluster

With this API call you can create a new cluster.

Sample Call

<yourServerURL>/api/1.0/createcluster?token=82d0267a068404cce422d459e0e2281c&tenantid=EASYREC_DEMO&clusterid=comedy&clusterdescription=comedy+movies&clusterparent=movies

Parameters

token
required

The required security token to access this service. This token is only valid for the current session.
Note: The token invalidates, if you sign out.

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

clusterid
required

The cluster ID to identify the cluster. Note: the clusterid is the name of the cluster.

clusterdescription
optional

A short text which describes the cluster.

clusterparent
optional

The cluster ID of the parent cluster. If this parameter is not provided the cluster will be added as child to the root cluster "CLUSTERS".

XML Response

Example Response

<easyrec>
   <action>createcluster</action>
   <success code="750" message="Cluster successfully created!"/>
</easyrec>

Error Response Codes

code="910" message="The provided token is not valid!"
code="700" message="Cluster id required!"
code="799" message="Cannot add cluster at this position! No parent cluster selected!"
code="799" message="Cannot add cluster! Cluster already exists!"
code="799" message="Parent cluster could not be found!"


Community Rankings

most viewed items

This community ranking shows items that were viewed most by all users. 50 items are returned at most, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/mostvieweditems?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&timeRange=ALL&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

timeRange
optional

An optional parameter to determine the time range. This parameter may be set to one of the following values:
• DAY: most viewed items within the last 24 hours.
• WEEK: most viewed items within the last week.
• MONTH: most viewed items within the last month.
• ALL (default): if no value or this value is given, the most viewed items of all time will be shown.

requesteditemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

clusterid
optional

If this parameter is set results are only from the specified cluster. If no cluster is found with the specified id, an empty list is returned.

XML Response

The response format is in XML endcoded in ISO-8859-1. The <value>-tag indicates how often an item was viewed. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>mostViewedItems</action>  
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl>
          /img/covers/beastieboys.jpg
        </imageurl>
        <value>
          111.0
        </value>
     </item>
  </recommendeditems>
</easyrec>
       

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

most bought items

This community ranking shows items that were bought the most. No more than 50 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/mostboughtitems?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&numberOfResults=10&timeRange=ALL&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

timeRange
optional

An optional parameter to determine the time range. This parameter may be set to one of the following values:
• DAY: most viewed items within the last 24 hours.
• WEEK: most viewed items within the last week.
• MONTH: most viewed items within the last month.
• ALL (default): if no value or this value is given, the most viewed items of all time will be shown.

requesteditemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

clusterid
optional

If this parameter is set results are only from the specified cluster. If no cluster is found with the specified id, an empty list is returned.

XML Response

The response format is in XML endcoded in ISO-8859-1. The <value>-tag indicates how often an item was bought. toggleExample Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>mostBoughtItems</action>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl>
          /img/covers/beastieboys.jpg
        </imageurl>
        <value>
          111.0
        </value>
     </item>
  </recommendeditems>
</easyrec>
       

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

most rated items

This community ranking shows items that were rated the most. No more than 50 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>api/1.0/mostrateditems?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&numberOfResults=10&timeRange=ALL&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

timeRange
optional

An optional parameter to determine the time range. This parameter may be set to one of the following values:
• DAY: most viewed items within the last 24 hours.
• WEEK: most viewed items within the last week.
• MONTH: most viewed items within the last month.
• ALL (default): if no value or this value is given, the most viewed items of all time will be shown.

requesteditemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

clusterid
optional

If this parameter is set results are only from the specified cluster. If no cluster is found with the specified id, an empty list is returned.

XML Response

The response format is in XML endcoded in ISO-8859-1. The <value>-tag indicates how often an item was rated. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>mostRatedItems</action>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl>
          /img/covers/beastieboys.jpg
        </imageurl>
        <value>
          111.0
        </value>
     </item>
  </recommendeditems>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

best rated items

This community ranking shows the best rated items. Rating values range from 1 to 10. The ranking only includes items that have an average ranking value greater than 5.5. No more than 50 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/bestrateditems?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&numberOfResults=10&timeRange=ALL&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

timeRange
optional

An optional parameter to determine the time range. This parameter may be set to one of the following values:
• DAY: most viewed items within the last 24 hours.
• WEEK: most viewed items within the last week.
• MONTH: most viewed items within the last month.
• ALL (default): if no value or this value is given, the most viewed items of all time will be shown.

requesteditemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this item is set to true the results contains an additional element 'profileData' containing the item profile.

Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>bestRatedItems</action>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl>
          http://easyrec.org/img/covers/beastieboys.jpg
        </imageurl>
        <value>
          8.7
        </value>
     </item>
  </recommendeditems>
</easyrec>
       

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

worst rated items

This community ranking shows the worst rated items. Rating values range from 1 to 10. The ranking only includes items that have an average ranking value less than 5.5. No more than 50 items are returned, results are sorted by relevance.

Sample Call

<yourServerURL>/api/1.0/worstrateditems?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&numberOfResults=10&timeRange=ALL&requesteditemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

timeRange
optional

An optional parameter to determine the time range. This parameter may be set to one of the following values:
• DAY: most viewed items within the last 24 hours.
• WEEK: most viewed items within the last week.
• MONTH: most viewed items within the last month.
• ALL (default): if no value or this value is given, the most viewed items of all time will be shown.

requesteditemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

withProfile
optional; default:false

If this parameter is set to true the result contains an additional element 'profileData' with the item profile.

XML Response

The response format is in XML endcoded in ISO-8859-1. The <value>-tag shows the average rating value of this item. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <tenantid>EASYREC_DEMO</tenantid>
  <action>worstRatedItems</action>
  <recommendeditems>
     <item>
        <id>43</id>
        <type>ITEM</type>
        <description>Beastie Boys - Intergalactic</description>
        <profileData><profile>
<year>1990</year>
</profile></profileData>
        <url>
          /item/beastieboys
        </url>
        <imageurl>
          /img/covers/beastieboys.jpg
        </imageurl>
        <value>
          8.7
        </value>
     </item>
  </recommendeditems>
</easyrec>
       

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"

Import API

Import rule

This call imports a rule.

A rule is relation between two items. (e.g. item A was viewed together with item B, where 'viewed together' is the assocation type, item A the 'from'-item and item B the 'to'-item). The strength of a relation is set through the association value, which starts from >0.0 (weak relation) to 100 (strongest relation). A set of rules having the same 'from'-item A are called recommendations of item A.

Rules are automatically computed by the ruleminer on a daily basis as soon significant user patterns are identified. In case you want to import your own rules you may query the Import API with the provided security token.

Sample Call

<yourServerURL>/api/1.0/importrule?token=b08f41cfa92b430538146cf474116c6d&tenantid=EASYREC_DEMO&itemfromid=42&itemfromtype=ITEM&itemtoid=42&itemtotype=ITEM&assoctype=VIEWED_TOGETHER&assocvalue=95.443

Parameters

token
required

The required security token ("b08f41cfa92b430538146cf474116c6d") to access this service. This token is only valid for the current session.
Note: The token invalidates, if you sign out.

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemfromid
required

A required base item id for the relation (e.g. "ID001")

itemtoid
required

A required partner item id for the relation (e.g. "ID003")

assocvalue
required

A required association value (0-100) to describe the relation strength between the two items. (e.g. "95.443")

Note:If you want to "delete" an imported rule, simply pass 0.0 as assoc value and the rule will not be shown in any recommendation, as long the ruleminer did not compute the same rule.

If the same rule was computed or imported by different sources the average assoc value is taken. For example: the ruleminer computed a rule between item A and B with an association value of 50. Then a rule for the same two items with an asooc value of 100 is manually imported. The final association strength between the two items will be 75.

assoctype
required

A required association type. This parameter may be set to one of the following values:
• VIEWED_TOGETHER
• BOUGHT_TOGETHER
• GOOD_RATED_TOGETHER
• IS_RELATED

itemfromtype
optional

An optional item type that denotes the type of the base item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

itemtotype
optional

An optional item type that denotes the type of the partner item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <action>importrule</action>
  <tenantid>EASYREC_DEMO</tenantid>      
  <itemfromid>ID001</itemfromid>
  <itemtoid>ID003</itemtoid>
  <assoctype>VIEWED_TOGETHER</assoctype>
  <assocvalue>95.443</assocvalue>
</easyrec>

Error Response Codes

code="910" message="The provided Token is not valid!"
code="214" message="Tenant does not exist!"
code="500" message="ItemFrom Id does not exist!"
code="501" message="ItemTo Id does not exist!"
code="502" message="Association Type does not exist!"
code="503" message="Invalid Assoc Value (use a decimal value between 0-100)!"
code="504" message="ItemFrom Id must differ from ItemTo Id!"

Import/update item

This call imports or updates an item.

Sample Call

<yourServerURL>api/1.0/importitem?token=b08f41cfa92b430538146cf474116c6d&tenantid=EASYREC_DEMO&itemid=42&itemdescription=Fatboy%20Slim%20-%20The%20Rockafeller%20Skank&itemurl=/item/fatboyslim&itemimageurl=/img/covers/fatboyslim.jpg&itemtype=ITEM

Parameters

token
required

The required security token ("b08f41cfa92b430538146cf474116c6d") to access this service. This token is only valid for the current session.
Note: The token invalidates, if you sign out.

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemid
required

A requried item id to identify an item on your Website. (e.g. "ID001")

itemdescription
required

A required item description that is displayed when showing recommendations on your Website. (e.g. "the frog")

itemurl
required

A required item url that links to the item page on your Website.
Note:Please encode &'s in url with %26

itemimageurl
optional

An optional item image url that links to a image of the item.
Note:Please encode &'s in url with %26

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <action>importitem</action>
  <tenantid>EASYREC_DEMO</tenantid>   
  <item>      
     <id>42</id>
     <type>ITEM</type>
     <description>Fatboy Slim - The Rockafeller Skank</description>
     <url>/item/fatboyslim</url>
     <imageurl/>
  </item>
</easyrec>

Error Response Codes

code="910" message="The provided Token is not valid!"
code="214" message="Tenant does not exist!"
code="301" message="Item requires an id!"
code="303" message="Item requires a description!"
code="304" message="Item requires a URL!"

set item active

This call sets an item active or inactive.

Sample Call

<yourServerURL>api/1.0/setitemactive?apikey=8ab9dc3ffcdac576d0f298043a60517a&tenantid=EASYREC_DEMO&itemid=42&active=true&itemtype=ITEM

Parameters

apikey
required

The required API Key to access this service. (e.g. "8ab9dc3ffcdac576d0f298043a60517a")

tenantid
required

The required tenant id to identify your Website. (e.g. "EASYREC_DEMO")

itemid
required

The id of the item you want to activate or deactivate

active
required

This value is used to activate or deactivate an item - set it to true(active)or false(deactivate)

itemtype
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

XML Response

The response format is in XML endcoded in ISO-8859-1. Example Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<easyrec>
  <action>setitemactive:true</action>
  <item>
    <creationDate>2010-06-29 10:45:32.0</creationDate>
    <description>Fatboy Slim - The Rockafeller Skank</description>
    <imageUrl>http://demo.easyrec.org/img/covers/fatboyslim.jpg</imageUrl>
    <id>42</id>
    <url>http://demo.easyrec.org/item/fatboyslim</url>
  </item>
  <tenantid>EASYREC_DEMO</tenantid>
  <style/>
</easyrec>

Error Response Codes

code="299" message="Wrong APIKey/Tenant combination!"
code="300" message="Item does not exist!"
code="301" message="Item requires an id!"
code="308" message="Missing parameter: active (true|false)"
code="912" message="Operation failed! itemType XXX not found for tenant YYY"
Personal tools
Namespaces

Variants
Actions
easyrec documentation
Navigation
Toolbox