OpenStreetBrowser/API Proposal

From OpenStreetMap Wiki
Jump to: navigation, search

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

http://www.openstreetbrowser.org/skunk/identify.php?lat=...&lon=...&zoom=...&categories=...&hidden_categories=...&count=10

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>