OpenStreetBugs/API 0.1

This page describes a historic artifact in the history of OpenStreetMap. It does not reflect the current situation, but instead documents the historical concepts, issues, or ideas.

---

This page describes the API of OpenStreetBugs in version 0.1. The API is accessible via HTTP on with the URL prefix http://openstreetbugs.schokokeks.org/api/0.1/. The source code is available on Github for a more exact reference.

General conventions

This API intends to be backwards compatible to the old OpenStreetBugs API.

All data is encoded in UTF-8. All coordinates are in WGS-84 (normal GPS coordinates).

You access the API using normal HTTP GET requests on the URL http://openstreetbugs.schokokeks.org/api/0.1/<Action>?<Param 1>=<Value 1>&<Param 2>=<Value 2>&<...> (without the <>). (In this document, everything that stands between < and > is to be replaced by the appropriate values.)

Every bug consists of an ID, a position (longitude and latitude), a description, an author, a creation date, a status and zero or more comments consisting of a text, an author and a date. The ID is a 64-bit integer. The status can be open (represented by a 0) or closed (represented by a 1). A closed bug does not differ from an open bug in any way except for its status. Several API methods that return bugs return the text, author and date of the bug and its comments not in separate fields but as one single HTML string. The comments and the main description are separated by the code <hr />. The format how the author and the date are encoded in the description and in the comments is not standardised (see #Suggested improvements).

Reading bugs

getBugs

Returns the existing bugs in the specified bounding box as executable JavaScript code, so they can be included in an OpenLayers map without being restricted to the Same Origin Policy. Bugs that have been closed less maximum 7 days ago will also be included. The bugs will be ordered by the date of their last change, the most recent one will go first. The number of returned bugs will not exceed 100.

URL: http://openstreetbugs.schokokeks.org/api/0.1/getBugs?b=<Bottom coordinate>&t=<Top coordinate>&l=<Left coordinate>&r=<Right coordinate> (example)
Return type: text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/getBugs

Parameter	Description	Allowed values	Default value
b	The southern coordinate of the bounding box.	A floating point number greater than or equal -90, has to be less than the value of the t parameter.	No default value, has to be specified.
t	The northern coordinate of the bounding box.	A floating point number less than or equal 90, has to be greater than the value of the b parameter.	No default value, has to be specified.
l	The western coordinate of the bounding box.	A floating point number greater than -180, has to be less than the value of the r parameter.	No default value, has to be specified.
r	The eastern coordinate of the bounding box.	A floating point number less than or equal 180, has to be greater than the value of the l parameter.	No default value, has to be specified.

The JavaScript function that will be called by this API call has to have the following format (see #General conventions for the format of the single parameters):

function putAJAXMarker(bugId, longitude, latitude, descriptionAndComments, status) { }

getGPX

Returns the existing bugs in the specified bounding box as GPX file that can be downloaded to use in a navigation device or to include in an application. The GPX file contains all the bugs as GPX Waypoints. The bugs will be ordered by the date of their last change, the most recent one will go first.

URL: http://openstreetbugs.schokokeks.org/api/0.1/getGPX?b=<Bottom coordinate>&t=<Top coordinate>&l=<Left coordinate>&r=<Right coordinate>&open=<Only open bugs>&limit=<Bug number limit> (example)
Return type: application/xml
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/getGPX

Parameter	Description	Allowed values	Default value
b	The southern coordinate of the bounding box.	A floating point number greater than or equal -90, has to be less than the value of the t parameter.	No default value, has to be specified.
t	The northern coordinate of the bounding box.	A floating point number less than or equal 90, has to be greater than the value of the b parameter.	No default value, has to be specified.
l	The western coordinate of the bounding box.	A floating point number greater than -180, has to be less than the value of the r parameter.	No default value, has to be specified.
r	The eastern coordinate of the bounding box.	A floating point number less than or equal 180, has to be greater than the value of the l parameter.	No default value, has to be specified.
open	Return only open bugs.	Any value, only the presence of this parameter counts.	By default, both open and closed bugs are returned.
limit	The maximum number of bugs to return.	An integer greater than or equal 0 and less than or equal 100000.	1000

getRSSfeed

Returns the existing bugs in the specified bounding box as RSS feed. The RSS feed contains the last 10 changed bugs within the specified area, the one that has been changed most recently goes first.

URL: http://openstreetbugs.schokokeks.org/api/0.1/getRSSfeed?b=<Bottom coordinate>&t=<Top coordinate>&l=<Left coordinate>&r=<Right coordinate>&open=<Only open bugs> (example)
Return type: application/rss+xml
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/getRSSfeed

Parameter	Description	Allowed values	Default value
b	The southern coordinate of the bounding box.	A floating point number greater than or equal -90, has to be less than the value of the t parameter.	No default value, has to be specified.
t	The northern coordinate of the bounding box.	A floating point number less than or equal 90, has to be greater than the value of the b parameter.	No default value, has to be specified.
l	The western coordinate of the bounding box.	A floating point number greater than -180, has to be less than the value of the r parameter.	No default value, has to be specified.
r	The eastern coordinate of the bounding box.	A floating point number less than or equal 180, has to be greater than the value of the l parameter.	No default value, has to be specified.
open	Return only open bugs.	Any value, only the presence of this parameter counts.	By default, both open and closed bugs are returned.

rssitem

Returns an RSS feed that always contains the latest change/state of the specified bug.

URL: http://openstreetbugs.schokokeks.org/api/0.1/rssitem?id=<Bug ID> (example)
Return type: application/rss+xml
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/rssitem

Parameter	Description	Allowed values	Default value
id	The ID of the Bug.	A 64-bit integer.	No default value, has to be specified.

Editing bugs

addPOIexec

Creates a new bug on the specified position. Returns a message as text that indicates whether the bug was successfully created. If the format parameter is used, the output can also be a JavaScript function call.

URL: http://openstreetbugs.schokokeks.org/api/0.1/addPOIexec?lat=<Latitude>&lon=<Longitude>&text=<Bug description with author and date>&format=<Output format>
Return type: text/html (actually plain text) or text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/addPOIexec

Parameter	Description	Allowed values	Default value
lat	The latitude where to create the bug.	An integer less than or equal 90 and greater than or equal -90.	No default value, has to be specified.
lon	The longitude where to create the bug.	An integer less than or equal 180 and greater than -180.	No default value, has to be specified.
text	The description of the bug including its author and creation date.	The following format is recommended: <Description> [<Author>, <Date in the format YYYY-MM-DD>]. If the message does not containg anything matching the expression \d\d:\d\d:\d\d (where \d represents a digit), the last character is stripped and the following string is appended: , <Current date>].	No default value, has to be specified.
format	The format the response should have.	js if the response should be JavaScript.	By default, the response will be plain text with the MIME type text/html.

If format is js, a function like the following will be called:

function osbResponse(errorMessage) {
  if(errorMessage == undefined)
    alert("Bug successfully created.");
  else
    alert("Error creating bug: "+errorMessage);
}

editPOIexec

Adds a new comment to an existing bug. Returns a message as text that indicates whether the comment was successfully added. If the format parameter is used, the output can also be a JavaScript function call.

URL: http://openstreetbugs.schokokeks.org/api/0.1/editPOIexec?id=<Bug ID>&text=<Comment with author and date>&format=<Output format>
Return type: text/html (actually plain text) or text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/editPOIexec

Parameter	Description	Allowed values	Default value
id	The ID of the bug to add the comment to.	A 64-bit integer.	No default value, has to be specified.
text	The comment including its author and creation date.	The following format is recommended: <Comment> [<Author>, <Date in the format YYYY-MM-DD HH:MM:SS TIMEZONE>]. If the message does not containg anything matching the expression \d\d:\d\d:\d\d (where \d represents a digit), the last character is stripped and the following string is appended: , <Current date/time>].	No default value, has to be specified.
format	The format the response should have.	js if the response should be JavaScript.	By default, the response will be plain text with the MIME type text/html.

