Socialight / API

Socialight API (V1) Documentation

Naveen Selvadurai [naveen@socialight.com]

Introduction

Some functionality of the Socialight platform is exposed via an Application Programming Interface (API). This document serves as a reference to the API. The latest version of the web service allows you to create and search for notes.

Concepts

The endpoints are all REST services. This means that you can construct these requests using either your browser, the command line or in other client-side code.

Most API services will use GET. If a particular endpoint requires POST, it will be specified alongside the request keyword.

All request URLs start with the hostname and service name:

http://socialight.com/api/

Then you should specify the method followed by a question mark:

profile?

This is followed by query parameters, which take the form argument=value. Both arguments and values must be url encoded. Some API methods take optional parameters; these are documented on a case-by-case basis below.

Currently, the API only supports XML (default) and KML as a response data format. KML is only available for certain queries.

All responses are UTF-8 encoded.

The Application ID (appid)

All requests require the use of an application ID (appid). You can obtain an application ID from this page:

http://socialight.com/api

You must be a registered member of Socialight in order to get access to an application ID. The appid is a string that uniquely identifies your application. If you have multiple applications, you must use a different ID for each one.

User authentication

Some requests, such as methods that access private data or create notes require that you pass in user details. This is needed in order to pull the proper data from your account and to return a feed that's more customized for your preferences. In some cases, user details are needed on top of the application ID in order to properly create data inside the Socialight network. For instance, creating notes on the platform requires that you not only pass in an appid but that you also authenticate the user so that the note can be attributed to their account.

There is currently one method for authenticating users: HTTP Basic Authentication.

HTTP Basic Authentication

When accessing authenticated endpoints from a browser, you'll be prompted to enter login details which the browser then passes to the server on your behalf. As a developer, you can take the same approach by passing authentication details with the appropriate header. To construct the header:

Concatenate the username and password into a single string with a colon (:) separating the fields, like this: username:password
Base64 encode the string.
Send the "Authorization" HTTP header with the value "Basic X" where X is the Base64-encoded string.

Methods

If the endpoint has 'latitude' as a request parameter, it goes without saying that 'longitude' should also be provided alongside the request. If you attempt to provide one without the other, your request will fail.

In case of error, the endpoint will return XML that takes the following structure:

<result>
 <error>The location could not be found.</error>
</result>

where 'error' is a string that explains the error in human-readable format. It is safe to either show this error directly to the user or to translate it into something more suitable for your application.

General actions

Geocode

Helps geocode (address to latitude/longitude) and reverse-geocode (latitude/longitude to address). This is particularly useful when attempting to figure out a user's location if all they know is the address. In reverse, this can help you show users a "friendly address" if all you know are latitude and longitude.

You can either provide the address or the latitude/longitude. If address is supplied, a latitude/longitude will be returned (is possible). If latitude/longitude is supplied, a proper address will be returned.

The geocode method is private and requires the use of a secret key. Please contact Socialight for more details.

URL: http://socialight.com/api/geocode

Request method: GET

Authentication: None

Request:

appid. Required.
geosecretkey. Required.
address. Free-text string indicating location. Ex: 1600 Pennsylvania Avenue, Washington, D.C.
latitude, longitude.

Response:

if you specify an address:

<result>
  <location>
    <latitude>40.7145118713379</latitude>

    <longitude>-74.0071411132812</longitude>
  </location>
</result>

if you specify coordinates:

<result>
  <location>
    <address>Robert F Wagner Sr Pl & Pearl St, Manhattan, NY 10038</address>

    <latitude>40.71</latitude>
    <longitude>-74.00</longitude>
  </location>
</result>

Sample requests:

To get the latitude and longitude for the address "1600 Pennsylvania Avenue, Washington, D.C.":
- http://socialight.com/api/geocode?geosecretkey=GEO&appid=YOUR_APPID&address=1600+Pennsylvania+Avenue,+Washington,+D.C.
To get the address if you already know the latitude and longitude:
- http://socialight.com/api/geocode?geosecretkey=GEO&appid=YOUR_APPID&latitude=40.71451&longitude=-74.00714

User actions

Profile

