HP Gloe API v1

hpgloe.com

In this document we describe the HP Gloe service API. The goal of this document is to
promote mashup services and customized clients to be written on top of Gloe and to
allow syndication of Gloe content. The API also allows native clients to be built for
platforms that Gloe currently does not support. For a general description of Gloe see the
separate An Overview of HP Gloe document.

General Protocol
All APIs support JSONP, that is a callback HTTP GET parameter may be passed and the
result is then the string

callback(json data);

All operations may be called using HTTP GET with the format:
http://www.hpgloe.com/json/operation/?param1=val1&param2=val2 …

Authentication
Most operations can be called without requiring authentication. There are two ways of
authenticating a user, with Facebook Connect, and with the native Gloe authentication
protocol.

To initiate a Facebook Connect login a browser should be opened with the URL:
http://www.hpgloe.com/json/mobilefblogin/
This will direct the user to the Facebook login page and set the cookies in the browser
that are required to link the users’ Facebook account with a corresponding Gloe account.
For first time logins a new Gloe account will be created dynamically/
For more information about Facebook connect see http://developers.facebook.com/connect.php

To login to a native Gloe account (without requiring a Facebook identity) the user must
first register an account using the register operation (see below) to obtain a Gloe
nickname and recommendation key. Authenticated requests must contain a timestamp
parameter with the current time using the time format %Y%m%d%H%M%S,
e.g. 20091231235959. The request must also contain a user parameter with the nickname
of a registered Gloe user. The parameter values must then be signed in alphabetical order
using the HMAC/SHA1 algorithm (See e.g., the Authentication section in
http://docs.amazonwebservices.com/AWSEC2/latest/DeveloperGuide/index.html?using-query-api.html for implementation
details) with the recommendation key. Note Gloe uses the AWS signature version 1
scheme. The difference to v2 are: we don't include the parameter names in the data to
sign, we order by parameter name alphabetically, and we only support SHA1. The

1
signature must then be passed in a signature parameter. All operations apart from the
friend management operations support both authenticated and anonymous users.
Anonymous users should not pass any signature parameter. Anonymous users are
identified by their IP and will have a much stricter quota for making recommendations.

Errors
Errors are returned inside a JSON object with attribute error. Eg.
{“error”: “error string”}
Error Error String
User that tries to authenticate is not found USER_NOT_FOUND
Anonymous access is attempted to operation that AUTHENTICATION_REQUIRED
requires authentication
The signature in the request was not valid AUTHENTICATION_FAILURE
The client IP could not be determined CLIENT_IDENTIFICATION_FAILED
Quota exceeded, no more recommendations QUOTA_EXCEEDED
allowed
Location parameters missing NO_LOCATION
The channel name is not permitted INVALID_CHANNEL
The url is not permitted (must not be an IP and INVALID_URL
must not be blacklisted)
The note text is not permitted INVALID_NOTE
The nickname is not permitted INVALID_NICKNAME
The email is not permitted INVALID_EMAIL
The nickname or email already exists DUPLICATE_NAME_OR_EMAIL
The recommendation was not successful RECOMMENDATION_FAILED

Operations
Parameters that need to be part of the signature apart from user name and timestamp are
marked in red.

Name Parameters Description Output Format Comment

getrec lat - latitude Return JSON array of 10-tuple with elements If filter is not all
(required) recommendations [<rank>,<url>,<title>,<thumburl>,<sampl authentication is
lon - longitude based on a e>,<tags>,<latitude>, <longitude>, required
(required) geolocation and <clicks>,<distance>]
radius – search various filters. thumburl, sample and tags are all deprecated, latitude and
radius Defaults are longitude are averages. All text is in unicode compatible
hits - # result radius: 10 miles URL encoding.
items and hits: 10
tag – channel recommendations
name and no filters.
filter – me,
all, friends
ref - url
reference (used
by notes
attached to web
pages)
q - string to
search for in
title or url

2
rec lat – latitude Recommend and JSON object with attribute message set to If the url parameter
(required) geotag web sites RECOMMENDATION_RECORDED if all went well is used it is a
lon – longitude or comments/notes and attribute quote set to the remaining quota regular
(required) on web sites recommendation
url – url to for an existing site.
recommend If the notes
(required) parameter is used
tags – channel the url of the
to recommend on recommendation
ref – url that will be created
this dynamically and
recommendation hosted on the gloe
is in reference server. If
to click=true the
notes – used recommendation
instead of url does not count
to create notes towards to
title – title of recommendation
recommendation quota and it is not
click - taken into account
true/false when ranking web
sites
register nickname – Registers a new JSON object with message attribute set to An email will be
requested gloe gloe account REGISTRATION_SUCCESS or error attribute set to sent to the
user name DUPLICATE_NAME_OR_EMAIL if nickname or email provided address if
(required) already exists registration
email – email (should be done over https to obtain the recommendation succeeded. The
address of key on the wire in the key attribute) email will contain
account an activation link
(required) and a user id. The
activation link
must be opened in
a browser to
activate the
account. The
nickname and the
user id must be
used to sign
requests that
require
authentication.
friends action – Adds or removes JSON object with attribute message set to Requires
remove/add friends to filter on FRIENDS_UPDATED and friends set to new (space authentication
(required) to a gloe account separated) list of friends if all went well
friends – space
separated list
of friends
getrectag lat – latitude Returns most JSON array of 2-tuple with elements
(required) popular tags in a [<rank>,<tag>]
lon – longitude geolocation
(required)
radius – search
radius
(required)
hits - # result
items (required)
filter -
arbitrary string
to filter
channels on
level - 1/2/...,
number of tag
hierarchies to
search
info friends - Returns current JSON object with attribute quota set to remaining quota Authentication
true/false, quota and friends and attribute friends set to current friends. required
return friends of an authenticated
or not user

3
top lat - latitude Get top JSON object names attribute
(required) contributors in a {"top": [["<id1>", <recs1>],...], provides human
lon - longitude geolocation "names": {"<userid1>": {"LastName": readable names for
(required) "<last name 1>", "FirstName": "<first user ids if
name 1>"}...}}} available

Examples
(URL encoding omitted for readability)
http://www.hpgloe.com/json/getrec/?lat=37.234&lon=-122.234
get all recommendations for geolocation (37.234,-122,234)

http://www.hpgloe.com/json/rec/?lat=37.234&lon=-122.234&url=http://www.hp.com&tags=hp
recommend http://www.hp.com in geolocation (37.234,-122,234) on channel hp

http://www.hpgloe.com/json/register/?nickname=tom&email=tom@example.com
register new user with nickname tom and email tom@example.com

http://www.hpgloe.com/json/friends/?action=add&friends=bob&user=tom&timestamp=20091231235
9&signature=sdfawefawefwefwa
Add bob as a friend to the tom account

http://www.hpgloe.com/json/getrectag/?lat=37.234&lon=-122.234
Get list of most popular channels in geolocation (37.234,-122,234)

http://www.hpgloe.com/json/info/?user=tom&timestamp=20091231235959&signature=dfggergerdrg
erger
Get quota and friend info for user tom

http://www.hpgloe.com/json/top/?lat=37.234&lon=-122.234
Get top contributors in geolocation (37.234,-122,234)