Used to mark the vertical relationship between two features.
The layer=* tag is one of several methods used to describe vertical relationships between crossing or overlapping features. The vertical ordering established by the layer values is valid exactly only in the precise location (not node) where the ways cross or objects overlap. Joining the ways with a shared node at the point where they cross would destroy the vertical order established by layer. The layer=* is not suitable to define vertical relationships of adjoining, nearby or distant elements or areas.
Values between -5 to 5 are used, 0 should not be used explicitly.
Ways passing above other ways on a bridge will have a higher layer value, ways passing in tunnels bellow other ways will have lower (negative) values. All ways without an explicit value are assumed to have layer 0.
With some exceptions, layer=* on ways should be used only in combination with one of tunnel=*, bridge=*, highway=steps, highway=elevator, covered=* or indoor=yes. For areas, it could be used in combination with tags such as man_made=bridge, building=* and similar.
Ways in buildings (or similar structures like multilevel parking lots, shopping centers, airports, railway stations, some multilevel bridges and roads...) may be better described with level=* instead of layer.
The layer provides absolutely no information about relative or absolute height difference of objects which do not immediately cross or overlap. A change in layer should not be used to indicate a change in elevation. A bridge is at layer 1 even if it is only several feet above sea level while the peak of Mount Everest is at layer 0 even though it is 8848 meters above sea level.
ele=* can be used to indicate elevation above sea.
Here are the main guidelines:
- Features at layer 0 should not normally have a layer tag.
- Do not use layer=-1 to hide warnings about crossing or overlapping ways. Either fix them or leave the easily visible warning so that others can fix them.
- Tag shortest possible/practical sections of ways. Long viaducts and tunnels can be tagged with a suitable single value for their entire length for simplicity although it may sometimes be better to adjust the layer along its length to accommodate more complicated crossings.
- Use the smallest suitable layer 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. For convenience some higher values are often locally used/reserved for very long bridges or underground networks where it is assumed that they are above/bellow most other crossings/objects in the area.
- When ways are passing on different levels apply layer=* only to the way which also has the bridge/tunnel attribute. Only ways with one of the tags/attributes tunnel=*, bridge=*, highway=steps, highway=elevator, covered=* should be tagged with the layer tag, similar for railways and waterways.
- 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.
- Rivers and streams should not be tagged with layer -1 along long sections of their length, crossings should be tagged like other crossings with bridges, tunnels and layer. Waterways that are covered may be tagged with covered=yes 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 (ford=*).
- 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. The location=overground can be used and layer=* may be used for example when two power lines cross.
- Some other features like man_made=pipelines 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 which is frequently not easily available for buried pipelines. layer=* may be used for example when two pipelines lines cross where the information is knwon.
- 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 or long sections.
- 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)