Returns basic details about the user's account. This is useful when you want your application to cache elements such as nickname, keys or profile picture. If you authenticate, this function will allow you to retrieve your own details and will give you your authToken. You can also use this same endpoint to get details about other users (pass in a value for the uid parameter).

URL: http://socialight.com/api/profile

Request method: GET

Authentication: None, HTTP Basic

Request:

appid. Required.
uid. Required. User ID for the account that you wish to retrieve details.

Response:

a sample response for the current user:

<result>
  <user>
    <id>1</id>

    <nickname>naveen</nickname>
    <firstname>Naveen</firstname>
    <lastname>S</lastname>
    <photo>http://socialight.com/images/1/1/1_100.jpg</photo>

    <authToken>a1b2c3d4e5</authToken>
  </user>
</result>

Sample request:

To get user details for yourself when you don't know your user ID, authenticate yourself and call:
- http://socialight.com/api/profile?appid=YOUR_APP_ID
To get user details for an account identified by ID X, whether or not you've authenticated:
- http://socialight.com/api/profile?appid=YOUR_APPID&uid=X

Check-in

Allows the user to update their current location. Specify either an address or location coordinates.

URL: http://socialight.com/api/checkin

Request method: GET

Authentication: HTTP Basic

Request:

appid. Required.
address.
latitude, longitude.

Response:

if you specify an address:

<result>
  <location>
    <latitude>40.7145118713379</latitude>
    <longitude>-74.0071411132812</longitude>

  </location>
</result>

if you specify coordinates:

<result>
  <location>
    <address>Robert F Wagner Sr Pl & Pearl St, Manhattan, NY 10038</address>

    <latitude>40.71</latitude>
    <longitude>-74.00</longitude>
  </location>
</result>

Sample requests:

To checkin to a location if you already know the address:
- http://socialight.com/api/checkin?appid=YOUR_APPID&address=202+1st+Avenue,nyc
To checkin to a location in you know the latitude and longitude:
- http://socialight.com/api/checkin?appid=YOUR_APPID&latitude=40.730169&longitude=-73.983418

List actions

Sources

Returns a list of sources that are currently visible to the user. The link indicates the query parameters to use when getting detail about a particular source. If you provide user authentication details, custom user-specified layers are returned in addition to the default list.

URL: http://socialight.com/api/layers

Request method: GET

Authentication: None, HTTP Basic

Request:

appid. Required.

Response:

<layers>
  <layer>
    <name>Around me</name>
    <link>type=all</link>

  </layer>
  <layer>
    <name>My notes</name>
    <link>type=user&uid=1</link>

  </layer>
...

Sample request:

To get a list of all sources currently available to you:
- http://socialight.com/api/layers?appid=YOUR_APPID

Source detail

Provides a list of notes that match the criteria given in the parameters. You can request this data as either XML (default) or KML. If you provide user authentication details, private notes are also returned in addition to the default public list.

Optionally, if you pass in a valid geo secret key, a map tile will be made available. It will be identified as 'mapLink'. This is a private option and is only available to certain applications. Please contact Socialight for more details.

URL: http://socialight.com/api/layer

Request method: GET

Authentication: None, HTTP Basic

Format: XML, KML

Request:

appid. Required.
type. Type of content requested
- all. all notes around you (default)
- contacts. all notes from contacts
- favorites. all of your notes marked as 'favorite'
- channel. notes from a particular channel as identified by channelid
- user. notes from a particular user as identified by uid
latitude, longitude.
what. search keyword
sort. choose one: nearest, recent, ordered. The default is nearest which sorts all data according to closeness to location. recent orders everything chronologically, with the first item in the list being the one created most recently. ordered sorts everything according to a list/user-defined order, which usually happens in the case of "walks", "pub crawls" or similar content.
radius. Defines, in miles, the area to search. The default is 5 miles.
limit. number of results to show. the default is 5.
offset. used to request more results after initial set(s). the sequence starts at offset+1.
format. Optional. Allows you to request data as either xml (default) or kml.

Response:

