Skip to content

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.

  1. An API key: my-api-key. See Create a Personal API Key.

  2. 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.

POST building/overture
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"
}'

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 the feature, or wait() on it:

GET feature status
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'

Status walks pending → running → completed. The completed feature records two things about its source:

  • source.release names 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.
  • attributions lists Overture Maps and each dataset the footprints came from, with its license. The data is licensed under ODbL. Reproduce each citation wherever you show or share the footprints.
GET building data/metadata
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'

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.

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.

GET building data/0
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'

Every building feature has the same columns, whatever its source:

ColumnHolds
geometryThe footprint polygon, in the domain CRS.
heightBuilding height in m, or null when no dataset records one.
height_sourceThe dataset that supplied height, or null with no height.
source_datasetThe 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.

Domain OpenStreetMap Microsoft ML Buildings
Overture footprints on the Bigfork domain (white outline), release 2026-10-21.0, by source dataset: OpenStreetMap (yellow) and Microsoft ML Buildings (cyan). Click a footprint to see its columns.

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.

POST building/overture — 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, 20 m past the edge",
"extent_buffer_m": 20
}'

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.

  • Using height without checking for nulls. A footprint keeps its row when no dataset records a height, so height and height_source are null for 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.