JOSM/Plugins/GeoChat/API

From OpenStreetMap Wiki
< JOSM‎ | Plugins‎ | GeoChat
Jump to: navigation, search
Available languages
English русский

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 http://zverik.dev.openstreetmap.org/osmochat.php.

Registration

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

?action=register&lat=...&lon=...&name=...

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.

?action=logout&uid=...

Frees the user id and name.

?action=whoami&uid=...

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

Receiving Messages

?action=get&lat=...&lon=...&uid=...

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

?action=post&lat=...&lon=...&uid=...&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.