OpenStreetBugs/API 0.6

From OpenStreetMap Wiki
Jump to navigation Jump to search

This page describes yet another reimplementation of the API of OpenStreetBugs intended to potentially be put onto the main page.

This is currently only a discussion draft and is likely to still change. Please suggest improvements

The API is currently accessible as a test via HTTP with the URL prefix http://openstreetbugs.dev.openstreetmap.org/api/0.6/bugs/. The source code is available in the OSM svn for a more exact reference.

The implementation might not fully conform to these specifications yet.

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.dev.openstreetmap.org/api/0.6/bugs/<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. This is for compatibility reasons, and there should also be methods available to get the information in separate fields. If returned in a single textfield, 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. The bugs will be ordered by the date of their last change, the most recent one will go first. The list of bugs can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the format parameter.


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

The b,l,r,t parameters should be renamed to a single bbox= parameter to be in line with the rest of the api

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.
format Specifies the format of the returned values Currently RSS, XML, json, javascript are supported By default, JavaScript is returned to be compatible with the old API
limit Specifies the number of entries returned at max A value of between 1 and 10000 is valid 100 is the default
closed Specifies the number of days a bug needs to be closed to no longer be returned A value of 0 means only open bugs are returned. A value of -1 means all bugs are returned. 7 is the default

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) { }

searchBugs

It should be possible to search for text in the comments

TODO

getOwnBugs

Retrieve your own bugs and bugs you have commented on.

TODO

getGPX

Should this be merged with the getBugs call with just a different format= parameter?

getRSSfeed

Should this be merged with the getBugs call with just a different format= parameter?

getItem

Returns the data on a specific bug entry

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.
format Specify the return type. RSS, XML, javascript, json.

Editing bugs

addPOIexec

This API function should probably be renamed

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. No default value, has to be specified.
name The author name. If the user is logged in, the OSM user name automatically overwrites this value. NoName.
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

This API function should probably be renamed

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. 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

This API function should probably be renamed

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);
}


API - style

Retrieving bug data by bounding box: GET /api/0.6/notes

Returns the existing notes in the specified bounding box. The notes will be ordered by the date of their last change, the most recent one will be first. The list of notes can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the file extension.


URL: http://api.openstreetmap.org/api/0.6/notes?bbox=left,bottom,right,top (example)
Return type: application/xml


Parameter Description Allowed values Default value
bbox Coordinates for the area to retrieve the bugs from Floating point numbers in degrees none, parameter required
limit Specifies the number of entries returned at max A value of between 1 and 10000 is valid 100 is the default
closed Specifies the number of days a bug needs to be closed to no longer be returned A value of 0 means only open bugs are returned. A value of -1 means all bugs are returned. 7 is the default

You can specify the format you want the results returned as by specifying a file extension. E.g. example to get results in json. Currently the format RSS, XML, json and gpx are supported.

Error codes

HTTP status code 400 (Bad Request)
When any of the limits are crossed

Read: GET /api/0.6/notes/#id

Returns the existing note with the given ID. The output can be in several formats (e.g. XML, RSS, json or GPX) depending on the file extension.


URL: http://api.openstreetmap.org/api/0.6/notes/#id ([1])
Return type: application/xml

Error codes

HTTP status code 404 (Not Found)
When no bug with the given id could be found

Create a new bug: Create: POST /api/0.6/notes

Create a new bug


URL: http://api.openstreetmap.org/api/0.6/notes?lat=51.00&lon=0.1&text=ThisIsABug (example)
Return type: application/xml


Parameter Description Allowed values Default value
lat Specifies the latitude of the bug floatingpoint number in degrees No default, needs to be specified
lon Specifies the longitude of the bug floatingpoint number in degrees No default, needs to be specified
text A description of the reported bug A text field with arbitrary text No default, needs to be present

If the request is made as an authenticated user, the note is associated to that user account.

Error codes

HTTP status code 400 (Bad Request)
if the text field was not present
HTTP status code 405 (Method Not Allowed)
If the request is not a HTTP POST request

Create a new comment: Create: POST /api/0.6/notes/#id/comment

Add a new comment to note #id

URL: http://api.openstreetmap.org/api/0.6/notes/#id/create?text=ThisIsABugComment (example)
Return type: application/xml

Parameter Description Allowed values Default value
text The comment A text field with arbitrary text No default, needs to be present


Error codes

HTTP status code 400 (Bad Request)
if the text field was not present
HTTP status code 404 (Not found)
if no bug with that id is not available
HTTP status code 405 (Method Not Allowed)
If the request is not a HTTP POST request

Close: PUT /api/0.6/note/#id/close

Close a note as fixed.


URL: http://api.openstreetmap.org/api/0.6/notes/#id/close?text=Commnet (example)
Return type: application/xml

This request needs to be done as an authenticated user.

Error codes

HTTP status code 404 (Not Found)
When no bug with the given id could be found
HTTP status code 405 (Method Not Allowed)
If the request is not a HTTP PUT request

Search for notes on text and comments: GET /api/0.6/notes/search

Returns the existing notes matching either the initial note text or any of the comments. The notes will be ordered by the date of their last change, the most recent one will be first. The list of notes can be returned in several different forms (e.g. XML, RSS, json or GPX) depending on file extension given.


URL: http://api.openstreetmap.org/api/0.6/notes/search?q=SearchTerm ([2])
Return type: application/xml


Parameter Description Allowed values Default value
q Specified the search query String none, parameter required
limit Specifies the number of entries returned at max A value of between 1 and 10000 is valid 100 is the default
closed Specifies the number of days a bug needs to be closed to no longer be returned A value of 0 means only open bugs are returned. A value of -1 means all bugs are returned. 7 is the default

Error codes

HTTP status code 400 (Bad Request)
When any of the limits are crossed

Suggested improvements

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

  • 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: 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?
Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=OpenStreetBugs/API_0.6&oldid=898403"