Every 3D city view built on OpenStreetMap, the extruded skylines in navigation apps, planning tools, and games, is standing on a handful of tags attached to ordinary flat building outlines. There is no separate 3D database. There is a scheme, Simple 3D Buildings, documented on the OSM wiki, that says how a building's outline and its parts carry heights, floor counts, and roof shapes, and renderers do the rest. This guide teaches the scheme whole: the outline against the part, the height tags and what they measure, the levels tags and what they do not, the roof family, and one building carried from a flat polygon to a fully tagged 3D object.
Home / GIS and Open Map Data for Beginners
OpenStreetMap Building Height: The Simple 3D Buildings Tag Scheme, Taught Whole

Photo: Miguel Moreira / Pexels
Tag the Third Dimension: The Height Checklist
Check off each step as you finish it. Your progress stays on this page.
0 of 7 complete
0% done
The Core Idea: An Outline and Its Parts
The scheme has two levels. The building outline, the way tagged building= that you already know, represents the building as a whole and carries the whole-building tags. Building parts, ways tagged building:part=, are additional outlines inside or overlapping it, each representing a section of the building that differs: the tower on the podium, the annex, the part with the pitched roof. A renderer assembles the 3D building from the outline plus its parts, extruding each by its own height. A simple rectangular block needs no parts at all: outline plus height is a complete 3D building. Parts earn their complexity the moment a building stops being one box, which is most buildings worth modeling. The discipline mirrors the map itself: model the whole first, add parts where reality has parts, and never let the parts contradict the outline's footprint.
The Height Tags: height and min_height
height is the scheme's foundation: the distance from the ground to the top of the roof, in meters. Two clauses in that definition do real work. It is measured to the top of the roof structure, excluding antennas, spires, and other decorative attachments, which are not part of the building's mass and would make every church tower a liar. And it is a measurement of the building, not an estimate from its floors; where you know the height, from a data source, a survey, or a published figure, tag the number. min_height is its partner for raised structures: the height at which a part begins. A bridge-like section between two towers, a building on stilts over a plaza, the upper block set back above a podium roof: each starts at some height above the ground, and min_height says where. A part with height 30 and min_height 12 is the slab of building between 12 and 30 meters, floating in the model exactly where it floats in life, with air beneath it that the renderer correctly leaves empty.
The Levels Tags: building:levels and building:min_level
building:levels counts the floors above ground, and the scheme is precise about the counting: roof levels are not counted as levels, and the number describes the wall's subdivision, not its size. building:min_level is the levels counterpart of min_height: the number of levels below a raised part, skipped between the ground and where that part's floors begin. Now the distinction the wiki itself insists on, and the one this article exists to teach: levels are a texture hint, height is the measurement. A renderer with only levels must guess a floor height and multiply, and its guess will differ from the next renderer's guess, so two maps will show two buildings. A renderer with height draws the building at its true size and uses levels only to texture the facade with the right number of window rows. Tag height wherever you can; add levels in addition, never as a substitute, because a building tagged with levels alone is a building whose height is a rumor each renderer repeats differently.

