|
EasyUtil Recommendation
Service API
The EasyUtil Recommendation Service
can be accessed through REST (Representational State Transfer). You
access the service by making an HTTP request and providing a list of
key-value pairs as parameters. The result comes back in XML format.
The URL and Parameters
The Base URL you should use is in the
email sent to you along with the access key. For this document, we
use the following as example:
http://server1.easyutil.com/recommend.php?
The parameters follow the base URL in
the format of "key=value", seperated by "&".
The key and value are case sensitive.
The AddItem Request
This request adds an owner-item
relationship. The parameters are:
| cid=[Your
access key] |
Provide your access
key through the cid parameter. This identifies your
application or site. |
| operation=AddItem |
Identifies this
operation |
| owner=[Owner
of Item] |
The owner of an item.
The items owned by the same owner under the same tag are
considered to be related to each other. The real meaning of
"owner" in your application is up to you. For
instance, if your application gives recommendation that
"users liked this article also liked those
articles", the "owner" field should mean your
users. The max length for the owner field is 40 bytes. |
| tag=[Tag
for item] |
The tag narrows down
the items related to the owner. The items owned by the same
owner under the same tag are considered to be related to each
other. The max length for the tag field is 40 bytes. |
| item=[Item] |
The item that is
owned by the owner under the tag. The max length for the item
is 100 bytes.
|
The URL for the above request is:
http://server1.easyutil.com/recommend.php?
cid=[Your access key]&
operation=AddItem&
owner=[Owner of Item]&
tag=[tag for item]&
item=[Item]
The parameters have their respective
length limitations (see above table). This web service is supposed
to help you get additional information out of your data, not for
storing your data. If your data currently resides in a database, you
should keep them there, and maybe use your data's primary key or a
combination of the key and data description for these parameters.
You can encrypt your parameters if you don't want them to pass as
clear text.
If the request is successful, the
response is:
|
<?xml
version="1.0" ?>
<Result
xmlns="http://www.easyutil.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.easyutil.com/ls.xsd">
<ResultCode>Success</ResultCode>
</Result>
|
If the request is unsuccessful, the
response is of the same format as above but with a different
ResultCode. The possible ResultCodes are:
| Success |
The request is
successful. |
| ServerMaintenance |
The server is offline
for maintenance. |
| InvalidCid |
The access key is
invalid. |
| InvalidOperation |
The operation is
invalid. |
| InvalidOwner |
Missing owner
parameter. |
| InvalidItem |
Missing item
parameter. |
The GetRelated Request
This request gets a list of items
related to the specified item. The parameters are:
| cid=[Your
access key] |
Provide your access
key through the cid parameter. This identifies your
application or site. |
| operation=GetRelated |
Identifies this
operation |
| item=[Item] |
The item for which we
want to get the related items. The max length for the item
is 100 bytes.
|
The URL for the above request is:
http://server1.easyutil.com/recommend.php?
cid=[Your access key]&
operation=GetRelated&
item=[Item]
If the request is successful, the
response contains a list of related items and their corresponding
weight. The weight gives how many times two items are associated
with each other by being owned by the same owner. The item list is
sorted with the most relevant item (highest weight) appearing first.
The response parameters:
| <ResultCode>Code</ResultCode> |
Result code gives the
status of the request. |
|
<Item>
|
The <Name>
field gives the name of an related item. This is the same name
submitted through AddItem request (the item parameter). The
<Weight> field gives the weight for the relation between
this item and the item we are getting the item list for. |
As an example, suppose there are 3
related items item1, item2, item3, with respect weight 1, 2, 3, the
response would be:
|
<?xml
version="1.0" ?>
<Result
xmlns="http://www.easyutil.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.easyutil.com/ls.xsd">
<ResultCode>Success</ResultCode>
</Result>
|
The possible ResultCodes are:
| Success |
The request is
successful. |
| ServerMaintenance |
The server is offline
for maintenance. |
| InvalidCid |
The access key is
invalid. |
| InvalidOperation |
The operation is
invalid. |
| InvalidItem |
Missing item
parameter. |
If the request is unsuccessful, the
response is
|
<?xml
version="1.0" ?>
<Result
xmlns="http://www.easyutil.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.easyutil.com/ls.xsd">
<ResultCode>[Code]</ResultCode>
</Result>
|
|
Recommendation Service (beta)