Osmxapi
From OpenStreetMap
The OSM Extended API (or osmxapi, pronounced OSM zappy) is an InformationFreeway service, based on a modified version of the standard API, that provides enhanced search and querying capabilities. Also, Osmxapi does not have the bbox size limitation of the standard API and has been designed to handle very large queries.
The dataset it uses is based on the weekly planet.osm and per-minute diff dumps. It is refreshed automatically within about 5 minutes of each per-minute diff file becoming available, so the data is never more than about 10 minutes old.
Osmxapi uses a REST style interface with X-path flavouring.
All responses are in the same format as the standard protocol. Requests have a slightly different format that uses an X-path like syntax to specify the search terms.
Contents |
Elements
Osmxapi implements queries for all three kinds of elements; nodes, ways and relations.
Nodes
A node request will return an xml document containing nodes and their associated tags. The URL for a node request takes the following form:
http://www.informationfreeway.org/api/0.5/node[...]
This will return a standard OSM API response containing nodes and tags. For example:
<?xml version='1.0' standalone='no'?>
<osm version='0.5' generator='osmxapi: OSM Extended API'
xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.4'
osmxapi:uri='/api/0.5/node[amenity=hospital]'
osmxapi:planetDate='200803150826'
osmxapi:copyright='2008 OpenStreetMap contributors'
osmxapi:instance='zappy2'>
<node id='672180' lat='48.2111685091189' lon='16.3035366605548' timestamp='2006-09-11T16:28:25+01:00'>
<tag k='amenity' v='hospital'/>
<tag k='name' v='Wilhelminenspital'/>
</node>
<node id='3596186' lat='53.4633699598014' lon='-2.22667910006381' timestamp='2007-06-21T17:10:58+01:00'>
<tag k='amenity' v='hospital'/>
<tag k='name' v='Manchester Royal Infirmary'/>
</node>
...
</osm>
Ways
The URL for way requests has the following form:
http://www.informationfreeway.org/api/0.5/way[...]
This returns an xml document containing ways that match the search terms. For each matching way the nodes referenced by that way are also returned. An example of the response from a way query looks like this:
<?xml version='1.0' standalone='no'?>
<osm version='0.5' generator='osmxapi: OSM Extended API'
xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.5'
osmxapi:uri='/api/0.5/way[landuse=residential]'
osmxapi:planetDate='200803150826'
osmxapi:copyright='2008 OpenStreetMap contributors'
osmxapi:instance='zappy2'>
<node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00'>
</node>
<node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00'>
<tag k='highway' v='traffic_signals'/>
<tag k='source' v='Yahoo'/>
</node>
...
<way id='4958218' timestamp='2007-07-25T01:55:35+01:00'>
<nd ref='218963'/>
<nd ref='331193'/>
...
<tag k='landuse' v='residential'/>
<tag k='source' v='landsat'/>
</way>
</osm>
Relations
The URL for relation requests has the following form:
http://www.informationfreeway.org/api/0.5/relation[...]
This returns an xml document containing relations that match the search terms. For each matching relation the nodes and ways referenced by that relation are also returned. An example of the response from a relation query looks like this:
<?xml version='1.0' standalone='no'?>
<osm version='0.5' generator='osmxapi: OSM Extended API'
xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.5'
osmxapi:uri='/api/0.5/way[landuse=residential]'
osmxapi:planetDate='200803150826'
osmxapi:copyright='2008 OpenStreetMap contributors'
osmxapi:instance='zappy2'>
<node ...
<way ...
<relation id='2670' timestamp='2007-10-25T03:05:34Z'>
<member type='way' ref='3992472' role=/>
<member type='way' ref='3992524' role=/>
<member type='way' ref='4253050' role=/>
<member type='way' ref='4253053' role=/>
<member type='way' ref='4266813' role=/>
<member type='way' ref='10285106' role=/>
<tag k='name' v='Fonnereau Way'/>
<tag k='network' v='Ipswich footpaths'/>
<tag k='type' v='route'/>
</relation>
</osm>
All Elements
All elements (nodes, ways and relations) that match the given filter predicates can be requested using the following URL:
http://www.informationfreeway.org/api/0.5/*[...]
This returns an xml document containing nodes, ways and relations that match the search terms. For each matching way the nodes and referenced by that way are also returned. Likewise, for each matching relation the ways and nodes referenced by that relation are also returned. An example of the response from this type of query looks like this:
<?xml version='1.0' standalone='no'?>
<osm version='0.5' generator='osmxapi: OSM Extended API'
xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.5'
osmxapi:uri='/api/0.5/*[amenity=hotel]'
osmxapi:planetDate='200803150826'
osmxapi:copyright='2008 OpenStreetMap contributors'
osmxapi:instance='zappy2'>
<node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00'>
</node>
<node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00'>
<tag k='amenity' v='hotel'/>
</node>
...
<way id='4958218' timestamp='2007-07-25T01:55:35+01:00'>
<nd ref='218963'/>
<nd ref='331193'/>
...
<tag k='amenity' v='hotel'/>
<tag k='building' v='hotel'/>
</way>
<relation id='123456' timestamp='2007-10-25T03:05:34Z'>
<member type='node' ref='331193' role=/>
<member type='node' ref='331194' role=/>
...
<tag k='amenity' v='hotel'/>
<tag k='operator' v='Premier Inns'/>
<tag k='type' v='operators'/>
</relation>
</osm>
Predicates
Each API request can be suffixed with selection predicates which determine which elements to select. For example [amenity=hospital] will select all elements that have an amenity tag with a value of hospital. The full url to select all nodes that are tagged as hospitals would be:
http://www.informationfreeway.org/api/0.5/node[amenity=hospital]
A request can be suffixed with multiple predicates, each of which further constrains the results (currently limited to one tag predicate and one bbox predicate). For example:
http://www.informationfreeway.org/api/0.5/node[amenity=hospital][bbox=-6,50,2,61]
this request will select and return all nodes with a tag of amenity=hospital within the bounding box that covers the whole of the England, Wales and Scotland.
Tag Predicates
A selection predicate must be of the form [key=value]. For example: node[amenity=hospital] will match any node that has an amenity key with a value of hospital, ie <tag k="amenity" v="hospital"/>.
A wildcard can be used for either the key or value, so predicates similar to the following examples are possible:
-
way[construction=*] -
node[*=gate] -
node[*=*]Not recommended unless you want several Gbytes of data.
A union operator may also be used to select multiple values. For example to select all major roads:
-
way[highway=motorway|motorway_link|trunk|primary]
The union operator can also be used with the key. For example to select golf courses:
-
node[amenity|leisure=golf_course]
Note: The URL needs to be UTF-8 url encoded in case of non-ascii characters. Firefox (as of version 2.0.0.11) still uses iso-8859-1 encoding by default. [1]
BBox Predicates
Another form of selection predicate is the bbox pseudo key. A selection predicate of the form [bbox=bllon,bllat,trlon,trlat] defines a bounding box that is used to limit the extent of the result document. Only elements that have some part within the bbox will be included in the result document.
Unlike the standard OSM API, the bbox predicate is not limited in size.
The default extent, if a bbox predicate is not specified, is the whole planet. This is equivalent to specifying [bbox=-180,-90,180,90].
Tags
The main method of querying Osmxapi is using a tag/value combination in a predicate. In addition to all the normal tags that you expect to find, Osmxapi stores a number of pseudo-tags that may be useful. They are all stored in the osm: tag namespace to avoid conflict with other tags.
- osm:user - when an element has a user attribute this is stored as the pseudo tag osm:user.
- osm:users - a list of all users who have made edits to an element (edits predating the 0.5 API are not included)
- osm:timestamp
Usage
Osmxapi URLs can be used from within any web-browser, however a simple query can return several Mb of data which can overwhelm some browsers. It is recommended that a tool such as wget or curl be used with the output directed to a file. For example, the following command uses wget to select all hospitals and store the result document in a file named data.osm:
$ wget http://www.informationfreeway.org/api/0.5/node[amenity=hospital] -O data.osm
Note, if you use curl it cannot handle redirections automatically so you need to use the host server directly. Also you need to use the -g option otherwise it will try to interpret the [...] as part of the command line:
$ curl -g http://www.informationfreeway.org/api/0.5/node[amenity=hospital] -o data.osm
Statistics
There are some stats about the contents of the osmxapi database here: http://osmxapi.hypercube.telascience.org/total.xml. These get updated once a day.
RSS Feed
The Osmxapi RSS feed provides a list of changes to elements that have been tagged by a user to be watched.
Any element tagged with watch:yourUserId=1 (or yes or true) will be monitored by Osmxapi and any changes to this element, including deletion, will be shown in the feed. Watched nodes can be grouped into categories by setting the value of the watch tag to the name of a category. For example: watch:80n=churches will add an element to a watchlist category called churches.
To remove an element from your watchlist simply delete the tag from the element.
You can subscribe to your watch list using the following url:
http://www.informationfreeway.org/api/0.5/watch/yourUserId
For example:
http://www.informationfreeway.org/api/0.5/watch/80n
To subscribe to a specific watch category append the URL with the name of the category. For example:
http://www.informationfreeway.org/api/0.5/watch/80n/churches
Notes:
- Anyone can subscribe to your watch list. You can subscribe to anyone's watch list.
- Currently the watch tag is only implemented for nodes.
- This is experimental, there may be significant changes.
- Here's the clever bit: Adding or deleting a watch tag for another user will have no effect. The watch tag for another user can be edited but it will not add or remove that item from that user's watch list. Only edits by the user that owns the watch list will control their watch list.
Limitations
- Created_by tags. These tags are generally un-interesting and have been suppressed to improve performance.
- Predicates. Currently each request is limited to one tag predicate and one bbox predicate. In the future it is hoped that more sophisticated conditions will be implemented. Multiple bboxes would be great for applications like GpsMid - they already implemented data retrieval over Osmxapi in Osm2GpsMid for single regions which is very helpful.
- Request grammar. The request grammar is not formally defined and is not processed using a proper parser, so malformed requests may have unpredictable results. Caveat Emptor.
- user. The planet.osm dump does not contain user information, but the diff files do. Where available the user attribute is returned for each element. A history of user names is also being built so that an attribution list of all users who have edited an element is provided in the
osmxapi:userstag. This will be complete for all changes since the database was last re-synchronised from a complete planet.osm file. This last happened on March 12, 2008.