<result>

  <note>
    <id>1</id>
    <title>Sweetness!</title>
    <link>http://socialight.com/note/2008/1/1/asdf</link>

    <imageLink>http://socialight.com/public/users/1/1/1/images/1.11111_small.png</imageLink>
    <mapLink>http://socialight.com/map/smallmap/40.0/-75.0</mapLink>
    <author id="1">naveen</author>
    <created>2008-01-01 05:39:47</created>

    <expires>2018-01-31 17:41:18</expires>
    <text>Great ice cream selection. Girls will love the lychee-flavored one. Ask the short lady in back if she has
an overflow batch of cookies. Get your hands on those cookies. Then eat them along with the ice cream.</text>
    <latitude>51.527809625256</latitude>
    <longitude>-0.0768184661865234</longitude>

    <place>We All Scream for...</place>
    <address>123 Main Street, Anytown, NY</address>
    <tags>icecream lychee cookies</tags>
    <action_favorited>true</action_favorited>

    <statistics_favorite>10</statistics_favorite>
    <statistics_thumbsup>15</statistics_thumbsup>
    <statistics_thumbsdown>0</statistics_thumbsdown>
  </note>

  <note>
...

Sample requests:

To get a list of all notes close to you, sorted by notes created recently:
- http://socialight.com/api/layer?appid=YOUR_APPID&type=all&sort=recent&latitude=40.730169&longitude=-73.983418
To get a list of all notes close to you, sorted by closeness:
- http://socialight.com/api/layer?appid=YOUR_APPID&type=all&sort=nearest&latitude=40.730169&longitude=-73.983418
To get a list of all notes close to you, sorted by closeness and returned as KML:
- http://socialight.com/api/layer?appid=YOUR_APPID&type=all&sort=nearest&latitude=40.730169&longitude=-73.983418&format=kml
To get a list of notes from people you are following:
- http://socialight.com/api/layer?appid=YOUR_APPID&type=contacts&latitude=40.730169&longitude=-73.983418
To get a list of notes that match the keyword 'sushi':
- http://socialight.com/api/layer?appid=YOUR_APPID&type=all&what=sushi&latitude=40.730169&longitude=-73.983418
To get a list of five notes that come after the initial five results for the keyword 'sushi':
- http://socialight.com/api/layer?appid=YOUR_APPID&type=all&what=sushi&latitude=40.730169&longitude=-73.983418&offset=5

Note actions

Create note

Allows you to create a new note at a location. If you are attaching media, you must use POST to submit this request.

URL: http://socialight.com/api/createnote

Request method: POST

Authentication: HTTP Basic

Request:

appid. Required.
latitude, longitude. Required.
text. The message. The only allowed HTML tags are: b, p, br, a, img.
title. A title for the note. (optional). No HTML tags are allowed.
media. An attached media file. Currently only images of the following types are supported: JPG, GIF, PNG. (optional)
visibility. The privacy/visibility level for the note.
- 1. only me.
- 2. only people following me.
- 3. for everyone (default).
tags. Space-separated list of tags.

Response:

<result>
 <note>
  <id>123</id>
  <title/>
  <link>http://socialight.com/note/2008/1/1/abc</link>

  <mapLink>http://socialight.com/map/smallmap/40.0/-75.0</mapLink>
  <author id="1">naveen</author>
  <created>2008-03-26 09:53:34</created>
  <expires>2018-03-26 21:53:34</expires>

  <text>My friend Kellyn works the bar.</text>
  <latitude>40.0</latitude>
  <longitude>-75.0</longitude>
  <place>Back Room</place>

  <address>123 Ludlow</address>
 </note>
</result>

Sample request:

To create a note near 12th and 1st Avenue, New York, NY:
- http://socialight.com/api/createnote?appid=YOUR_APPID&latitude=40.730169&longitude=-73.983418&text=I+lived+around+here.&visibility=3&tags=home+eastvillage

Comment

Gives you the ability to add a comment to a note.

URL: http://socialight.com/api/commentnote

Request method: GET

Authentication: HTTP Basic

Request:

appid. Required.
noteid. Required. Indicates the note on which to perform this action.
comment. Required. The text of the comment you wish to add. The only allowed HTML tags are: b, p, br, a.

Response:

<comment>success</comment>

