hp gloe api documentation (an hp labs experiment)

A geo-tagging

experiment

from HP Labs

hpgloe.com

API DocumentAtIon

HP GLOE • API DOCUMENTATION • 2

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…

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 [email protected].

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.


operations

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

Return recommendations based on a geolocation and various filters. Defaults are radius: 10 miles and hits: 10 recommendations and no filters.

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.

If filter is not all authentication is required.

rec lat – latitude (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

Recommend and geotag Web sites or comments/notes on Web sites.

JSON object with attribute message set to RECOMMENDATION_RECORDED if all went well and attribute quote set to the remaining quota.

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.

nAme commentoutPut formAtPArAmeters DescrIPtIon

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


register nickname – requested gloe user name (required)

email – email address of account (required)

Registers a new GLOE account.

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).

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.

friends action – remove/add (required)

friends – space separated list of friends

Adds or removes friends to filter on to a GLOE account.

JSON object with attribute message set to FRIENDS_UPDATED and friends set to new (space separated) list of friends if all went well.

Requires authentication.

getrectag lat – latitude (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

Returns most popular tags in a geolocation.

JSON array of 2-tuple with elements [<rank>,<tag>].


operations


info friends – true/false, return friends or not

Returns current quota and friends of an authenticated user.

JSON object with attribute quota set to remaining quota and attribute friends set to current friends.

Authentication required.

top lat – latitude (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.


operations


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

4&lon=-122.234

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

rec/?lat=37.234&lon=-122.234&url=http://www.

hp.com&tags=hp

http://www.hpgloe.com/json/register/?nicknam

e=tom&[email protected]

http://www.hpgloe.com/json/friends/?action=a

dd&friends=bob&user=tom&timestamp=2009123123

59&signature=sdfawefawefwefwa

http://www.hpgloe.com/json/getrectag/?lat=37

.234&lon=-122.234

http://www.hpgloe.com/json/info/?user=tom&ti

mestamp=20091231235959&signature=dfggergerdr

gerger

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

top/?lat=37.234&lon=-122.234

Get all recommendations for geolocation (37.234,-122,234) Recommend http://www.hp.com in geolocation (37.234,-122,234) on channel hp

Register new user with nickname tom and email [email protected]

Add Bob as a friend to the Tom account

Get list of most popular channels in geolocation (37.234,-122,234)

Get quota and friend info for user Tom

Get top contributors in geolocation (37.234,-122,234)

(URL encoding omitted for readability)

exAmPle use

examples


I

Errors are returned inside a JSON object with attribute error. Eg.:

{“error”: “error string”}

User that tries to authenticate is not found

Anonymous access is attempted to operation that requires authentication

The signature in the request was not valid

The client IP could not be determined

Quota exceeded, no more recommendations allowed

Location parameters missing

The channel name is not permitted

The url is not permitted (must not be an IP and must not be blacklisted)

The note text is not permitted

The nickname is not permitted

The email is not permitted

The nickname or email already exists

The recommendation was not successful

USER_NOT_FOUND

AUTHENTICATION_REQUIRED

AUTHENTICATION_FAILURE

CLIENT_IDENTIFICATION_FAILED

QUOTA_EXCEEDED

NO_LOCATION

INVALID_CHANNEL

INVALID_URL

INVALID_NOTE

INVALID_NICKNAME

INVALID_EMAIL

DUPLICATE_NAME_OR_EMAIL

RECOMMENDATION_FAILED

error error strInG

errors

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

hp gloe api documentation (an hp labs experiment)

Documents