Create building features
You are viewing in-progress documentation for v2. Switch to the stable version for the current production release.
A building feature holds building footprint polygons for a domain. Each
source of footprints has its own endpoint under features/building/, and each
section below covers one source. To upload your own footprints, or to combine
them with fetched ones, see
Upload your own road, water and building features.
For what a feature is and how grids and inventories use one, see
About features.
Prerequisites
Section titled “Prerequisites”-
An API key: my-api-key. See Create a Personal API Key.
-
A domain: your-domain-id. See Create a domain. Footprints are clipped to this domain and stored in its CRS.
Create building features from Overture Maps
Section titled “Create building features from Overture Maps”Overture Maps publishes building footprints
combined from several datasets, among them OpenStreetMap and Microsoft ML
Buildings. To fetch them for your domain, POST to
features/building/overture. Every body field is optional: name,
description, tags, and extent_buffer_m.
curl -X 'POST' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/building/overture' \ -H 'accept: application/json' \ -H 'api-key: my-api-key' \ -H 'Content-Type: application/json' \ -d '{ "name": "Overture buildings"}'import fastfuels_sdk.v2 as ff
ff.set_api_key("my-api-key")
domain = ff.Domain.from_id("your-domain-id")
building = ff.features.create_building_feature_from_overture( domain, name="Overture buildings"){ "id": "your-building-feature-id", "domain_id": "your-domain-id", "type": "building", "name": "Overture buildings", "description": "", "status": "pending", "progress": null, "created_on": "2026-11-06T18:55:15.217467", "modified_on": "2026-11-06T18:55:15.217467", "source": { "product": "overture", "description": "Overture Maps building footprints", "extent_buffer_m": 0.0, "release": null }, "georeference": null, "error": null, "tags": [], "attributions": []}The 201 mints a feature id. Record it: your-building-feature-id.
Status starts pending, and source.release stays null until the job reads
the footprints.
Poll until completed
Section titled “Poll until completed”Poll the feature, or wait() on it:
curl -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/your-building-feature-id' \ -H 'accept: application/json' \ -H 'api-key: my-api-key'building.wait()print(building.source["release"]){ "id": "your-building-feature-id", "domain_id": "your-domain-id", "type": "building", "name": "Overture buildings", "description": "", "status": "completed", "progress": { "percent": 100, "message": "Complete" }, "created_on": "2026-11-06T18:55:15.217467Z", "modified_on": "2026-11-06T18:55:16.915654Z", "source": { "description": "Overture Maps building footprints", "product": "overture", "extent_buffer_m": 0.0, "release": "2026-10-21.0" }, "georeference": { "crs": "EPSG:32611", "bounds": [ 717141.6556112946, 5326524.549818624, 718694.8955395881, 5328248.228078655 ] }, "error": null, "tags": [], "attributions": [ { "dataset": "Overture Maps Foundation", "license_name": "ODbL-1.0", "license_url": "https://opendatacommons.org/licenses/odbl/1-0/", "citation": "© OpenStreetMap contributors, Overture Maps Foundation", "access_url": "https://docs.overturemaps.org/attribution/", "accessed_on": "2026-11-06" }, { "dataset": "Microsoft ML Buildings", "license_name": "ODbL-1.0", "license_url": "https://opendatacommons.org/licenses/odbl/1-0/", "citation": "Microsoft Global ML Building Footprints", "access_url": "https://github.com/microsoft/GlobalMLBuildingFootprints", "accessed_on": "2026-11-06" }, { "dataset": "OpenStreetMap", "license_name": "ODbL-1.0", "license_url": "https://opendatacommons.org/licenses/odbl/1-0/", "citation": "© OpenStreetMap contributors", "access_url": "https://www.openstreetmap.org/copyright", "accessed_on": "2026-11-06" } ]}Status walks pending → running → completed. The completed feature records
two things about its source:
source.releasenames the Overture release that was read. Each request reads the latest release, so a feature created after Overture publishes a new release can hold different footprints. To keep the same footprints, keep using the same feature id.attributionslists Overture Maps and each dataset the footprints came from, with its license. The data is licensed under ODbL. Reproduce eachcitationwherever you show or share the footprints.
Check the footprint count
Section titled “Check the footprint count”curl -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/your-building-feature-id/data/metadata' \ -H 'accept: application/json' \ -H 'api-key: my-api-key'metadata = building.get_data_metadata()print(metadata.total_features){ "total_features": 524, "partition_count": 1, "partitions": [ { "index": 0, "num_features": 524 } ]}On the Bigfork domain, release 2026-10-21.0 returns 524 footprints in one
partition. A domain with no buildings gives a completed feature with
total_features: 0. A grid or inventory rule that references an empty feature
still completes, but selects nothing with within or intersects and
everything with outside, so check the count before you use the feature.
Read the footprints
Section titled “Read the footprints”GET .../data/{partition_index} returns one partition as GeoJSON in the
domain CRS. Iterate partition_index from 0 to partition_count - 1. In the
SDK, to_geodataframe() reads every partition.
curl -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/your-building-feature-id/data/0' \ -H 'accept: application/geo+json' \ -H 'api-key: my-api-key'footprints = building.to_geodataframe()print(footprints[["height", "height_source", "source_dataset"]].head()){ "type": "FeatureCollection", "features": [ { "id": "0", "type": "Feature", "properties": { "height": 4.0, "height_source": "OpenStreetMap", "source_dataset": "OpenStreetMap" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717901.5302831826, 5326614.670838669], [717889.6255953972, 5326612.026062051], [717889.4560343017, 5326621.791060623], [717900.4678999044, 5326621.619612892], [717901.5302831826, 5326614.670838669] ] ] } }, { "id": "23", "type": "Feature", "properties": { "height": 4.003058910369873, "height_source": "Microsoft ML Buildings", "source_dataset": "OpenStreetMap" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717974.2291922779, 5326859.73893004], [717955.3823156228, 5326858.966906492], [717954.8715566573, 5326871.423346645], [717973.7183922974, 5326872.195369771], [717974.2291922779, 5326859.73893004] ] ] } }, { "id": "22", "type": "Feature", "properties": { "height": null, "height_source": null, "source_dataset": "Microsoft ML Buildings" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717880.7025544842, 5326750.45708962], [717877.3752392847, 5326749.662918775], [717875.3365466406, 5326758.1549491985], [717878.6638570055, 5326758.949119012], [717880.7025544842, 5326750.45708962] ] ] } } ], "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::32611" } }}Every building feature has the same columns, whatever its source:
| Column | Holds |
|---|---|
geometry | The footprint polygon, in the domain CRS. |
height | Building height in m, or null when no dataset records one. |
height_source | The dataset that supplied height, or null with no height. |
source_dataset | The dataset that supplied the footprint. |
height_source and source_dataset can differ. On the Bigfork domain, 454
footprints come from OpenStreetMap and 70 from Microsoft ML Buildings. 402
footprints have a height, and 318 of those are OpenStreetMap footprints with a
height from Microsoft ML Buildings. The other 122 have no height. If you use
height, filter or fill the rows where it is null.
Keep buildings whole at the domain edge
Section titled “Keep buildings whole at the domain edge”Footprints are clipped to the domain, so a building that crosses the boundary
is cut at it. To keep such buildings whole, set extent_buffer_m (0 to 100 m).
The footprints are then clipped to the domain grown by that distance, and
buildings within that distance outside the domain are included too.
curl -X 'POST' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/building/overture' \ -H 'accept: application/json' \ -H 'api-key: my-api-key' \ -H 'Content-Type: application/json' \ -d '{ "name": "Overture buildings, 20 m past the edge", "extent_buffer_m": 20}'import fastfuels_sdk.v2 as ff
ff.set_api_key("my-api-key")
domain = ff.Domain.from_id("your-domain-id")
building = ff.features.create_building_feature_from_overture( domain, name="Overture buildings, 20 m past the edge", extent_buffer_m=20)building.wait()On the Bigfork domain, 4 footprints are cut at the edge without a buffer. With
extent_buffer_m: 20 all 4 come back whole, and 13 buildings that lie
outside the domain are added, for 537 footprints.
Common pitfalls
Section titled “Common pitfalls”- Using
heightwithout checking for nulls. A footprint keeps its row when no dataset records a height, soheightandheight_sourcearenullfor some rows. - Re-creating the feature to get the same footprints. A new request reads
the latest Overture release, which can differ from the one an existing
feature recorded in
source.release. Reference the existing feature id instead.
Next steps
Section titled “Next steps”- Remove surface fuel under roads, water and buildings to zero surface fuel inside the footprints.
- Remove trees with road, water and building features to drop CHM detections that fall on rooftops.