Developers: Get your API key now!
Specification of IRL API with User API Key
- Add new user
- Get user's API Key
- Get user's friends around radius
- Get user's status
- Status update
- Media
- Move
- Get user's events
- Get user's public events
- Get user's friends events
- Get user's replies events

IRL Connect API Documentation

Developers: Get your API key now!

Send us an e-mail to api@irlconnect.com with the following information:

Name of the application
An e-mail address we should use to contact you regarding the application
A description of your application to users in maximum 90 characters
The web address of your application (or page from which people can download your application)
A logo for your application. We use this when displaying your content on IRL Connect.

We will respond to your request within 48 hours on workdays.

Specification of IRL API with User API Key

Add new user

Creates a new IRL user. A confirmation e-mail will be send to the provided e-mail address. Also a user API key will be created and returned, to be used for authentication of future API calls.

Address:

http://api.irlconnect.com/new_user.json

type=GET, or POST both OK

Parameters

KEY: (required) API key
username : (required) the username of the user, if username already existed, will auto add username1, and if username1 already exists change to username2, etc. And username should be more than 3 characters, 4 or more than 4 characters. And less than 17 characters, 16 or less than 16 characters. Only with A-Za-z0-9_
email: (required) the email of the user
password: (required) the password of the user, And password should be more than 3 characters, 4 or more than 4 characters.
nickname: the nickname of the user, if no nickname provided, then nickname will be the same as username.
avatar: the avatar of the user.
status: the status update message
location: the location of the user

(Note: KEY should be block letter)

The format of location is "Amsterdam, Netherlands"(location name) or "9.86784 23.45663"(lat, lng) or "610000"(zip code).

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
201	Invalid_username	invalid username
202	Invalid_password	invalid password
203	Invalid_email	invalid email
204	Email_taken	email have been taken, please change to another emaill address.

Success

Format:

{success: {message: "User added successfully.", username: "username", userapikey: "userapikey", email :"email ", nickname: "nickname"}}

Need to remember userapikey for later API call.

Get user's API Key

A user API key will be created and returned, to be used for authentication of future API calls.

Address:

http://api.irlconnect.com/get_user_api_key.json

type=GET, or POST both OK

Parameters

KEY: (required) API key
username : (required) the username of the user
password: (required) the password of the user

(Note: KEY should be block letter)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
103	credentials_not_found	the username is not known
104	bad_credentials	the password doesn't match

Success

Format:

{success: {message: "User's ApiKey found.", username: "username", userapikey: "userapikey"}}

Need to remember userapikey for later API call.

Get user's friends around radius

Address:

http://api.irlconnect.com/get_user_friends.json

type=GET, or POST both OK

Parameters

KEY: (required) api key
username : (required) the username of the user
lat: (required) lattitude of the position
lng: (required) longitude of the position
radius: (required) the radius of search friends. The format of radius is a positive integral of radius in meters
showAllIrlUser: (optional) whether return other IrlUser (Default No)
showAllTwitterUser: (optional) whether return other Twitter User (Default No)
showAllFacebookUser: (optional) whether return other Facebook User (Default No)

(Note: KEY should be block letter)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
103	credentials_not_found	the username is not known

Success

Format:

[{"status": "great location for dinner blab la bla", "name": "user name", "avatar": "url", "location":{"lat":"42.34343","lon":"2.4545"}}]

Get user's status

Address:

http://api.irlconnect.com/get_user_info.json

type=GET, or POST both OK

Parameters

KEY: (required) api key
username : (required) the username of the user

(Note: KEY should be block letter)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
103	credentials_not_found	the username is not known

Success

Format:

{"status": "user status", "avatar": "url", "name": "user name", "location":{"lat":"43.5454","lon":"2.3434"}}

Status update

Updates the status message for a specific user.

Address:

http://api.irlconnect.com/status_update.json

type=GET, or POST both OK

Parameters

KEY: (required) API key
userapikey: (required) the user's API Key
status: the status update message
location: the location of the status update

(Note: KEY should be block letter)

The format of location is "Amsterdam, Netherlands"(location name) or "9.86784 23.45663"(lat, lng) or "610000"(zip code)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.
404	bad_credentials	API for this user was disallowed.

Success

Format:

{success: {message: "Status updated successfully"}}

{success: {message: "Status updated successfully, Location updated successfully"}} If the location is found and the location is 2km> from old location.

Media

Creates a media item in the talk stream. This item is clickable and the content will be shown on the map.

Address:

http://api.irlconnect.com/media.json

type=GET, or POST both OK

Parameters

KEY : (required) API key
userapikey: (required) the user's API Key
url: (optional) url of content

html: (optional) html code of the content. Intended for use with video. Should be the embed code of the video player, like (code below is an example of Bambuser):

				<object id="bplayer" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" width="320" height="276"><embed name="bplayer" src="http://bambuser.com/r/player.swf" type="application/x-shockwave-flash" flashvars="[---FLASHVARS---]" width="320" height="276" allowfullscreen="true"></embed><param name="movie" value="http://bambuser.com/r/player.swf"></param><param name="flashvars" value="[--- FLASHVARS---]"></param><param name="allowfullscreen" value="true"></param></object>

content-type: (optional) MIME type of the url file.
title: (required) title/short description of content, for balloon & in talk stream
body: (optional) longer description of content
tracebackurl (optional): URL to the full article of the media. If provided, this url is used in the talk stream as well in the balloon on the map.
location (optional): Location of the media. This location is also used to update the user's location.

