OpenStreetBrowser/API Proposal
As you can read on OpenStreetBrowser/API the OpenStreetBrowser (OSB) already implements an API for third party applications (for sure the same API is used by OSB itself. The idea for the next version is, that people can define their own categories with all their interesting features (a forester might be interested in forests, high seats and feedlots, a OSM enthusiast in objects with fixme-tags, notes and maybe even bugs from OpenStreetBugs). For sure those categories would be shared, like a wiki-page.
Definition of a category
A category-definition is an XML-File with a couple of rules:
<category id="1" version="1">
<tag k="name" v="Foresters category" />
<tag k="name:de" v="Försterliste" />
<tag k="description" v="A list of things that might be interesting for foresters" />
<tag k="lang" v="en" />
<tag k="sub_categories" v="2;3" />
<rule id="1">
<tag k="name" v="Forest"/>
<tag k="name:de" v="Wald"/>
<tag k="display_name" v="[wood_name];[name]"/>
<tag k="display_type" v="wood"/>
<tag k="match" v="landuse=forest"/>
<tag k="importance" v="regional"/>
</rule>
<rule id="2">
<tag k="name" v="Highstand"/>
<tag k="name:de" v="Hochstand"/>
<tag k="match" v="building=highstand"/>
<tag k="importance" v="urban"/>
</rule>
</category>
For a list of tags see: OpenStreetBrowser/Category_Tags
Query/Modify List
There's a public HTTP-API were you can query or modify categories: http://www.openstreetbrowser.org/categories.php?[options]
Categories-API
The Categories-API is accessible as /categories.php and allows to change, list and download categories.
POST /categories.php?todo=save&[options]
Options:
| id=ID | Use 'new' to create a new category or the ID of a previously downloaded list |
| version=YYY branch=XXX |
If a previous save failed because of a conflict, provide the branch-id and version-id of the status-message to resolve the conflict |
Post the XML-content of the category to the HTTP Request.
POST /categories.php?todo=save&[options]
Options:
| id=ID | Use 'new' to create a new category or the ID of a previously downloaded list |
| version=YYY branch=XXX |
If a previous save failed because of a conflict, provide the branch-id and version-id of the status-message to resolve the conflict |
Post the XML-content of the category to the HTTP Request.
Return:
<result> <status id='' version='' branch='' status='' /> </result>
| id= | The ID of the changed category |
| version= | The version of the file. This is an unique id, as generated by the versioning system (git) |
| branch= | If there was a conflict saving the file, recover the change from this branch (provide this parameter for conflict resolve). |
| status= | 'Ok' if saving was successful. Other values indicate failures. |
GET /categories.php?todo=list&[options]
Options:
| lang=de | The preferred language of the result (defaults to the default_language of the category or 'en') |
Post the XML-content of the category to the HTTP Request.
Return:
<result> <category id='XXX' version='YYY'>name</category> </result>
| id= | The id of an available category |
| version= | The latest version of this category |
GET /categories.php?todo=list&[options]
Options:
| lang=de | The preferred language of the result (defaults to the default_language of the category or 'en') |
Lists all categories.
Return:
<result> <category id='XXX' version='YYY' lang='en'>name</category> .... </result>
| id= | The id of an available category |
| version= | The latest version of this category |
| lang= | The language of the returned name |
| name | The name of the category |
GET /categories.php?todo=history&[options]
Options:
| id= | The ID of the requested category |
Return the history of the file.
Return:
<result> <category id='XXX' version='YYY'>change message</category> .... </result>
| id= | The id of an available category |
| version= | The version of this entry |
Click on an object
| lat, lon | lat and lon in SRID 900913 |
| zoom | current zoom level |
| categories | ,-separated list of list of categories |
| hidden_categories | ,-separated list of loaded but hidden categories |
| count | only first <count> results |
<result>
<category id="1" version="1">
<match category_id="culture" rule_id="1" id="node_123456;way_1234">
<tag k="name" v="Schwarzwald"/>
<tag k="name:en" v="Black Forest"/>
<tag k="name:fr" v="Whatever ;)"/>
<tag k="#distance" v="5.321" />
<tag k="#geo:center" v="POINT(1822041.05722666 6140217.1238253)"/>
<tag k="#rule_id" v="1234" />
</match>
...
</category>
</result>
Response to a Category-Query
http://www.openstreetbrowser.org/skunk/list.php?viewbox=...&zoom=..&category=...
| viewbox | left,top,right,bottm in SRID 900913 |
| zoom | current zoom level |
| category | list of categories, e.g. culture,religion |
Example: [1]
<result>
<category id="1" version="1">
<match rule_id="1" id="node_123456;way_1234">
<tag k="display_name" v="Schwarzwald"/>
<tag k="display_name:en" v="Black Forest"/>
<tag k="display_type" v="mixed"/>
<tag k="geo:center" v="POINT(1822041.05722666 6140217.1238253)"/>
<tag k="icon" v="http://..../.../foo.png"/>
<tag k="importance" v="local"/>
</match>
...
</category>
</result>