If format is js, a function like the following will be called:

function osbResponse(errorMessage) {
  if(errorMessage == undefined)
    alert("Comment successfully added.");
  else
    alert("Error adding comment: "+errorMessage);
}

closePOIexec

Marks an existing bug as closed. Returns a message as text that indicates whether the bug was successfully closed. If the format parameter is used, the output can also be a JavaScript function call.

URL: http://openstreetbugs.schokokeks.org/api/0.1/closePOIexec?id=<Bug ID>
Return type: text/html (actually plain text) or text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/closePOIexec

Parameter	Description	Allowed values	Default value
id	The ID of the bug to close.	A 64-bit integer.	No default value, has to be specified.

If format is js, a function like the following will be called:

function osbResponse(errorMessage) {
  if(errorMessage == undefined)
    alert("Bug successfully closed.");
  else
    alert("Error closing comment: "+errorMessage);
}

Suggested improvements

Feel free to add something here or on the talk page.

• General: Introduce a better data format that separately stores comments, descriptions, authors and dates.
• getBugs: Bounding boxes cannot cross the date line as the l parameter has to be less than the r parameter.
• rssitem: Should contain all changes of the bug instead of just the last one.
• addPOIexec/editPOIexec/closePOIexec: Should not define MIME type text/html without actually sending HTML code.
• addPOIexec/editPOIexec/closePOIexec: Include a mechanism in the callback JavaScript function to find out which action actually failed. Perhaps make an additional parameter that the client may specify and that will then be sent back through the callback function?
• getGPX: the elements in "extensions" should have their own openstreetbugs namespace (see [1])
• getRSSfeed: Would be nice to retrieve all bugs within a specified bounding box, not just the 10 newest ones.