The Roof Family: roof:shape, roof:height, roof:levels
Roofs are where flat extrusions stop looking like buildings, and the scheme gives them a small family of tags on the outline or the part. roof:shape names the form: flat, gabled, hipped, pyramidal, dome, onion, and a longer documented list. roof:height gives the height of the roof section itself, the part above the wall's top edge, so the renderer can split the building's total height into wall and roof correctly; note it is a portion of the height value, not an addition to it, a subtlety that doubles many a roof when missed. roof:levels counts floors inside the roof space where that is how the building is organized. Supporting tags complete the picture: roof:orientation for which way a ridge runs, and the general building:colour and building:material tags (glass, brick, concrete, and their kin) that let renderers texture the extrusion with something closer to the real facade than default gray. A gabled shape with a correct roof:height transforms a model more than any other single tag in the family; if you add one roof tag to a building, add the pair, shape and height, together.
One Building, Tagged Completely
Walk a simple case end to end: a mid-rise block, six floors of offices over a two-floor retail podium that extends beyond the tower on all sides. The outline covers the podium's full footprint, tagged building=commercial with height for the whole structure (podium plus tower, ground to roof top) and building:levels for its total above-ground floors. A building:part covers the podium alone: its own height (the podium's two floors' worth) and its building:levels of 2. A second building:part covers the tower's footprint: min_height set to the podium's height, height set to the building's total, building:min_level of 2 and the tower's own levels. The tower's part carries roof:shape=flat. Renderers that understand parts now draw a podium with a tower rising from it; renderers that do not fall back to the outline and its total height and draw one honest block. That graceful fallback is the scheme's quiet virtue: detail is additive, and a partially tagged building is a simpler building, never a broken one. Our opening hours guide covers the other tag system every building on the map deserves; a building with hours and a height is a building a stranger can actually use.
Who Draws It: The Renderers
The scheme exists because renderers consume it. The best known is OSM Buildings, the web library that extrudes the tagged city into the isometric skylines embedded in countless sites; F4 Map and other 3D viewers render the same tags with richer materials and lighting; and game and simulation pipelines import the scheme through the standard download and conversion tools. All of them implement the same contract: outline plus parts, heights as truth, levels as texture, roof tags as form. Tag to the contract and every consumer draws your building; invent your own height convention and none of them will. The wiki page is the contract's text, and it is short enough that anyone tagging more than a handful of buildings owes it one careful read, this article having been the invitation rather than the substitute.
Where Heights Come From: Sources a Mapper Can Use
The scheme is only as good as the numbers fed into it, and heights have a hierarchy of sources worth respecting. At the top sit published figures: the documented heights in architecture references, planning documents, and official building records, which arrive with provenance and can be cited in the changeset comment. Next, open elevation and lidar data: many cities and countries now publish lidar-derived building heights as open data, and importing or reading heights from such a dataset (respecting its license and the community's import norms) beats any estimate. Below that, counted levels times a defensible floor height: if you can count the floors from the street or imagery, levels is solid data, and a height estimated from it should be tagged as the levels themselves, letting renderers do the arithmetic openly, rather than dressed up as a measured height it is not. At the bottom, comparison with neighbors: the new block is clearly two floors taller than the tagged building beside it. Estimates are legitimate mapping when they are honest; the sin is false precision, a height written to a decimal that no instrument ever produced. Tag what you know, at the precision you know it, and the 3D city grows on evidence instead of confidence. A note in the changeset about the source ("heights from city open data," "levels counted on survey") is the provenance the next mapper needs, the same courtesy our history guide asks of every edit.
Reading a City in the Scheme: What the Tags Let You See
Step back from the tags and consider what the scheme makes possible as a reading instrument. A district where outlines carry heights but almost no parts is a district of simple slabs; one rich in parts, min_heights, and roof shapes is a district of podiums, setbacks, and pitched roofs, and the difference is visible in the tag statistics before any renderer draws a pixel. Planners mine exactly this: shadow studies need heights, skyline protection needs the roof family, floor-space estimates need levels disciplined by heights. All of that analysis drinks from tags that individual mappers added one building at a time, most of them thinking only of making the 3D view look right. That is the recurring miracle of this data model, the same one our PBF and history guides keep meeting from other sides: small, well-specified contributions, made for local reasons, compose into infrastructure strangers build cities' worth of reasoning on. Tag one building completely and you have improved a skyline. Tag a street of them and you have improved a dataset. The scheme is the contract that lets both be true at once.
Related Guides
If this page answered part of the question, these GIS guides cover the rest of the same ground:
- OpenStreetMap Opening Hours: The opening_hours Grammar, Decoded: The other essential building tag system, when it is open rather than how tall it is.
- OpenStreetMap uMap: Layers, Imports, and a Backup: Showing buildings and their data on a custom map of your own.
- OpenStreetMap History: Versions, Changesets, and Recovery: Reading who tagged a building's height, and when.
- OpenStreetMap Download: Get the Data Behind the Map: The building data in bulk, heights included, for your own rendering.
Frequently Asked Questions
How is building height measured in OpenStreetMap?
The height tag is the distance in meters from the ground to the top of the roof, excluding antennas, spires, and similar attachments. Tag the measured or published height where you know it; it is a measurement, not an estimate derived from floor counts.
What is the difference between height and building:levels?
Height is the true measurement a renderer extrudes by. Building:levels counts the floors above ground (roof levels excluded) and serves as a texture hint for facades. Tag height wherever possible and use levels in addition, never as a substitute, because renderers guess floor heights differently and a levels-only building changes size from map to map.
When do I use building:part?
When part of a building differs from the whole: a tower on a podium, an annex, a section with its own roof. Each part is its own outline tagged building:part, with its own height and, for raised parts, min_height and building:min_level. Simple one-box buildings need no parts.
What does min_height mean?
It is the height at which a building part begins above the ground: a section spanning a plaza, or the upper block above a podium. A part with min_height 12 and height 30 occupies the space between 12 and 30 meters, with open air beneath it in the model.
How do I tag a roof's shape?
Use roof:shape on the outline or part (flat, gabled, hipped, pyramidal, dome, and other documented values), together with roof:height for the height of the roof section itself. Roof:height is a portion of the building's total height, not an addition to it.
Photo credits: Miguel Moreira (Pexels); Masood Aslami (Pexels). Photos are served from this site; follow the credit to the library page for the original.