Sample request:

To add a comment to a note with ID X:
- http://socialight.com/api/commentnote?appid=YOUR_APPID&noteid=X&comment=Yeah,+I+second+that.

Flag

Gives you the ability to quickly mark a note (save as a favorite, thumbs up/thumbs down, flag as inappropriate).

URL: http://socialight.com/api/flag/[type] where type is one of 'favorite', 'inappropriate', 'thumbsup' or 'thumbsdown'.

Request method: GET

Authentication: HTTP Basic

Request:

appid. Required.
noteid. Required. Indicates the note on which to perform this action.

Response:

<flag>favorite</flag>

Sample request:

To save a note with ID X as a favorite:
- http://socialight.com/api/flag/favorite?appid=YOUR_APPID&noteid=X

Feeds

The methods listed above will allow you to progammatically query and modify data inside Socialight. Sometimes, though, you might just need to export all notes from a particular user or channel. You can do this by using one of the feed access points. These access points will allow you to retrieve notes in either the GeoRSS or KML format.

User

Allows you to export notes created by a particular user.

URL: http://socialight.com/[format]/[username]

Request method: GET

Authentication: None

Request:

format. Required. Indicate either rss or kml.
username. Required. Specify the username as a URL-encoded string.

Response:

<feed xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:georss="http://www.georss.org/georss" xmlns="http://www.w3.org/2005/Atom">
  <title>naveen's Socialight Feed</title>

...

Sample request:

To get all notes from the user 'cjn208' as RSS:
- http://socialight.com/rss/cjn208
To get all notes from the user 'cjn208' as KML:
- http://socialight.com/kml/cjn208

Channel

Allows you to export notes in a particular channel.

URL: http://socialight.com/[format]/channel/[channelurl]

Request method: GET

Authentication: None

Request:

format. Required. Indicate either rss or kml.
channelurl. Required. Specify the channel's friendly URL name as a URL-encoded string. The channel's friendly URL name can be found on the channel's home page: it's the last part of the URL that follows '/channels/'. For instance, if you were looking at the "Late Night London" channel with the URL http://socialight.com/channels/late_night_london, the friendly channel name would be late_night_london.

Response:

<feed xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:georss="http://www.georss.org/georss" xmlns="http://www.w3.org/2005/Atom">
  <title>Around NYC Channel Socialight Feed</title>
...

Sample request:

To get all notes from the channel 'Around NYC' as RSS:
- http://socialight.com/rss/channel/aroundnyc
To get all notes from the channel 'Around NYC' as KML:
- http://socialight.com/kml/channel/aroundnyc

Tutorial and examples

HOWTO

In addition to the sample requests you see above, we've made available a tutorial you can use to get a grasp of how to construct queries. This tutorial will also show you how to pull all of these details together into an application.

http://socialight.com/help/apihowto

Java

We've also open-sourced our official Java mobile application. It is a location-aware application that will show you notes near you. It also has the ability to create notes and, if your handset has a camera, it will allow you to tag pictures.

http://code.google.com/p/socialight

Ruby

Lastly, we've also published a sample Ruby command-line application that you can use as a starting point for creating apps on top of the API. This application will allow you to search around a location by keyword and will return results in text format.

http://socialight.com/public/code/sclapi.rb

Testing

You can use your browser to test the endpoints. We prefer using Firefox as it shows you a live preview of the XML returned by our service.

Changelog

01 January 2008: Initial
28 March 2008: Limits and offsets; formatting changes
31 March 2008: Ordered lists
03 April 2008: Sample requests have been added
07 April 2008: Sort keyword 'nearby' is incorrect; changed to 'nearest'
08 April 2008: Ability to create media (images) alongside a note
18 April 2008: Support for multiple applications: appid and user authentication required; formatting changes
21 April 2008: Profile now supports both authenticated and unauthenticated usage
28 April 2008: Minor wording changes and definitions
30 April 2008: KML support
05 May 2008: Tutorial and example applications
06 May 2008: Feeds
18 June 2008: Java
01 July 2008: User authentication is now optional for sources (/layers, /layer)
19 August 2008: User input validation in new notes and comments