Upload your own road, water and building features
You are viewing in-progress documentation for v2. Switch to the stable version for the current production release.
POST /domains/{domain_id}/features/{type}/geojson creates a road, water or
building feature from polygons you supply. POST /domains/{domain_id}/features/{type}/concatenate combines features of one type
into a new feature, so a single rule can reference fetched and uploaded
geometry together. For how uploaded and combined features relate to fetched
ones, 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. Uploaded polygons are clipped to this domain and stored in its CRS.
-
The polygons to upload, as a GeoJSON FeatureCollection: footprints from a county GIS layer, a survey, or your own digitizing.
-
To combine the upload with fetched features, a completed feature of the same type in that domain. The examples combine buildings with an Overture building feature: your-overture-building-feature-id. See Create building features, or Create road and water features from OpenStreetMap for roads and water.
-
To use the combined feature in a fuel rule, a completed FBFM40 grid in that domain: your-fbfm40-grid-id. See Build surface fuel grids from LANDFIRE. The examples use a 2 m grid with
remove_non_burnable: ["NB1"], as in Remove surface fuel under roads, water and buildings.
The examples use the Bigfork, Montana domain. Its Overture building feature,
release 2026-10-21.0, holds 524 footprints.
Upload polygons as a feature
Section titled “Upload polygons as a feature”To upload polygons, POST a GeoJSON FeatureCollection to
features/building/geojson, features/road/geojson or
features/water/geojson. The path sets the feature’s type. Next to type
and features, the body takes the optional name, description, tags and
extent_buffer_m. Here the FeatureCollection holds three houses that the
Overture feature lacks, digitized from 2025 NAIP imagery.
curl -X 'POST' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/building/geojson' \ -H 'accept: application/json' \ -H 'api-key: my-api-key' \ -H 'Content-Type: application/json' \ -d '{ "type": "FeatureCollection", "name": "Houses missing from Overture", "features": [ { "type": "Feature", "properties": {"source_dataset": "Digitized from NAIP 2025"}, "geometry": { "type": "Polygon", "coordinates": [[ [-114.078864, 48.056179], [-114.078869, 48.056081], [-114.078843, 48.056066], [-114.078749, 48.056068], [-114.078655, 48.056075], [-114.078625, 48.056133], [-114.078649, 48.056176], [-114.078864, 48.056179] ]] } }, { "type": "Feature", "properties": {"source_dataset": "Digitized from NAIP 2025"}, "geometry": { "type": "Polygon", "coordinates": [[ [-114.078685, 48.056414], [-114.078693, 48.05635], [-114.07872, 48.056347], [-114.078724, 48.056277], [-114.078485, 48.056233], [-114.07848, 48.056325], [-114.078573, 48.056337], [-114.07857, 48.056392], [-114.078685, 48.056414] ]] } }, { "type": "Feature", "properties": {"source_dataset": "Digitized from NAIP 2025"}, "geometry": { "type": "Polygon", "coordinates": [[ [-114.077719, 48.056555], [-114.077741, 48.056518], [-114.077709, 48.056439], [-114.077594, 48.056412], [-114.077481, 48.056411], [-114.077456, 48.056427], [-114.077426, 48.056464], [-114.077473, 48.056487], [-114.077463, 48.05653], [-114.077582, 48.056562], [-114.077719, 48.056555] ]] } } ]}'import fastfuels_sdk.v2 as ff
ff.set_api_key("my-api-key")
domain = ff.Domain.from_id("your-domain-id")
houses = { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": {"source_dataset": "Digitized from NAIP 2025"}, "geometry": { "type": "Polygon", "coordinates": [ [ [-114.078864, 48.056179], [-114.078869, 48.056081], [-114.078843, 48.056066], [-114.078749, 48.056068], [-114.078655, 48.056075], [-114.078625, 48.056133], [-114.078649, 48.056176], [-114.078864, 48.056179], ] ], }, }, { "type": "Feature", "properties": {"source_dataset": "Digitized from NAIP 2025"}, "geometry": { "type": "Polygon", "coordinates": [ [ [-114.078685, 48.056414], [-114.078693, 48.05635], [-114.07872, 48.056347], [-114.078724, 48.056277], [-114.078485, 48.056233], [-114.07848, 48.056325], [-114.078573, 48.056337], [-114.07857, 48.056392], [-114.078685, 48.056414], ] ], }, }, { "type": "Feature", "properties": {"source_dataset": "Digitized from NAIP 2025"}, "geometry": { "type": "Polygon", "coordinates": [ [ [-114.077719, 48.056555], [-114.077741, 48.056518], [-114.077709, 48.056439], [-114.077594, 48.056412], [-114.077481, 48.056411], [-114.077456, 48.056427], [-114.077426, 48.056464], [-114.077473, 48.056487], [-114.077463, 48.05653], [-114.077582, 48.056562], [-114.077719, 48.056555], ] ], }, }, ],}
uploaded = ff.features.create_building_feature_from_geojson( domain, houses, name="Houses missing from Overture")print(uploaded.id, uploaded.status){ "id": "your-uploaded-building-feature-id", "domain_id": "your-domain-id", "type": "building", "name": "Houses missing from Overture", "description": "", "status": "completed", "progress": null, "created_on": "2026-11-16T16:37:31.551234Z", "modified_on": "2026-11-16T16:37:31.551234Z", "source": { "product": "geojson", "description": "User-uploaded GeoJSON", "extent_buffer_m": 0.0 }, "georeference": { "crs": "EPSG:32611", "bounds": [ 717141.6556112946, 5326524.549818624, 718694.8955395881, 5328248.228078655 ] }, "error": null, "tags": [], "attributions": []}The feature is stored during the request, so the 201 returns it
completed. Record its id: your-uploaded-building-feature-id.
- Geometry. Each feature is a
PolygonorMultiPolygon. Draw roads and driveways as footprints the width of the road, not as centerlines. - CRS. Coordinates are read in the CRS named by the FeatureCollection’s
crsblock. Without one, as here, they are read as longitude and latitude (EPSG:4326). Any CRS is accepted, and the polygons are reprojected to the domain’s CRS. For coordinates in the Bigfork domain’s UTM zone, the block is"crs": {"type": "name", "properties": {"name": "EPSG:32611"}}. - Clipping. Polygons are clipped to the domain, so a polygon that crosses
the domain edge is cut at it, and one wholly outside the domain is dropped.
To keep polygons whole up to 100 m past the edge, set
extent_buffer_m. - Properties. Properties are optional. Each one becomes a column of the
feature’s data. A property holds one type across all features, and none can
be named
geometry. georeference.boundsis the extent of the domain, grown byextent_buffer_m, not the extent of the polygons.
In the Python SDK, create_road_feature_from_geojson,
create_water_feature_from_geojson and
create_building_feature_from_geojson upload a FeatureCollection. The
_from_geodataframe versions upload a GeoDataFrame and send its CRS in the
crs block.
Check what was stored
Section titled “Check what was stored”total_features counts the polygons the feature holds after clipping:
curl -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/your-uploaded-building-feature-id/data/metadata' \ -H 'accept: application/json' \ -H 'api-key: my-api-key'metadata = uploaded.get_data_metadata()print(metadata.total_features){ "total_features": 3, "partition_count": 1, "partitions": [ { "index": 0, "num_features": 3 } ]}All three houses lie inside the domain, so the feature holds 3 polygons. A count lower than the number you uploaded means some polygons lay outside the domain.
GET .../data/{partition_index} returns the stored polygons as GeoJSON in the
domain’s CRS, EPSG:32611 here, with each property as a column. In the SDK,
to_geodataframe() reads every partition.
curl -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/your-uploaded-building-feature-id/data/0' \ -H 'accept: application/geo+json' \ -H 'api-key: my-api-key'rows = uploaded.to_geodataframe()print(rows.crs)print(rows[["source_dataset", "geometry"]]){ "type": "FeatureCollection", "features": [ { "id": "0", "type": "Feature", "properties": { "source_dataset": "Digitized from NAIP 2025" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717673.0076616996, 5326673.234831276], [717674.9771499757, 5326668.524042196], [717672.9866794341, 5326661.993566813], [717666.0127944023, 5326660.94981969], [717659.0178175371, 5326660.4617393715], [717657.0174342298, 5326662.055191791], [717656.9765972904, 5326672.960232516], [717673.0076616996, 5326673.234831276] ] ] } }, { "id": "1", "type": "Feature", "properties": { "source_dataset": "Digitized from NAIP 2025" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717677.9823255951, 5326697.462681448], [717677.990824919, 5326691.3419564245], [717684.9703191747, 5326690.27138983], [717684.9859015446, 5326680.033137337], [717666.9938103566, 5326684.247032165], [717666.9965549954, 5326692.037559499], [717668.9955080326, 5326692.447308417], [717669.321573648, 5326699.582357766], [717677.9823255951, 5326697.462681448] ] ] } }, { "id": "2", "type": "Feature", "properties": { "source_dataset": "Digitized from NAIP 2025" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717750.8748265003, 5326719.149653565], [717759.8758030459, 5326715.930100324], [717759.3122252043, 5326711.1231484655], [717762.9109638233, 5326708.700090365], [717760.8319896937, 5326704.503345133], [717759.0369125744, 5326702.654510779], [717750.6137535725, 5326702.445958974], [717741.9318764769, 5326705.121184503], [717739.2144054155, 5326713.810060447], [717740.6973612444, 5326717.984166454], [717750.8748265003, 5326719.149653565] ] ] } } ], "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::32611" } }}Combine uploaded and fetched features
Section titled “Combine uploaded and fetched features”To combine features of one type, POST their ids to
features/building/concatenate, features/road/concatenate or
features/water/concatenate. Here the Overture footprints and the uploaded
houses become one building feature.
curl -X 'POST' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/features/building/concatenate' \ -H 'accept: application/json' \ -H 'api-key: my-api-key' \ -H 'Content-Type: application/json' \ -d '{ "source_feature_ids": [ "your-overture-building-feature-id", "your-uploaded-building-feature-id" ], "name": "Overture and uploaded buildings"}'buildings = ff.features.concatenate_building_features( domain, ["your-overture-building-feature-id", uploaded], name="Overture and uploaded buildings",)print(buildings.id, buildings.status){ "id": "your-building-feature-id", "domain_id": "your-domain-id", "type": "building", "name": "Overture and uploaded buildings", "description": "", "status": "completed", "progress": null, "created_on": "2026-11-16T16:37:48.996886Z", "modified_on": "2026-11-16T16:37:48.996886Z", "source": { "product": "concatenate", "description": "Rows of other features, appended", "source_feature_ids": [ "your-overture-building-feature-id", "your-uploaded-building-feature-id" ] }, "georeference": { "crs": "EPSG:32611", "bounds": [ 717141.6556112946, 5326524.549818624, 718694.8955395881, 5328248.228078655 ] }, "error": null, "tags": [], "attributions": [ { "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-16" }, { "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-16" }, { "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-16" } ]}The new feature is completed in the 201. Record its id:
your-building-feature-id.
- Inputs.
source_feature_idslists 2 to 100 completed features of the path’s type in the domain, each once. In the SDK, passFeatureobjects, ids, or a mix. - Rows. The rows of each input are appended in the order listed. Polygons are not merged, so where an uploaded polygon overlaps a fetched one, the feature keeps both.
- Columns. The new feature has every column of every input, plus
source_feature_id, the id of the input each row came from. A row isnullin a column its input lacks. A property named like a column of another input fills that column, so it needs the same type. - Attributions.
attributionslists those of every input. Rows from Overture or OpenStreetMap stay under the ODbL, so reproduce eachcitationwherever you show or share the combined feature. - The inputs are unchanged.
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 = buildings.get_data_metadata()print(metadata.total_features){ "total_features": 527, "partition_count": 1, "partitions": [ { "index": 0, "num_features": 527 } ]}The combined feature holds 527 footprints, the 524 from Overture and the 3
uploaded houses. Each row records its input in source_feature_id:
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'rows = buildings.to_geodataframe()print(rows.groupby("source_feature_id", sort=False).size()){ "type": "FeatureCollection", "features": [ { "id": "0", "type": "Feature", "properties": { "height": 4.0, "height_source": "OpenStreetMap", "source_dataset": "OpenStreetMap", "source_feature_id": "your-overture-building-feature-id" }, "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": "524", "type": "Feature", "properties": { "height": null, "height_source": null, "source_dataset": "Digitized from NAIP 2025", "source_feature_id": "your-uploaded-building-feature-id" }, "geometry": { "type": "Polygon", "coordinates": [ [ [717673.0076616996, 5326673.234831276], [717674.9771499757, 5326668.524042196], [717672.9866794341, 5326661.993566813], [717666.0127944023, 5326660.94981969], [717659.0178175371, 5326660.4617393715], [717657.0174342298, 5326662.055191791], [717656.9765972904, 5326672.960232516], [717673.0076616996, 5326673.234831276] ] ] } } ], "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::32611" } }}The uploaded houses have no height property, so their height and
height_source are null. Their source_dataset property fills the
source_dataset column.
Use the combined feature in one rule
Section titled “Use the combined feature in one rule”A grid or inventory rule references one feature_id. To apply a rule to the
fetched and uploaded polygons together, reference the combined feature. This
rule removes dead surface fuel in every cell that a building touches:
curl -X 'POST' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/grids/lookup/fbfm40' \ -H 'accept: application/json' \ -H 'api-key: my-api-key' \ -H 'Content-Type: application/json' \ -d '{ "name": "Dead surface fuel — buildings masked", "source_grid_id": "your-fbfm40-grid-id", "bands": ["fuel_load.1hr", "fuel_load.10hr", "fuel_load.100hr"], "modifications": [ { "conditions": [ {"source": "feature", "operator": "intersects", "target": "cell", "feature_id": "your-building-feature-id"} ], "actions": [ {"band": "fuel_load.1hr", "modifier": "replace", "value": 0}, {"band": "fuel_load.10hr", "modifier": "replace", "value": 0}, {"band": "fuel_load.100hr", "modifier": "replace", "value": 0} ] } ]}'import fastfuels_sdk.v2 as ff
ff.set_api_key("my-api-key")
fbfm = ff.get_grid("your-domain-id", "your-fbfm40-grid-id")
dead_fuel_bands = ["fuel_load.1hr", "fuel_load.10hr", "fuel_load.100hr"]
grid = ff.grids.create_fuel_grid_from_fbfm40_lookup( fbfm, bands=dead_fuel_bands, name="Dead surface fuel — buildings masked", modifications=[ ff.mask("your-building-feature-id", dead_fuel_bands, 0, operator="intersects", target="cell"), ],)print(grid.id, grid.status){ "id": "your-grid-id", "domain_id": "your-domain-id", "name": "Dead surface fuel — buildings masked", "description": "", "status": "pending", "progress": null, "created_on": "2026-11-16T16:42:28.752070", "modified_on": "2026-11-16T16:42:28.752070", "checksum": "0fa01b2fb9ac44589d117fea54c781c0", "source": { "name": "lookup", "table": "fbfm40", "source_grid_id": "your-fbfm40-grid-id", "source_grid_checksum": "6bfd9796db2f4c48953707f9342a0374", "source_band": "fbfm", "herbaceous_curing": 0.67 }, "modifications": [ { "conditions": [ { "source": "feature", "operator": "intersects", "feature_id": "your-building-feature-id", "buffer_m": null, "target": "cell" } ], "actions": [ { "band": "fuel_load.1hr", "modifier": "replace", "value": 0 }, { "band": "fuel_load.10hr", "modifier": "replace", "value": 0 }, { "band": "fuel_load.100hr", "modifier": "replace", "value": 0 } ] } ], "bands": [ { "key": "fuel_load.1hr", "name": "1-hour Fuel Load", "description": "Oven-dry mass per unit area of 1-hour timelag dead fuels.", "type": "continuous", "unit": "kg/m**2", "index": 0, "nodata": null, "summary": null }, { "key": "fuel_load.10hr", "name": "10-hour Fuel Load", "description": "Oven-dry mass per unit area of 10-hour timelag dead fuels.", "type": "continuous", "unit": "kg/m**2", "index": 1, "nodata": null, "summary": null }, { "key": "fuel_load.100hr", "name": "100-hour Fuel Load", "description": "Oven-dry mass per unit area of 100-hour timelag dead fuels.", "type": "continuous", "unit": "kg/m**2", "index": 2, "nodata": null, "summary": null } ], "georeference": { "crs": "EPSG:32611", "transform": [2.0, 0.0, 717141.6556112946, 0.0, -2.0, 5328248.549818624], "shape": [862, 777] }, "error": null, "chunks": { "shape": [512, 512], "count": null, "count_by_axis": null }, "tags": [], "attributions": []}Record the grid id, your-grid-id, and
poll it
to completed. On the Bigfork domain the rule removes fuel from 46,009 cells,
185.1 t of dead fuel. The same rule on the Overture feature alone removes fuel
from 45,762 cells, so the three uploaded houses add 247 cells.
To remove trees inside the same footprints, reference the combined feature in an inventory rule, as in Remove CHM detections inside building footprints.
Common pitfalls
Section titled “Common pitfalls”A rejected upload or concatenation returns 422 and creates no feature. Fix
the body and send it again.
-
Projected coordinates without a
crsblock. The coordinates are read as longitude and latitude, so UTM meters fall far outside the domain. Add acrsblock that names the CRS.{"detail": "None of the polygons intersect the domain. Check that they are in the declared CRS and cover the domain's area."} -
A road or driveway drawn as a line. A
LineStringis rejected. Buffer each line into a polygon the width of the road. The Python SDK raisesValueErrorbefore sending the request.{"detail": [{"type": "literal_error","loc": ["body", "features", 0, "geometry", "Polygon", "type"],"msg": "Input should be 'Polygon'","input": "LineString","ctx": {"expected": "'Polygon'"}},{"type": "literal_error","loc": ["body", "features", 0, "geometry", "MultiPolygon", "type"],"msg": "Input should be 'MultiPolygon'","input": "LineString","ctx": {"expected": "'MultiPolygon'"}}]} -
An invalid polygon. A ring that crosses itself is rejected. The error names the first invalid feature by its index. Repair the polygons, for example with QGIS’s Fix Geometries tool or shapely’s
make_valid.{"detail": "Feature 0 has an invalid geometry (Self-intersection[-114.078747 48.0561225]), and 1 feature(s) are invalid in all. Fix them, e.g. with QGIS's Fix Geometries tool or shapely's make_valid, and upload again."} -
A property with mixed types. Here
storiesis2in one feature and"two"in another. Give each property one type across all features.{"detail": "Feature properties can't be stored: (\"Could not convert 'two' with type str: tried to convert to int64\", 'Conversion failed for column stories with type object'). Each property must have one type across all features, e.g. always a number or always text."} -
A property named
geometry. Rename it. The name is taken by the geometry column. -
Concatenating a fetched feature before it completes. Wait until each input is
completed.{"detail": "Feature 'your-overture-building-feature-id' has status 'running', expected 'completed'. Wait for it to finish before concatenating it."} -
A property that clashes with another input’s column. Here an uploaded house carries
heightas text,"two storeys", while the Overtureheightcolumn holds numbers. Upload heights as numbers in m, or use another property name.{"detail": "Feature properties can't be stored: (\"Could not convert 'two storeys' with type str: tried to convert to double\", 'Conversion failed for column height with type object'). Each property must have one type across all features, e.g. always a number or always text."} -
Features of different types. Every input must have the type in the path. To mask roads and buildings in one grid, write one rule per feature, as in Remove fuel under roads, water and buildings in one grid.
Next steps
Section titled “Next steps”- Remove surface fuel under roads, water and buildings to thin fuel or widen the mask around the combined feature.
- Remove trees with road, water and building features to drop trees and rooftop detections inside the combined footprints.