RESTful API Overview

Brightkite provides a RESTful API for integration with 3rd parties.  Your application must be authenticated before you can begin making calls to the REST API.  Please see the Authentication Guide for instructions on how to do this.  This document also assumes that you have a basic understanding of REST and HTTP.

Registering and Authorizing API Applications

To register a new application and get an OAuth key visit:

http://brightkite.com/me/developed_apps

To see the apps that you have authorized:

http://brightkite.com/me/authorized_apps

Formats

Every resource that is available from the API can be requested in either XML or JSON format.  There is no difference in the operations or the data that is available for both formats, so feel free to use whichever format you prefer for your application.  In a nutshell, append .xml or .json to Brightkite URLs, and you get stuff in that format.

Example:

Here is the URL for Brightkite HQ "place" page:

http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab

Here is the same URL for the XML representation:

http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab.xml 

Go ahead and click it, your browser should show you some XML with the information about where our offices are located.

Now if you're feeling bold, try some JSON:

http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab.json

You can also specify which format you want by setting the HTTP 'Accepts' header to something like 'application/xml' or 'text/xml', however if you plan on using the JSON API this way, be sure that you use 'application/json' or 'text/json', not 'text/javascript'.  Use UTF-8 encoding for text .

One difference between the XML and JSON representations is that in the XML representation, the type of object is described by the name of the top-level tag.

<place>
    <scope>address</scope>
    <country>US</country>
    <zip>80205</zip>
    <street2 nil="true"/>
    <display_location>2911 Walnut St, Denver, CO 80205, USA</display_location>
    <street>2911 Walnut St</street>
    <longitude type="float">-104.98248</longitude>
    <city>Denver</city>
    <shortcode>x9fvxkn</shortcode>
    <latitude type="float">39.762146</latitude>
    <state>CO</state>
    <name>Brightkite HQ</name>
    <id>356a192b7913b04c54574d18c28d46e6395428ab</id>
</place>

In the JSON representation, all objects have one additional attribute, called object_type, which is the same as the XML tag name.

{

    "scope": "address",

    "country": "US",

    "zip": "80205",

    "street2": null,

    "display_location": "2911 Walnut St, Denver, CO 80205, USA",

    "street": "2911 Walnut St",

    "longitude": -104.98248,

    "city": "Denver",

    "shortcode": "x9fvxkn",

    "latitude": 39.762146,

    "state": "CO",

    "name": "Brightkite HQ",

    "object_type": "place",

    "id": "356a192b7913b04c54574d18c28d46e6395428ab"

}

Any of the JSON endpoints which are available from a GET request also support JSON-P by adding a callback parameter to the request.  The response will wrap the JSON in a function call to whatever you specify as your callback.

Ex:

http://brightkite.com/me/friends.json?callback=handleBrightkiteFriends 

There are more examples of the objects that are returned from the API in the API Object Reference document.

Resources  

Retrieving information about a resource is done by making an HTTP GET request to the URL for the resource.  This makes it easy to explore the API from within your browser - click on any of the links in this section to see a representation of the data returned by the API.  Creating, updating, and deleting resources will be covered later.

The 'Me' Resource

There's a good chance that your application will want to retrieve information about the current user, so we've made sure this information is always available at the location /me.  This URL will always return information about the user you are currently logged in as.  Try it now if you are logged in to Brightkite: http://brightkite.com/me.xml

People 

Information about other users in the system can be retrieved by requesting it from /people/<login_name>.

For example: http://brightkite.com/people/mcollins.xml

You can also search for people:

curl -X GET http://brightkite.com/people/search.xml?query=John

Friends

You can get a list of a user's friends by requesting /people/<login_name>/friends

Example: http://brightkite.com/people/mcollins/friends.xml

Using the /me resource also works here if you are logged in:

http://brightkite.com/me/friends.xml

Pending friendships ( people who have sent you a request to be friends ) are also available through the API:

http://brightkite.com/people/mcollins/pending_friends.xml

Places

Places are what Brightkite is all about.  Each place represents a physical location in the real world somewhere, and is assigned a unique identifier (UUID) by Brightkite.  The identifiers themselves are just a string of characters and do not contain any useful information in and of themselves. For example, the UUID for Brightkite HQ is 356a192b7913b04c54574d18c28d46e6395428ab.  If you know a place's UUID you can get more information for that place by requesting it from /places/<uuid>.

So to find out where Brightkite HQ is you could go to:

http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab.xml

That's not very useful though if you don't know the UUID of the place you are looking for, so you can also search for places using the API by requesting /places/search and sending the address in as the value of the query parameter q.

For example:

http://brightkite.com/places/search.xml?q=Denver

Street addresses work too:

http://brightkite.com/places/search.xml?q=2911%20Walnut%20St.%2C%20Denver%2C%20CO

Even latitude,longitude:

