API v0.3
Historical Interest Only. Version 0.3 no longer in use
This document describes OSM Protocol Version 0.3 which is no longer in use. We stopped using version 0.3 in May 2007. See the Protocol page for a link to the currently active protocol specifications.
The RESTful API
As well as building a mapping system on this website, developers of OpenStreetMap.org are creating an API (Application programming interface) which allows other developers to create new software that uses functionality and accesses the open licenced map data from OpenStreetMap.org.
REST APIs do things like GET_request and PUT XML to URLs. (Four acronyms in one sentence is pretty good). For more information on RESTful APIs see wikipedia's REST page.
Encoding
Server response should specify the encoding used, and use the specified encoding.
<?xml version='1.0' encoding='UTF-8'?> ...
Implemented parts
These things are implemented and ready to use
General notes
You need an account to be able to access the API. You can get an account here: http://www.openstreetmap.org/create-account.html
You should check for 500 HTTP_INTERNAL_SERVER_ERROR etc on any request. This could mean either the API isn't working itself, Apache, or the SQL server. The XML and URLs may change, have bits added and so on. You should keep an eye on the developer MailingLists.
GZIP response encoding is supported by the API to speed up transfer of data. For a reference client implementation in Java, see the applet's source code.
Authentication
HTTP Simple authentication works for the api now. eg http://foo%40example.com:easypass@www.openstreetmap.org/api/0.3/node/1 will work for user 'foo@example.com' with password 'easypass'. You can also use use 'token' and a valid token as the password. Note that %40 is the URL encoding of the @ in the e-mail address.
If any URL returns HTTP 401 Authorization Required then the user/pass has failed.
Map
- url = map?bbox=bllon,bllat,trlon,trlat
- url = map?bbox=bllon,bllat,trlon,trlat&to=YYYY-MM-DD%20HH:MM:SS
Map is the heart of things here. It will provide a bundle of nodes, line segments, and ways given some bounding box. The XML returned will give you the ways that any of the segments within that bounding box belong to. It is NOT going to give you all the segments that those ways own and their nodes, so if you're interested in the segments that a node has you have to fetch them yourself if they lie outside the bounding box.
In the interests of keeping the API snappy, it is restricted to providing data for only moderately sized areas. If you don't need the very latest data, or if you need lots of data, you should use Planet.osm instead.
| HTTP Method | Description | Result |
|---|---|---|
| GET map?bbox=... | Get the map bundle for given bounding box | 200 OK will give you a list of objects.
<?xml version="1.0"?>
<osm version="0.3" generator="OpenStreetMap server">
<way id="5" timestamp="2006-03-13 14:53:55">
<seg id="66996"/>
<seg id="13"/>
<seg id="14"/>
<seg id="15"/>
<tag k="hum" v="cheese"/>
</way>
...
<node lon='-0.148664925516301' uid='60' lat='51.5254829507548'/>
<node lon='-0.148588713362387' uid='110308' lat='51.5278975364617'>
<tag k="name" v="cheese"/>
</node>
<node lon='-0.151248498106725' uid='195063' lat='51.5280013031537'/>
...
<segment id="154325" from="198125" to="198099"/>
<segment id="113991" from="155337" to="155328">
<tag k="name" v="Camden Road"/>
</segment>
<segment id="154392" from="198146" to="198145"/>
...
</osm>
If you get 400 Bad Request, your bounding box was badly defined or too big. (The area limit is currently ~0.1 square degrees. If you need a larger area, use Planet.osm) You can get the map as it was at some point in time with the to parameter, eg something like 'map?bbox=bllon,bllat,trlon,trlat&to=2004-01-01%2012:34:56' |
Nodes
Single Node
You can get the details on a single node. You can also get its history. Nodes come with optional keys and values in the tag sub nodes.
| HTTP Method | Result |
|---|---|
| GET node/40 | 200 OK will give you this:
<?xml version="1.0"?> <osm version="0.3" generator="OpenStreetMap server"> <node lon='-0.148588713362387' id='40' lat='51.5278975364617'> <tag k="hum" v="cheese"/> </node> </osm> With 404 NOTFOUND, that node hasn't been created yet. With 410 GONE, that node has been deleted. |
| GET node/22/history | 200 OK will give you this:
<?xml version="1.0"?> <osm version="0.3" generator="OpenStreetMap server"> <node id="22" lat="51.0039939880371" lon="-0.994343876838684" visible="true" timestamp="2005-04-17 14:46:50"/> <node id="22" lat="51.0039939880371" lon="-0.994343876838684" visible="false" timestamp="2005-04-17 14:46:54"/> </osm> You can specifiy the history period with the to and from parameters. Eg, '/node/22/history?from=2004-01-01&to=2005-06-06%2012:34:52' |
| DELETE | Drops the node. 200 OK means it was dropped. 404 NOT_FOUND means the node wasn't there in the first place. 410 GONE means it's there but already been deleted. |
| PUT | Put some xml and it'll update the node. If you put a node to node/create with id="0" then it will create a node and return you its id. 200 OK means all is well. BAD_REQUEST means the xml was strange, or the xml didn't have the same node uid as the URL did. |
Multiple nodes
- url = nodes?nodes=123,124,4344,2,2123
This gets the details for a list of nodes.
| HTTP Method | action |
|---|---|
| GET | With 200 OK, You get something like:
<?xml version="1.0"?>
<osm version="0.3" generator="OpenStreetMap server">
<node id="123" lat="59.9504280090332" lon="10.7899694442749"/>
<node id="124" lat="59.9498329162598" lon="10.7902059555054"/>
<node id="2" lat="1.0" lon="1.0">
<tag k="testnode" v="yes"/>
</node>
</osm>
|
Line Segments
Single Segment
- url = segment/113991
A single line segment connects two nodes and has optional keys associated with it. It acts much like nodes above.
| HTTP Method | action |
|---|---|
| GET | With 200 OK, You get:
<?xml version="1.0"?>
<osm version="0.3" generator="OpenStreetMap server">
<segment id="113991" from="155337" to="155328">
<tag k="name" v="Camden Road"/>
</segment>
</osm>
With 404 NOTFOUND, that segment hasn't been created yet. With 410 GONE, that segment has been deleted, or one or both of it's nodes have been deleted. |
| GET segment/22/history | With 200 OK, You get:
<?xml version="1.0"?>
<osm version="0.3" generator="OpenStreetMap server">
<segment id="22" from="155337" to="155328" timestamp="2005-04-17 15:12:03" >
<tag k="name" v="Camden Road"/>
</segment>
<segment id="22" from="43" to="41" visible="true" timestamp="2005-04-18 15:12:03"/>
</osm>
You can specifiy the history period with the to and from parameters. Eg, '/segment/22/history?from=2004-01-01&to=2005-06-06%2012:34:52' |
| GET segment/22/ways | Gives you the ways this segment belongs to (including their complete segment list) |
| DELETE | Drops the segment. 200 OK means it was dropped. 404 NOT_FOUND means the segment wasn't there in the first place. 410 GONE means it's there but already been deleted. |
| PUT | Put some XML like the above and it'll update the segment, returning the seg id in the repsponse body if you got 200 OK. If you put a segment with id="0" to segment/create it will create the segment for you. BAD_REQUEST means the xml was strage, or the xml didn't have the same node id as the URL did, or the segments nodes are currently deleted. |
Ways
A 'way' is an ordered list of segments. You can create streets, roads, paths etc from ways.
| HTTP Method | action |
|---|---|
| GET way/6 | With 200 OK, You get:
<?xml version="1.0"?>
<osm version="0.3" generator="OpenStreetMap server">
<way id="6" timestamp="2006-03-13 14:53:56">
<seg id="66996"/>
<seg id="13"/>
<seg id="14"/>
<seg id="15"/>
<tag k="hum" v="cheese"/>
<tag k="gqergqer" v="qerg"/>
</way>
</osm>
Ways have the same /history function as nodes and segments above. |
| PUT | Like nodes and segments, this will create (/way/create) or update (/way/[id]) your 'way'. |
| DELETE | deletes the way |
Areas
An area is simply a "way" that connects to itself to form a closed polygon. There is no separate "area" object in the database.
Uploaded Points
- url = trackpoints?bbox=bllon,bllat,trlon,trlat&page=0
Gets the track points uploaded by various users. It will provide a list of track points, paged, given some bounding box where bllat is the bottom-left latitude, trlon is the top-right longitude and so on. Each page (page goes like 0, 1, 2...) contains 5,000 track points. Currently there is no way to find how many pages there are in total and the newer points are on the early pages.
| HTTP Method | action |
|---|---|
| GET | With 200 OK, You get:
<gpx version='1.0'>
<trk>
<trkseg>
<trkpt lon='-0.20506667' lat='51.495342'/>
<trkpt lon='-0.19523' lat='51.495342'/>
<trkpt lon='-0.19219333' lat='51.495342'/>
[...]
</trkseg>
</trk>
</gpx>
With 400 BAD REQUEST, your bounding box was badly defined or too big |
Unimplemented parts
The following needs implementation.
Quadtiles
A QuadTiles implementation would be desirable.
Authentication
Would be nice to do HTTP DIGEST authentication at some point.
Extra protocol stuff
SSL would be nice.
Fetch only modified data
Idea:
limit GET requests to return only changed data
might be implemented by adding extra fields in the request or by parsing the HTTP request (If-Modified-Since HTTP Header)
Store user's last position
http://trac.openstreetmap.org/ticket/150
Encoding
Server response should specify the encoding used, and use the specified encoding.
<?xml version='1.0' encoding='UTF-8'?> ...
WMS
See WMS Server
Changes in the 0.4 API
- Use '0.4' in the XML and URLs
- Use 'create' instead of '0' to create objects, eg /api/0.4/node/create
- API speaks mime type 'application/xml'