> For the complete documentation index, see [llms.txt](https://cityweft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cityweft.gitbook.io/docs/basics/metadata-descriptors.md). # Metadata (Descriptors) This page describes the descriptor objects returned in the API response ### What are Descriptors? Each geometry feature (building, surface, barrier, or infrastructure instance) in the API response includes a `descriptor` object that contains metadata about that object. The descriptor provides detailed information that you can use to: * **Identify and categorize features**: Determine what type of building, surface, or infrastructure element you're working with * **Apply appropriate styling**: Use material types, colors, and other visual properties to render features correctly * **Filter and query**: Select specific feature types (e.g., only residential buildings, only roads, only trees) based on descriptor properties * **Enhance visualization**: Use roof types, facade materials, and other architectural details for realistic rendering * **Describe buildings**: Show address, use, year built and other facts about a building * **Trace quality**: See which Cityweft data tier a feature came from and how reliable its dimensions are All metadata is available in the `descriptor` property of each mesh (for buildings, surfaces, and barriers) or node (for infrastructure instances). ### Descriptor Reference #### Building Descriptors Building descriptors are found in `geometry[].meshes[].descriptor` when `type === "buildings"`. **Building Type Properties** | Property | Type | Description | | -------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `string` | ๐Ÿข Building type identifier. | | `id` | `number \| string?` | ๐Ÿ†” Unique building identifier | | `label` | `string?` | ๐Ÿท๏ธ Building name, when known | | `buildingName` | `string?` | ๐Ÿท๏ธ Building name from source data | | `buildingType` | `string \| null?` | ๐Ÿ˜๏ธ Building category code. Lowercase values such as "residential", "apartments", "house", "commercial", "industrial", "retail", "office", "school", "hospital"; `null` or absent when the source data doesn't say. Stable for filtering โ€” for display text use the Building Description fields below. | | `datasetName` | `string?` | ๐Ÿ“Š Cityweft data tier this building came from (see table below) | | `heightBasis` | `string?` | ๐Ÿ“ How the height was obtained: `'measured'` (from survey data), `'mapped'` (explicitly recorded in source data), `'derived'` (calculated from levels), `'estimated'` (default assumption) | | `levelsBasis` | `string?` | ๐Ÿ  How the level count was obtained: `'mapped'`, `'derived'`, or `'estimated'` | | `roofBasis` | `string?` | ๐Ÿš๏ธ How the roof shape was obtained: `'measured'` (from survey data), `'mapped'` (recorded in source data), `'estimated'` (default roof type) | **Dataset tiers** The `datasetName` value tells you which Cityweft data tier produced a building: | Value | Meaning | | ---------------------------------------- | ------------------------------------------------------------------- | | `Global Buildings - Mapped` | Worldwide base data with mapped footprints | | `Global Buildings - Estimated` | Worldwide footprints detected by machine learning | | `Europe Buildings - Measured` | European footprints with measured heights from governmental sources | | `Premium Buildings - Detailed` | Premium country dataset at full roof detail | | `Premium Buildings - Simple` | Premium country dataset with measured heights on simplified massing | See [Customizations](/docs/basics/customizations.md#building-data-sources) for how to control which tiers are used. **Building Dimensions** | Property | Type | Description | | -------------------- | --------- | ---------------------------------------------------- | | `buildingLevels` | `number?` | Number of above-ground floors | | `buildingHeight` | `number?` | Total height in meters | | `buildingMinHeight` | `number?` | Height of base/bottom in meters | | `buildingRoofHeight` | `number?` | Height of roof section in meters | | `originalHeight` | `number?` | Original height from data source before calculations | **Building Description** Facts about the building in plain English, ready to display. Each field is present only when the underlying data records it, so coverage varies by area: Premium datasets carry the most (use, year built, dwellings and materials for most buildings in many countries), while Global Buildings tiers mostly carry only `buildingType` and `label`. Values are display text and can differ between countries โ€” filter on `buildingType` instead. | Property | Type | Description | Example | | --------------------------- | --------- | --------------------------------------------------------------------- | --------------------------------------------------- | | `address` | `string?` | One-line postal address, formatted for the building's country | `"801 South Plymouth Court, Chicago, IL 60605"` | | `buildingUse` | `string?` | What the building is used for | `"Residential"`, `"Hotel"`, `"Single-family house"` | | `buildingSecondaryUse` | `string?` | Secondary use, where recorded | `"Commercial & services"` | | `yearBuilt` | `number?` | Year of construction | `1890` | | `dwellings` | `number?` | Number of dwellings | `30` | | `buildingUnits` | `number?` | Number of separately registered units | `14` | | `floorArea` | `number?` | Gross floor area in mยฒ | `2202` | | `footprintArea` | `number?` | Footprint area in mยฒ | `780` | | `buildingLevelsUnderground` | `number?` | Number of floors below ground | `1` | | `wallMaterial` | `string?` | Wall material as recorded in the source data | `"Stone"`, `"Brick"` | | `roofCovering` | `string?` | Roof covering as recorded in the source data | `"Slate"`, `"Zinc or aluminium"` | | `architect` | `string?` | Architect | `"Jacques-Germain Soufflot"` | | `operator` | `string?` | Organisation operating the building | `"University of Oxford"` | | `heritage` | `string?` | Heritage protection: `"Listed"`, or the listing grade where recorded | `"Listed"`, `"Grade II"` | | `buildingStatus` | `string?` | Lifecycle state โ€” present only when the building is not in normal use | `"Under construction"`, `"Disused"`, `"Ruin"` | | `website` | `string?` | Website of the building or its occupant | `"https://www.example.com/"` | | `wikipedia` | `string?` | Wikipedia article URL | `"https://en.wikipedia.org/wiki/Dearborn_Station"` | `wallMaterial` and `roofCovering` describe the real materials where known; `buildingFacadeMaterial` and `buildingRoofMaterial` (below) are coarse classes intended for rendering. **Building Roof Properties** | Property | Type | Description | Values | | ------------------------- | --------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buildingRoofType` | `string?` | Roof shape/style | `'flat'`, `'hipped'`, `'gabled'`, `'gambrel'`, `'pyramidal'`, `'onion'`, `'dome'`, `'round'`, `'skillion'`, `'mansard'`, `'quadrupleSaltbox'`, `'saltbox'` | | `buildingRoofOrientation` | `string?` | Roof ridge orientation | `'along'` (ridge along building length), `'across'` (ridge across building width) | | `buildingRoofDirection` | `number?` | Direction/bearing of roof ridge in radians | 0-2ฯ€ | | `buildingRoofAngle` | `number?` | Angle/slope of roof in radians | 0-ฯ€/2 | | `buildingRoofMaterial` | `string?` | Roof material | `'default'`, `'tiles'`, `'metal'`, `'concrete'`, `'thatch'`, `'eternit'`, `'grass'`, `'glass'`, `'tar'` | | `buildingRoofColor` | `number?` | Roof color (numeric color value) | RGB/hex encoded | **Building Facade Properties** | Property | Type | Description | Values | | ------------------------ | ---------- | --------------------------------------- | ------------------------------------------------------------ | | `buildingFacadeMaterial` | `string?` | Facade material | `'plaster'`, `'brick'`, `'wood'`, `'glass'`, `'cementBlock'` | | `buildingFacadeColor` | `number?` | Facade color (numeric color value) | RGB/hex encoded | | `buildingWindows` | `boolean?` | Whether building has windows | `true`/`false` | | `buildingFoundation` | `boolean?` | Whether building has visible foundation | `true`/`false` | **Building Additional Properties** | Property | Type | Description | | -------- | --------- | ------------------------------ | | `zIndex` | `number?` | Rendering order (added by API) | *** #### Surface Descriptors Surface descriptors are found in `geometry[].meshes[].descriptor` when `type === "surface"`. **Surface Types** | Type | Description | Additional Properties | | ----------------------- | --------------------------------- | -------------------------------------------------------------------------------------- | | `'asphalt'` | ๐Ÿ›ฃ๏ธ Asphalt surface | - | | `'roadwayIntersection'` | ๐Ÿšฆ Road intersection | `intersectionMaterial` | | `'pavement'` | ๐Ÿšถ Sidewalk/pedestrian pavement | - | | `'water'` | ๐Ÿ’ง Water body | - | | `'farmland'` | ๐ŸŒพ Agricultural land | - | | `'grass'` | ๐ŸŒฑ Grass area | - | | `'sand'` | ๐Ÿ–๏ธ Sand area | - | | `'rock'` | ๐Ÿชจ Rock area | - | | `'pitch'` | โšฝ Sports field | `pitchType` | | `'manicuredGrass'` | โ›ณ Manicured/well-maintained grass | - | | `'helipad'` | ๐Ÿš Helicopter landing pad | - | | `'forest'` | ๐ŸŒฒ Forest area | `treeType` | | `'garden'` | ๐ŸŒณ Garden area | - | | `'construction'` | ๐Ÿ—๏ธ Construction site | - | | `'shrubbery'` | ๐ŸŒฟ Shrubbery/bushes | - | | `'roadwayArea'` | ๐Ÿ›ฃ๏ธ Roadway surface area | - | | `'path'` | ๐Ÿ›ฃ๏ธ Path/road | `pathType`, `pathMaterial`, `lanesForward`, `lanesBackward`, `isRoadwayMarked`, `side` | | `'waterway'` | ๐Ÿ’ง Waterway/canal | - | **Surface Properties**
| Property | Type | Description | Used With | Values | | ---------------------- | ---------- | ------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- | | `type` | `string` | Surface type (see table above) | All surfaces | See Surface Types table above | | `label` | `string?` | Surface label/name | All surfaces | Any string | | `intersectionMaterial` | `string?` | Surface material for intersections | `'roadwayIntersection'` | `'asphalt'`, `'concrete'`, `'cobblestone'` | | `pitchType` | `string?` | Type of sports field | `'pitch'` | `'generic'`, `'football'`, `'basketball'`, `'tennis'` | | `treeType` | `string?` | Tree species/type | `'forest'` | `'genericBroadleaved'`, `'genericNeedleleaved'`, `'beech'`, `'fir'`, `'linden'`, `'oak'` | | `pathType` | `string?` | Type of path | `'path'` | `'roadway'`, `'footway'`, `'cycleway'`, `'railway'`, `'tramway'`, `'runway'` | | `pathMaterial` | `string?` | Surface material for paths | `'path'` | `'asphalt'`, `'concrete'`, `'dirt'`, `'sand'`, `'gravel'`, `'cobblestone'`, `'wood'` | | `isRoadwayMarked` | `boolean?` | Whether roadway has lane markings | `'path'` with `pathType === 'roadway'` | `true`, `false` | | `lanesForward` | `number?` | Number of lanes in forward direction | `'path'` with `pathType === 'roadway'` | Positive number | | `lanesBackward` | `number?` | Number of lanes in backward direction | `'path'` with `pathType === 'roadway'` | Positive number | | `side` | `string?` | Which side of path the feature is on | `'path'` | `'both'`, `'left'`, `'right'` | | `width` | `number?` | Width in meters | `'path'`, `'waterway'` | Positive number (meters) | | `height` | `number?` | Height in meters | `'waterway'` | Positive number (meters) | | `minHeight` | `number?` | Minimum/base height in meters | `'path'`, `'waterway'` | Number (meters) | | `zIndex` | `number?` | Rendering order (added by API) | All surfaces | Number | *** #### Surface Line Descriptors Polylines in the `surfaceLines` group (see [Surface Lines](/docs/geometry/surface-lines.md)) reuse the **same `type` taxonomy as surface meshes** (`path`, `water`, `pitch`, โ€ฆ) so linework can share the surface layer structure. One extra property distinguishes the representation: | Property | Type | Description | Values | | ---------- | -------- | ----------------------------------------------------------------------------------------------------- | ----------------------------- | | `lineRole` | `string` | Whether the polyline is a feature centerline or an outline/boundary ring of the corresponding surface | `'centerline'` \| `'outline'` | *** #### Barrier Descriptors Barrier descriptors are found in `geometry[].meshes[].descriptor` when `type === "barriers"`. **Note:** Barriers (walls, fences) are linear features (polylines) that have been converted to meshes. Paths and waterways are included in the `surface` geometry type. **Barrier Types** | Type | Description | Additional Properties | | --------- | ----------- | --------------------- | | `'fence'` | ๐Ÿšง Fence | `fenceMaterial` | | `'wall'` | ๐Ÿงฑ Wall | `wallType` | **Wall Properties (when `type === 'wall'`)** | Property | Type | Description | Values | | ---------- | --------- | ------------------ | ---------------------------------- | | `wallType` | `string?` | Wall material type | `'stone'`, `'concrete'`, `'hedge'` | **Fence Properties (when `type === 'fence'`)** | Property | Type | Description | Values | | --------------- | --------- | -------------- | ------------------------------------------------ | | `fenceMaterial` | `string?` | Fence material | `'wood'`, `'chainLink'`, `'metal'`, `'concrete'` | *** #### Infrastructure Descriptors (Instances) Infrastructure descriptors are found in `geometry[].nodes[].descriptor` when `type === "instances"`. Infrastructure features are point instances (nodes) that represent discrete objects at specific coordinates. **Infrastructure Types** | Type | Description | Additional Properties | | --------------------- | ------------------------------- | -------------------------------------------------- | | `'tree'` | ๐ŸŒฒ Individual tree | `treeType`, `height`, `minHeight`, `crownDiameter` | | `'rock'` | ๐Ÿชจ Rock formation | `height`, `minHeight` | | `'hydrant'` | ๐Ÿš’ Fire hydrant | `height`, `minHeight` | | `'transmissionTower'` | โšก Electrical transmission tower | `height`, `minHeight` | | `'utilityPole'` | ๐Ÿ“ก Utility/power pole | `height`, `minHeight` | | `'artwork'` | ๐ŸŽจ Art installation | `height`, `minHeight`, `direction` | | `'adColumn'` | ๐Ÿ“ข Advertisement column | `height`, `minHeight` | | `'windTurbine'` | ๐Ÿ’จ Wind turbine | `height`, `minHeight` | | `'bench'` | ๐Ÿช‘ Bench/seating | `height`, `minHeight` | | `'picnicTable'` | ๐Ÿงบ Picnic table | `height`, `minHeight` | | `'busStop'` | ๐Ÿ›‘ Bus stop | `height`, `minHeight` | | `'memorial'` | ๐Ÿ—ฟ Memorial monument | `height`, `minHeight`, `direction` | | `'statue'` | ๐Ÿ—ฝ Statue | `height`, `minHeight`, `direction` | | `'sculpture'` | ๐ŸŽญ Sculpture | `height`, `minHeight`, `direction` | **Infrastructure Properties**
| Property | Type | Description | Used With | Values | | --------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `type` | `string?` | Infrastructure type (see table above) | All instances | See Infrastructure Types table | | `treeType` | `string?` | Tree species/type | `'tree'` | `'genericBroadleaved'`, `'genericNeedleleaved'`, `'beech'`, `'fir'`, `'linden'`, `'oak'` | | `height` | `number?` | Height in meters | All instances | Positive number (meters) | | `minHeight` | `number?` | Minimum/base height in meters | All instances | Number (meters) | | `crownDiameter` | `number?` | Measured crown width in meters (detected trees; see [Trees & Vegetation](/docs/geometry/infrastructure/trees-and-vegetation.md)) | `'tree'` | Positive number (meters) | | `direction` | `number?` | Orientation/direction in radians | `'memorial'`, `'statue'`, `'sculpture'`, `'artwork'` | 0-2ฯ€ (radians) | **Instance Node Structure** Each infrastructure instance in the `nodes` array has the following structure: ```json { "x": 123.45, "y": 67.89, "z": 10.0, "instanceType": "tree", "scale": 1.0, "rotation": 0.0, "descriptor": { "type": "tree", "treeType": "oak", "height": 15.0, "minHeight": 0.0 } } ``` *** ### Attributions Every response also carries a top-level `attributions` array โ€” the credit lines for the data behind the scene: ```json "attributions": [ { "id": "source-id", "name": "Data source name", "text": "Credit line to display", "license": "License name", "url": "https://...", "required": true } ] ``` Render the `text` lines verbatim wherever you display or redistribute the output. Entries with `required: true` are license conditions of the underlying data; `required: false` marks courtesy credits. *** ### Type Correlations Summary Certain descriptor properties are only relevant for specific types: * **`treeType`** โ†’ Used with `type: 'tree'` (infrastructure) and `type: 'forest'` (surface) * **`wallType`** โ†’ Used with `type: 'wall'` (barriers) * **`fenceMaterial`** โ†’ Used with `type: 'fence'` (barriers) * **`pathType`** โ†’ Used with `type: 'path'` (surface) * **`pathMaterial`** โ†’ Used with `type: 'path'` (surface) * **`pitchType`** โ†’ Used with `type: 'pitch'` (surface) * **`intersectionMaterial`** โ†’ Used with `type: 'roadwayIntersection'` (surface) * **`lineRole`** โ†’ Used with polylines in the `surfaceLines` group * **`building*` fields** โ†’ Used with `type: 'building'` or `type: 'buildingPart'` (buildings) * **Building description fields** (`address`, `yearBuilt`, `dwellings`, `floorArea`, `footprintArea`, `wallMaterial`, `roofCovering`, `architect`, `operator`, `heritage`, `website`, `wikipedia`) โ†’ Buildings only