(Note: KEY should be block letter)

One of the two parameters, "url" or "html", should be provided.

The format of location was "Amsterdam, Netherlands"(location name) or "9.86784 23.45663"(lat, lng) or "610000"(zip code)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.
404	bad_credentials	API for this user was disallowed.
301	url or html required	url or html required
302	invalid url	invalid url
303	title required	title required
304	invalid html	invalid html

Success

Format:

{success: {message: "Media updated successfully"}}

Or, if a location was provided and the distance between the old and new location is more then 2 km.:

{success: {message: "Media updated successfully, Location updated successfully"}}

Move

Moves a user to a new location.

Address:

http://api.irlconnect.com/move.json

type=GET, or POST both OK

Parameters

KEY : (required) API key
userapikey: (required) the user's API Key
lat: (optional) latitude of the new position
lng: (optional) longitude of the new position
location: (optional) location of the new position

(Note: KEY should be block letter)

The format of location is "Amsterdam, Netherlands"(location name) or "9.86784 23.45663"(lat, lng) or "610000"(zip code)

At least one of the two parameters ("lat lng" and "location") should be provided, else throw a 106 error.

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.
404	bad_credentials	API for this user was disallowed.
106	location required	location required
107	lat and lng required	lat and lng required

Success

Format:

{success: {message: "Location updated successfully."}}

Get user's events

Address:

http://api.irlconnect.com/statuses.json

type=GET, or POST both OK

Parameters

KEY: (required) api key
userapikey: (required) the user's API Key (not required when show = ‘public')
show: the event type want to return, default ‘public'
page: (optional) Specifies the page of results to retrieve (not required and not used when show = ‘public')
count: (optional) Specifies the number of statuses to retrieve. (not required and not used when show = ‘public', default 10).

(Note: KEY should be block letter)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.

Success:

Format:

{"status": "ok", "count": "count of events", "events": [{"originator": "originator ", "type": "EventType", "timestamp": {"ctime": "Fri May 8 09:41:51 2009", "isoformat": "2009-05-08T09:41:51.906000"}, "appversion": "0.9.0.270", "location": {"lat": 60.222831, "lon": 21.372218}, "appid": 1, "message": {"default": "Default message", "key": "irlconnect.event.login"}, "data": {"IrlUser": {"guid": "guid", "name": "nickname"}}}], "timestamp": "2009-05-08T09:41:56.187000", "size": "1"}

Get user's public events

Address:

http://api.irlconnect.com/statuses/public.json

type=GET, or POST both OK

Parameters

KEY: (required) api key

(Note: KEY should be block letter)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages:

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.

Success

Format:

{"status": "ok", "count": "count of events", "events": [{"originator": "originator ", "type": "EventType", "timestamp": {"ctime": "Fri May 8 09:41:51 2009", "isoformat": "2009-05-08T09:41:51.906000"}, "appversion": "0.9.0.270", "location": {"lat": 60.222831, "lon": 21.372218}, "appid": 1, "message": {"default": "Default message", "key": "irlconnect.event.login"}, "data": {"IrlUser": {"guid": "guid", "name": "nickname"}}}], "timestamp": "2009-05-08T09:41:56.187000", "size": "1"}

Get user's friends events

Address:

http://api.irlconnect.com/statuses/friends.json

type=GET, or POST both OK

Parameters

KEY: (required) api key
userapikey: (required) the user's API Key
page: (optional) Specifies the page of results to retrieve
count: (optional) Specifies the number of statuses to retrieve.(default 10).

(Note: KEY should be block letter)

Errors

Format:

		{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.

Success:

Format:

{"status": "ok", "count": "count of events", "events": [{"originator": "originator ", "type": "EventType", "timestamp": {"ctime": "Fri May 8 09:41:51 2009", "isoformat": "2009-05-08T09:41:51.906000"}, "appversion": "0.9.0.270", "location": {"lat": 60.222831, "lon": 21.372218}, "appid": 1, "message": {"default": "Default message", "key": "irlconnect.event.login"}, "data": {"IrlUser": {"guid": "guid", "name": "nickname"}}}], "timestamp": "2009-05-08T09:41:56.187000", "size": "1"}

Get user's replies events

Address:

http://api.irlconnect.com/statuses/replies.json

type=GET, or POST both OK

Parameters

KEY: (required) api key
userapikey: (required) the user's API Key
page: (optional) Specifies the page of results to retrieve
count: (optional) Specifies the number of statuses to retrieve.(default 10).

(Note: KEY should be block letter)

Errors

Format:

{error: {id: int, msg: "string"}}

We support the following error messages

ID	String	Description
100	key_not_valid	The API key is not valid
101	bad_request	The request is invalid, e.g., missing some required fields.
102	internal_error	Internal Error
403	credentials_not_found	The User API key is not valid.

Success

Format:

{"status": "ok", "count": "count of events", "events": [{"originator": "originator ", "type": "EventType", "timestamp": {"ctime": "Fri May 8 09:41:51 2009", "isoformat": "2009-05-08T09:41:51.906000"}, "appversion": "0.9.0.270", "location": {"lat": 60.222831, "lon": 21.372218}, "appid": 1, "message": {"default": "Default message", "key": "irlconnect.event.login"}, "data": {"IrlUser": {"guid": "guid", "name": "nickname"}}}], "timestamp": "2009-05-08T09:41:56.187000", "size": "1"}