JOSM/Plugins/GeoChat/API
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 https://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.