Socialight API HOWTO
1. Introduction
Socialight's API allows you to access Socialight content from other sources. You can use this access to create location-based applications on top of our platform. This document will give you an overview on how to get started with the API quickly.
2. Register for a Socialight account
If you haven't already done so, create an account with Socialight. You can do this at:
After signup, enter some data about your favorite places. This will not only give your friends something to find and learn, but it will give you an idea of how the platform works. Later on, when you are querying for data, you'll be able to better understand how the location queries work as you might see your own data returned in the results.
3. Register an application
After you register for a Socialight account, you can become a Socialight developer by registering your first application. You can do this at:
This page is a single stop for all developer-related content. The latest documentation and notices will be listed on this page. This page also displays all of your registered application keys. A developer can register more than one application key. For example, you might want one key for testing and another for your live application.
To register an application, click "Apply" on this page. You'll be taken to a form where you'll be prompted to provide details about your app. Fill in the application name and a description and, optionally, enter a URL where your users might be able to find your app or documentation and extensions related to your app. Make sure you do a good job in filling out this information. At some point in the future, we'll give you the ability to publish your application in a directory along with all the others written using Socialight. When you are done, click "Apply." The system will register your application, mark it live and will generate a unique application ID.
4. Try out your appid on the endpoints
Now that you have an appid, you should try some queries against the API to make sure it works and to get an idea of the data that's returned.
As an easy test, let's say you wanted to get a list of 10 notes that are close to an address. For example, "183 Thompson Street, New York, NY". To do this, you'd use the "layer" query. This query is the one you'll probably use the most as it gives you a single interface to ask for notes from various sources, do searches, etc. At this point, you need to convert your friendly address into a latitude/longitude pair so that the query can understand your location. In future, we might make it possible for you to query based on a text address, but currently due mainly to geocoding limits, we have to restrict the type of location queries our servers can do.
So let's continue with the example. To convert the address to a latitude/longitude pair, you can use any of the freely available online geocoding systems. With Yahoo's API, you can perform a query like:
It will return a proper latitude/longitude pair that you can then use in the next step.
In your web browser, try this as a query, where "APP_ID" is the appid that was generated for you in step 3:
The server may ask you to authenticate yourself. This authentication step is different from the appid as it will give you a chance to distinguish yourself from all the other people using the application (and therefore, the same appid). Authenticating will let Socialight know who you are so that the content can be tailored to your account. For instance, this means that you'll now have the ability to retrieve: notes you've created, notes from people you're following and your favorite notes.
After you successfully authenticate, Socialight will return a response to your search. If there is no data in the area you indicated (for instance, the middle of Antarctica), the server will return an empty set:
<result></result>
Otherwise, the server will return a maximum of 10 results:
<result>
<note>
<id>1072</id> <title>Good noodle house</title> <link>...
5. Using the API in an application (Ruby)
It's relatively easy to build this same query flow into your application. For instance, you can construct REST queries in Ruby as follows:
require 'net/http' http = Net::HTTP.new('socialight.com')
http.start do |http|
req =
Net::HTTP::Get.new('/api/layer?appid=APP_ID&latitude=40.727965&longitude=-74.000257&limit=10')
req.basic_auth 'username', 'password'
resp, data = http.request(req)
end
The 'data' variable now holds the returned XML that you saw in step 4. You can make use of one of the XML parsing libraries (like REXML) in Ruby to extract the data from the XML response. To give you an idea of what you can do in an application, we've made available a Ruby application as a sample. It is a command-line program that will allow you to search around a location by keyword.
6. That's it!
You've now successfully seen how to access one of the endpoints that Socialight makes available. You can repeat the same exercise on all the other requests in the API as well. See the API documentation for more details.