From OpenStreetMap Wiki
< JOSM‎ | Plugins‎ | GeoChat
Jump to navigation Jump to search

This is a description of GeoChat API. All request use HTTP GET. Action name is passed in the action parameter. Some requests need a current user's position in WGS-84. Responses are returned in JSON hash, including error and success messages.

The server is currently located at


To use the chat, users should register. Their names are needed for communicating and to identify them in the stream.


This registers a user with name name who's editing at specified coordinates. Returns an error if a name is already taken. Names are freed after logging out, or an hour since the last message request. A succesful request returns user identified in uid field: it is required for most other requests.


Frees the user id and name.


Returns a name for a registered user. This is useful when identifiers are persisted between sessions.

Receiving Messages


This returns all messages and users near the specified coordinates. Radius is configured on the server and currently is 20 kilometers. Response is a JSON hash with three arrays: messages for public messages, private for private ones, and users with a list of neraby users.

Messages are sorted by time, new ones are at the end. Every message is a hash with the following entries:

Key Value
id A unique identifier for the message. ID space is common for all messages. It is recommended to use &lastid=... for requesting just the new messages; its value is the identifier of the last received message.
lon, lat Message position.
time Sending time in DD-MM-YYYY HH:MM:SS format. Time zone is usually UTC, but you can check the server time with ?action=now call.
timestamp UNIX timestamp.
author Sender's name.
message Message text.
incoming false if the message was sent by the user who requested this list.

For private messages a recipient field is added, which contains a name of a user to whom the message is addressed.

Every element of users array contains three field: name in name field and coordinates in lat, lon.

Sending a Message


This posts a message at the specified position. For private messages add &to=... parameter with a recipient's name. If there is no user with that name registered, the server will return an error.

Messages are automatically purged from the database after several hours.