http://brightkite.com/places/search.xml?q=39.762146%2C%20-104.98248

The other types of objects available from the REST API are usually associated with a place, so we refer to them as Place Objects.  This includes checkins, notes and photo posts described below. 

Place objects are also identified by a UUID and are available from the /objects/<uuid> URL.

http://brightkite.com/objects/c09617edc7ff700faf66ec71a7646b2506e20035.xml

To find all the objects associated with a particular place: /places/<uuid>/objects

http://brightkite.com/places/9f32b279bb70c3a39b42e687a25e137613390681/objects.xml 

Places and People

Want to see who is checked in at a place?  No problem, just add /people to the place URL.

http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab/people.xml

People URL's also accept a radius parameter so you can see who's nearby.  Radius is specified in meters up to 100,000.

http://brightkite.com/places/1b6453892473a467d07372d45eb05abc2031647a/people.xml?radius=2000

You can also specify hours_ago to see who's been there recently.

http://brightkite.com/places/1b6453892473a467d07372d45eb05abc2031647a/people.xml?radius=2000&hours_ago=2

Checkins, Notes, and Photos

Each of these types of objects is associated with a user and a place in Brightkite.  Just as you can get all the objects for a place by using a path like /places/<uuid>/objects, you can also get all the objects associated with a particular user by using the /people/<login>/objects path.  The information that is returned when you are requesting objects by user depends on your relationship to the user and that user's settings -- friends and trusted friends can sometimes be allowed more precise location data.  Calling one of these URLs will return all the objects for that user or place.  Much of the time you are only interested in one type of object, so the /objects URLs allow you to specify that via the filters query parameter.

Examples:

Get all checkins for a place:
http://brightkite.com/places/9f32b279bb70c3a39b42e687a25e137613390681/objects.xml?filters=checkins

Get all notes created by a user:
http://brightkite.com/people/mcollins/objects.xml?filters=notes

Get all notes and photos created by a user:
http://brightkite.com/people/mcollins/objects.xml?filters=notes,photos

Search objects:

http://brightkite.com/objects/search.xml?oquery=Denver

Placemarks

Placemarks are Brightkite's own version of bookmarks for real world places.  Users create placemarks so they can give a place a custom name that is easy to remember and check in at.

To get a list of a user's placemarks:

http://brightkite.com/me/placemarks.xml

Or to see all the placemarks for a place:

http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab/placemarks.xml

Comments

Photos and notes can have comments attached to them. If you want to get all the comments for an object you simply add /comments to the object's URL.

Examples:

http://brightkite.com/objects/38c5462ce60bbce1d6f4f98c90f39673c5cb0b3d/comments.xml

http://brightkite.com/objects/91b8d9698d1f2d25ba61550c378dc3a7b99578af/comments.xml

Direct Messages

Direct messages are messages from one user to another.  They aren't related to a place, and they won't show up in either user's streams. Nudges are a type of direct message that have a pre-defined message body.  There are two resources related to direct messages: sent_messages and received_messages.

To see direct messages you have sent:

http://brightkite.com/me/sent_messages.xml

Or those you've received:

http://brightkite.com/me/received_messages.xml

To send a direct message to another user, create a received_message via the recipient's login and send message[body].   For example:

  curl -X POST -u login:pw http://brightkite.com/people/<recipient>/received_messages.xml -dmessage[body]='i like turtles'

Friendships

Friendships contain information about existing relationships with friends, like whether that friend is trusted and where a friend's checkins and posts are sent. If you are already friends with a user, you can get the friendship object by going to /people/<friend login name>/friendship

Blocks

For those times when that reeeallly annoying person just won't stop bugging you, Brightkite allows you to block users so their posts will not show up in your feeds or be sent to your phone or email.  

http://brightkite.com/me/blocked_people.xml

Streams

The Brightkite API also provides access to several streams that contain only the objects that are interesting from a certain point-of-view.  Some of these are analogous to the RSS/KML feeds described in the Feeds document.

Friend Stream

The Friend Stream contains all the recent activity for a user and his or her friends.

http://brightkite.com/me/friendstream.xml

Nearby Stream

The Nearby Stream contains activity within a certain radius of the place you are checked in at.

http://brightkite.com/me/nearbystream.xml

Mentions Stream

The mentions stream contains all the note and photo posts where someone has mentioned you with @username

http://brightkite.com/me/mentionsstream.xml

Comments Stream

The comments stream contains comments for the notes and photo's you've posted and any other posts you are tracking.

http://brightkite.com/me/commentsstream.xml

Other Operations - Create, Update, Delete

Creating new objects with the Brightkite API is done via POST requests.  The body of the post request should contain parameters that specify the attributes for the object you are creating or updating.  These parameters are usually the same as the attribute names returned in JSON or XML from a GET request.   Requests will fail if some of the attributes required to create the object are missing or invalid ( like notes that are too long, etc.).  Some parameters  are commonly specified in a form like object[attribute].

