Used to mark the vertical relationship between two features.
The layer=* tag is used to mark the vertical relationship between two different features. It provides no information about the absolute height or the absolute vertical spacing between the features for which ele=* should be used. If two ways intersect then they must have the same layer, if one passes above another then they should have different layers. In general it is assumed that any object that has no layer tag is at the natural, or permanently changed ground level (which can also be considered to be at layer=0). Positive values up to layer=5 are used for elements that pass above features at ground level and negative values down to layer=-5 for features that are below ground.
It is sometimes appropriate to tag some features, such as man_made=pipelines and power=cables to be tagged with location=overground or location=underground which indicates that they are in the air or buried without providing any information about relative heights where pipes or cables cross.
The layer tag gives information about the relative vertical relationship between two features, and does not provide any indication of absolute heights and a change in layer does not necessarily indicate any change in height. A bridge over a stream should be at level 1 even if the stream is as far below it as the Grand Canyon. A track on top of Mount Everest is considered to be at ground-level even though it is 8848 meters above sea level. A bridge passing over a river should be tagged as being at layer=1 for the duration of the bridge even if there is no vertical change in height in the road.
Here are the main guidelines:
- Features at layer 0 should not normally have a layer tag. Exceptions include tunnels or bridges which are indeed at layer 0.
- For preference use the smallest suitable value. Only use layer=2 for a bridge that passed over a feature that is already at level 1; similarly only use layer=-2 would be used for a tunnel that passed below another tunnel.
- Long viaducts and tunnels can be tagged with a suitable single value for their entire length for simplicity although there it may sometimes be appropriate to adjust the layer along its length to tunnel to accommodate more complicated crossings.
- Within complex junctions it is often necessary to break way to change the layer and thereby ensure that the vertical arrangement of intersections is accurately described.
- Power lines (power=line) do not normally need to be tagged with a layer and are assumed to float above all other features unless a layer value is used to indicate otherwise. Where power lines cross each other or pass under some other feature then suitable layer tags should be used on the relevant ways to indicate the vertical arrangement.
- Waterways (waterway=*) do not normally need to be tagged with a layer and are generally rendered as if they flow underneath built features. Where a highway is at the same level as a waterway, you can add a junction node and tag (ford=*).
- When a way (or ways) passes under a bridge at layer=1 then the lower way does not normally need to be tagged as a tunnel or as layer=-1. Conversely, when a way passes above a tunnel then the way(s) above it do not need to be tagged as a bridge or with layer=1.
- Where a single way passes under a number of ways using a single 'bridge' it may be appropriate to create a single tunnel at layer=-1 rather than multiple bridges at layer=1.
- Although some map rendering and quality assurance services assume that bridges and tunnels are at layers +1 and -1 respectively it is better to explicitly state the layer for all bridges and tunnels.
Note that there can some ambiguity about whether a particular crossing should be tagged as a bridge or as a tunnel, particularly where the distance under the upper way is long. In general the way though a tunnel tends to be longer and darker, whereas the way under a bridge tends to be shorter and less dark. The GDF standard uses the term 'brunnel' to cover both features.
Things to avoid
Here are some common examples of how not to use the layer tag:
- Landuses, such as parks and woods should not normally be tagged with a layer. Adding a layer result in ways at ground level getting hidden. The exception to this rule is where a landuse is indeed above another landuse.
- Road and railways etc should not be tagged with a layer just because they are raised up on an embankment or are in a cutting - use embankment=* and cutting=* for this purpose. No layer tag is normally required.
- An island (place=island) in a lake (natural=water) should not be tagged as layer=1, nor should a clearing in a wood. This has sometimes been done in an attempt to get the island or clearing to render properly. A multipolygon should be used for this purpose.
- Floors within a building should be tagged with level=* rather than layer.
- Use the smallest suitable layer value. Simple bridges over a way at ground level should use layer=1 not layer=2.
- Rivers and streams should not be tagged with layer -1 along their entire length. Some people do however advocate tagging rivers and streams at layer -1 where they pass under a succession of bridges using layer=0 for the bridge. This does however create some difficulties with respect to intersecting ways (for example, an underground pipeline would need to be layer=-2 to cross under the stream).
- Positive values do not need a '+' sign. Use 'layer=1' rather than 'layer=+1'.
|This layers view of Washington using ITO Map shows how elements are correctly organised with elements that pass over other elements at ground level using layer 1 (red) unless it is necessary for them to to use layer 2 (orange). Elements underground are using layers -1 or -2 as appropriate.|
|This view of the Grand Union canal in the UK shows incorrect use of layers. The canal switches from surface (no layer) to layer -1 (dark blue) to layer 2 (orange) for no reason. bridges and tunnels are using high layer numbers than necessary and some don't have layers at all. A point where a stream and footpath pass under the canal in a tunnel are shown at the same layer as the canal (layer -1 as it happens). A car park and collection of tracks in the village are shown at layer=-1 - no layer tag is needed given that they are at ground level.|
|Layer tags used incorrectly for woods and a golf course. The woods are on layer 2, a golf course on layer -1 and a common on layer -2. These features are all at ground level and will render correctly without layering.|