e o - ta g ging

API Documentation g
A riment
expe Labs
from HP

hpgloe.com
In this document we describe the
API for the HP Gloe service, a
geo-tagging experiment from HP
Labs. 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, such
as a Firefox extension or iPhone
app. For a general description of
Gloe see the separate HP Gloe
Overview document.
For further information and
technical support, please contact
gloecontact@hp.com.
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 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.
HP GLOE • API DOCUMENTATION • 2
 operations
Name parameters
getrec lat – latitude (required)
lon – longitude (required)
radius – search radius
hits – # result items
tag – channel name
filter – me, all, friends
ref – url reference (used
by notes attached to Web
pages)
q – string to search for in title
or url
rec lat – latitude (required)
lon – longitude (required)
url – url to recommend
(required)
tags – channel to
recommend on
ref – url that this
recommendation is in
reference to
notes – used instead of url to
create notes
title – title of
recommendation
click – true/false
Parameters that need to be part of the signature apart from user
name and timestamp are marked in pink.
description
Return recommendations
based on a geolocation and
various filters. Defaults are
radius: 10 miles and hits:
10 recommendations and
no filters.
Recommend and geotag
Web sites or comments/
notes on Web sites.
Output format
JSON array of 10-tuple with
elements [<rank>,<url>,
<title>,<thumburl>,
<sample>,<tags>,<latitude>,
<longitude>, <clicks>,
<distance>] thumburl, sample
and tags are all deprecated,
latitude and longitude are
averages. All text is in
unicode compatible URL
encoding.
JSON object with
attribute message set to
RECOMMENDATION_
RECORDED if all went well
and attribute quote set to
the remaining quota.
HP GLOE • API DOCUMENTATION • 3
comment
If filter is not all
authentication is required.
If the url parameter is used it
is a regular recommendation
for an existing site. If the
notes parameter is used the
url of the recommendation
will be created dynamically
and hosted on the gloe
server. If click=true the
recommendation does
not count towards to
recommendation quota and
it is not taken into account
when ranking Web sites.
 operations
Name parameters
register nickname – requested gloe
user name (required)
email – email address of
account (required)
friends action – remove/add (required)
friends – space separated list
of friends
getrectag lat – latitude (required)
lon – longitude (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
description
Registers a new gloe
account.
Adds or removes friends to
filter on to a gloe account.
Returns most popular tags in
a geolocation.
Output format
JSON object with message
attribute set to REGISTRATION_
SUCCESS or error attribute
set to DUPLICATE_NAME_
OR_EMAIL if nickname or
email already exists (should be
done over https to obtain the
recommendation key on the
wire in the key attribute).
JSON object with attribute
message set to FRIENDS_
UPDATED and friends set to new
(space separated) list of friends
if all went well.
JSON array of 2-tuple with
elements [<rank>,<tag>].
HP GLOE • API DOCUMENTATION • 4
comment
An email will be sent to
the provided address if
registration succeeded.
The email will contain an
activation link 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.
Requires authentication.
 operations

Name parameters description Output format comment

info friends – true/false, return Returns current quota and JSON object with attribute Authentication required.
friends or not friends of an authenticated quota set to remaining quota
user. and attribute friends set to
current friends.

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

HP GLOE • API DOCUMENTATION • 5

examples

(URL encoding omitted for readability)

Example USE

http://www.hpgloe.com/json/getrec/?lat=37.23 Get all recommendations

4&lon=-122.234 for geolocation (37.234,-
122,234)

http://www.hpgloe.com/json/ Recommend http://www.

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

http://www.hpgloe.com/json/register/?nicknam Register new user with

e=tom&email=tom@example.com nickname tom and email
tom@example.com

http://www.hpgloe.com/json/friends/?action=a Add Bob as a friend to the

dd&friends=bob&user=tom&timestamp=2009123123 Tom account
59&signature=sdfawefawefwefwa

http://www.hpgloe.com/json/getrectag/?lat=37 Get list of most popular

.234&lon=-122.234 channels in geolocation
(37.234,-122,234)

http://www.hpgloe.com/json/info/?user=tom&ti Get quota and friend info

mestamp=20091231235959&signature=dfggergerdr for user Tom
gerger

http://www.hpgloe.com/json/ Get top contributors in

top/?lat=37.234&lon=-122.234 geolocation (37.234,-
122,234)

HP GLOE • API DOCUMENTATION • 6

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 AUTHENTICATION_REQUIRED

that 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 QUOTA_EXCEEDED

recommendations allowed

Location parameters missing NO_LOCATION

The channel name is not permitted INVALID_CHANNEL

The url is not permitted (must not be an INVALID_URL

I and must not be blacklisted)
IP

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

To learn more about HP Labs, visit http://hpl.hp.com.

HP GLOE • API DOCUMENTATION • 7