Objects that need a place in order to be created ( checkins, notes, photos, etc. ) use a URL format that is created by adding the type of object to the end of the place's URL, e.g.  /places/<place id>/<object_type>.  To update an object that has already been created, you can use the direct form of the URL, /objects/<object_id>

Updating existing objects through the API can be done by sending a PUT request to the URL for the object and including the attributes you want to update as parameters in the request body.

There's not much point in putting an example here for deleting something, as it would only work for the first person who tried it.  If you've made it this far and you were trying out the examples, you've probably already created a few test objects with the Brightkite API.  Now go ahead and send an HTTP DELETE to a URL for one of the objects you've just created, and see it disappear right before your eyes!  Delete requests won't return any data, but if the operation was successful your application will receive a 200 response.

Checkins

Checkins are simple to create because they don't require any extra parameters, just POST to the place you want to check in at.  It doesn't really make sense to update checkin objects, but if you made a mistake creating one, just DELETE it and create a new one.

    REST URL formats:

    /places/<place id>/checkins

         /objects/<object id>         

    /places/<place id>/checkins/<object id>

    Required parameters: none

Example:

  curl -X POST http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab/checkins.xml

Notes

Notes need a body parameter, which contains the actual text of the note.

    REST URL formats:

        /places/<place id>/notes

        /objects/<object id>        

    /places/<place id>/notes/<object id>

    Required parameters:

        note[body] :  up to 140 characters of text

Examples:

    Create a new note (with an XML response):

    curl -X POST -u login:pw http://brightkite.com/places/356a192b7913b04c54574d18c28d46e6395428ab/notes.xml  -dnote[body]=supercooltestnote

  Update an existing note (with a JSON response):

    curl -X PUT -u login:pw http://brightkite.com/objects/a9c594ec8f4338de9ca7d70319a0c309075d60df.json -dnote[body]=Updated%20note

Photos

Photos are similar to notes except that the body parameter is optional, and a photo is required.

    REST URL formats:

    /places/<place id>/photos

    /objects/<object id> 

    /places/<place id>/photos/<object id>   

    Required parameters:

        photo[photo] : JPEG, PNG, GIF or BMP file

    Optional parameters:

        photo[body] :  note or caption for the photo (up to 140 characters of text)

 Examples:

Comments

You can create comments for notes and photos as long as you know the UUID for the object you are commenting on.  When you create a comment you also have the option of 'tracking' the comments for that object so that you are notified when other people comment as well.  The default behavior on the Brightkite website is to turn tracking on.

    REST URL formats:

    /objects/<object id>/comments

    Required Parameters:

        comment[comment] : Text of the comment.  Comments are not restricted to 140 characters like notes are.

    Optional Parameters:

        watch_item : 0 or 1.  Boolean that indicates whether to track this comment.

Examples:

Direct Messages

    REST URL formats:

    /people/<login name>/sent_messages

    /people/<login name>/received_messages

Examples:

Friendships

Friendship objects represent a relationship between you and another user.  They also contain the individual settings for trust and for how you receive updates.

    REST URL formats:

        /me/friendship

    Required Parameters:

    person_id  : user name of the person you are creating a friendship with.

    Optional Parameters :

    friendship[trusted] : boolean ( 0 or 1) indicating whether the friend is trusted.

    friendship[checkin_stream_feeding] : boolean ( 0 or 1) indicating whether this friend's checkins should show up in your stream.

    friendship[checkin_sms_notifications] : boolean ( 0 or 1) indicating whether this friend's checkins should be sent to your phone via SMS.

    friendship[checkin_email_notifications] : boolean ( 0 or 1) indicating whether this friend's checkins should be sent to you via email.

    friendship[post_stream_feeding] : boolean ( 0 or 1) indicating whether notes and photo posts should show up in your stream.

    friendship[post_sms_notifications] : boolean ( 0 or 1) indicating whether notes and photo posts should be sent to your phone via SMS.

    friendship[post_email_notifications] : boolean ( 0 or 1) indicating whether notes and photo posts should be sent to you via email.

Examples:

Blocks

Blocks allow you to prevent posts from certain users from getting sent to you.

    REST URL formats:

    /people/<login name>/blocked_people

        /me/blocked_people

Updating and Modifying User Account Settings

User accounts in Brightkite have a number of settings which can be updated via the API.  To see your current settings, request http://brightkite.com/me/config.xml 

The object returned by the config resource is an expanded Person object, so it contains the same information as requesting /me but with additional data for the user's account settings.

To update settings, send a PUT request with the parameters you want to update.

Example - update a user's privacy mode to public:

curl -X PUT http://brightkite.com/me/config -dperson[privacy_mode]=public -u username:password

Configs

Configs represent account settings for a particular Brightkite user. 

    REST URL formats:

        /people/<login name>/config

    /me/config