Used to mark the vertical relationship between two features.
The layer=* tag is used to mark vertical relationships between different crossing or overlapping features and / or between a feature and the ground level. The layer=* is not suitable to define vertical relationships of adjoining or nearby elements or areas.
layer=0 represents the natural ground level as it would be shown by contour lines on a topographic map. Positive values up to layer=5 are used for elements that are above ground level, and negative values down to layer=-5 for elements that are below ground level.
If two ways intersect then they should have the same layer. If one passes above another then they should have different layers and at least one of them also a bridge or tunnel tag.
Note that the layer provides no information about the absolute height or the absolute vertical spacing between features (use ele=* for that purpose instead). A change in layer thus does not necessarily indicate a change in height (although in practice it actually often does). A bridge is at level 1 even if the ground is as far below it as the Grand Canyon, and a track on top of Mount Everest is at level 0 even though it is 8848 meters above sea level.
Any object that has no layer tag is generally assumed to reside on ground level. This is also true for bridges and tunnels. For this reason, it's strongly recommended to explicitly state the layer for all bridges and tunnels.
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 passes over a feature that is already at level 1; similarly only use layer=-2 for a tunnel that passes below another tunnel.
- When ways are passing on different levels it is usually preferable to apply layer=* only to the way which also has the bridge/tunnel attribute. The other way(s) should not be tagged unless they are also on a bridge or in a tunnel.
- Tag shortest possible section of ways.
- 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 accommodate more complicated crossings.
- Within complex junctions it is often necessary to break ways 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=*). Rivers and streams should not be tagged with layer -1 along their entire length.
- Some other features like man_made=pipelines and power=cables can also be appropriately tagged by using location=overground or location=underground instead of layer=*. This simply indicates that they are in the air or buried, without providing any actual relative height information. layer=* may be used for example when two pipelines cross.
- Where a single way passes under a number of bridges it may be appropriate to create a single tunnel rather than multiple bridges. Conversely, where a single way passes over a number of bridged ways it may be appropriate to create a single bridge rather than multiple tunnels.
- 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 be 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 through 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 results in ways at ground level getting hidden. The exception to this rule is where a landuse is indeed above another landuse.
- Roads, railways, waterways 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=*, respective waterway=ditch for this purpose.
- 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. Any other intersecting ways however need to have a correct layer tag then as well (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 higher 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.|
- Proposed_features/layer_change (A tag to help renderers avoid artefacts when layers change, thus making it easier for them to respect the layer tag)
- Proposed_features/default_layer_for_bridge_and_tunnel, rejected proposal