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.

Implemented parts

General notes

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.

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.

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.

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.

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.