Skip to content

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.

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

  2. A domain: your-domain-id. See Create a domain. Uploaded polygons are clipped to this domain and stored in its CRS.

  3. The polygons to upload, as a GeoJSON FeatureCollection: footprints from a county GIS layer, a survey, or your own digitizing.

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

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

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.

POST building/geojson
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]
]]
}
}
]
}'

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 Polygon or MultiPolygon. 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 crs block. 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.bounds is the extent of the domain, grown by extent_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.

Overture buildings Uploaded houses
The three uploaded houses (magenta) and the Overture footprints around them (yellow), in the Bigfork domain. Click a footprint to see its properties.

total_features counts the polygons the feature holds after clipping:

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

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.

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

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.

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

The new feature is completed in the 201. Record its id: your-building-feature-id.

  • Inputs. source_feature_ids lists 2 to 100 completed features of the path’s type in the domain, each once. In the SDK, pass Feature objects, 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 is null in a column its input lacks. A property named like a column of another input fills that column, so it needs the same type.
  • Attributions. attributions lists those of every input. Rows from Overture or OpenStreetMap stay under the ODbL, so reproduce each citation wherever you show or share the combined feature.
  • The inputs are unchanged.
GET 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'

The combined feature holds 527 footprints, the 524 from Overture and the 3 uploaded houses. Each row records its input in source_feature_id:

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

The uploaded houses have no height property, so their height and height_source are null. Their source_dataset property fills the source_dataset column.

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:

Remove fuel under all buildings
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}
]
}
]
}'

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.

A rejected upload or concatenation returns 422 and creates no feature. Fix the body and send it again.

  • Projected coordinates without a crs block. The coordinates are read as longitude and latitude, so UTM meters fall far outside the domain. Add a crs block 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 LineString is rejected. Buffer each line into a polygon the width of the road. The Python SDK raises ValueError before 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 stories is 2 in 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 height as text, "two storeys", while the Overture height column 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.