Introduction

Lingr offers a full set of API so that developers can build tools that interoperate with Lingr's functionality. This document is a reference for the API.

Basics

HTTP methods

You call the Lingr API methods using simple HTTP requests. Some of the methods require that you use the GET method, while others require POST.

All of the Lingr API methods require that you pass some parameters when you make the call. For methods that use HTTP GET, you simply include the parameters in the URL that you use to access the method.

For methods that use HTTP POST, the parameters should be included in the body of the request, and the body should have a Content-Type of application/x-www-form-urlencoded.

Format

Lingr supports JSON, XML as data formats. Unless otherwise stated, all API methods supports XML and JSON as a response format, and you can specify it in a request parameter of format with xml or json. When the format parameter is omitted, XML is used by default.

When JSON is specified, all methods accepts callback parameter as well, which will pass the JSON object to a given function so that you can simply eval the response.

• http://www.lingr.com/api/session/create?format=json&callback=myFunc

For instance, when callback=myFunc is given, the response body will look like this:

myFunc({"status": "ok", "session": "2lA42FcLddH"})

Character encoding

Lingr uses, and expects UTF-8 encoding everywhere. That's all you should know.

API keys

To use the Lingr API, you need to have an API key. We use API keys to track usage of the Lingr API, as well as to maintain compliance with the Lingr API Terms of Use.

Getting an API key is simple. Sign up for a Lingr account, Go to here, read the Lingr API Terms of Use, and click the link upon your agreement.

Error codes

The complete list of error codes is available here.

Tutorial

Here's the tutorial to have a overview of how the Lingr API works. You might want to try advanced tutorial also.

Showcase

If you are looking for API libraries or applications that use the API, go to the Showcase.

There is public code written in Ruby, PHP, .NET, Javascript.

API Methods

Session

• session.create
• session.verify
• session.destroy

Authentication

• auth.login
• auth.logout

Explore

• explore.getHotRooms
• explore.getNewRooms
• explore.getHotTags
• explore.getAllTags
• explore.search
• explore.searchTags
• explore.searchArchives

User

• user.getInfo
• user.startObserving
• user.observe
• user.stopObserving

Room

Chat

• room.enter
• room.getMessages
• room.observe
• room.setNickname
• room.say
• room.exit

Query

• room.getInfo
• room.getArchives

Management

• room.create
• room.changeSettings
• room.delete

Common Structures

• Room
• Message
• Occupant
• Tag
• Image URLs

Notes

• Notes for in-browser implementations

Other Resources

• Lingr Discussion on Google Groups
• Available Feeds
• Japanese translation: Lingr Group on Hatena

Recent Changes

• May 16, 2007 — Added new explore.searchArchives method
• May 14, 2007 — Added timezone to the Room structure
• May 2, 2007 — Private messaging support. Added occupant_id parameter to room.say, and new private type to the Message structure
• April 16, 2007 — Added new room.getArchives method
• April 12, 2007 — Added new room.create, room.changeSettings, and room.delete methods
• March 6, 2007 — The room.getInfo and room.getMessages methods now support a new user_messages_only parameter. A new error code 122: repeated counter was defined, and can be returned from the room.getMessages and room.observe methods.
• February 23, 2007 — details
• February 7, 2007 — Added new session.verify
• January 25, 2007 — First version of API released.

Got a comment?

If you've got something to say about the API reference, please let us know in the Google Groups.