API changes between v0.4 and v0.5

This change history reflects the changes in the API between versions 0.4 and 0.5.

Version 0.5 was released on 2007-10-07.

In a nutshell:

• Use '0.5' in the XML and URLs
• Removed segments. A way consists in V0.5 of nodes instead of segments in V0.4 and earlier
• Added relations and the corresponding commands to create, store, get and delete relations
• OSM objects are versioned, making it possible to access the full history of every object modification from this point onward

Ways without segments

Version 0.5 does away with segments. Ways are represented as an ordered list of nodes instead:

(Data Primitives page explains the current definitions of these terms)

Areas

Note that, when written as an ordered list of nodes, an area will always reference one node twice (first and last node will be identical).

Areas with holes

Areas with holes in them have in the past often been modelled as one way with two non-contiguous "rings" of segments. This is not possible without segments; ways must always be contiguous. Thus, an area and its holes have to be created as individual ways, and then grouped using a relation. An example is given below.

Relations

Version 0.5 supports a new object type called "relation" (although it might also be used for other purposes than just relations). A relation object can have tags like ways and nodes do, plus it can have any number of members (which may be nodes, ways, or relations themselves).

Membership information is not stored on individual objects, but rather on the relationship object. This means that adding a way to a relationship or removing it does not change the way - it only changes the relation object.

References

Referential integrity is assured. The API does not allow the deletion of objects which are "used" in a relationship (much like nodes cannot be deleted when used by a way). Editors are responsible for handling "weak" relationships (i.e. before deleting an object itself, the object has to be removed from all relations refering to that object). The data model does not know the difference between weak and strong relationships.

API functions

Accessing Nodes

The API commands dealing with the creation, modification, and deletion of Nodes remain unaltered. The only change is that the attempt to delete a node that is referenced by a relationship will fail.

Information about any relationships a node may be in is not passed in the description of the node itself.

Accessing Ways

The XML representation of ways is changed to refer to nodes directly:

Old (API v0.4)		New (API v0.5)
<way id="13"> <seg id="345" /> <seg id="346" /> <seg id="347" /> <seg id="348" /> <tag k="highway" v="residential" /> <tag k="name" v="Dorfstrasse" /> </way>		<way id="13"> <nd ref="401" /> <nd ref="402" /> <nd ref="403" /> <nd ref="404" /> <nd ref="405" /> <tag k="highway" v="residential" /> <tag k="name" v="Dorfstrasse" /> </way>

This modified structure is used for reading, creating, and updating ways.

Information about any relationships a way may be in is not passed in the description of the way itself.

Accessing Relations

(See also API v0.5).

Relations have tags and members. The XML for relationships looks like this:

<relation id="99"> <member type="way" ref="345" role="" /> <member type="way" ref="346" role="" /> <member type="way" ref="347" role="" /> <tag k="highway" v="motorway" /> <tag k="type" v="superway" /> </relation>

There may be any number of members (order is insignificant). The type attribute is one of "way", "node", or "relation". The ref attribute specifies the id of the object referenced. Only type and ref together identify the object referenced. The role attribute is optionally used to specify which role the object plays in the relationship. For simple groupings, role is expected to remain empty or be left out?, but for turn restrictions etc. it will have an arbitrary string value.

Relations support the same operations that nodes and ways do and work in the same fashion.

Bounding box queries

These will now additionally return relations that affect one of the returned objects.

Areas with holes example

Here's an area with a "hole":

<way id="1">
   <tag k="natural" v="water" />
   <nd ref="10" />
   <nd ref="11" />
   ...
   <nd ref="20" />
   <nd ref="10" />
</way>

<way id="2">
   <nd ref="50" />
   <nd ref="51" />
   ...
   <nd ref="59" />
   <nd ref="50" />
</way>

<relation id="1">
   <tag k="type" v="multipolygon" />
   <member type="way" ref="1" role="outer" />
   <member type="way" ref="2" role="inner" />
</relation>