Skip to content
DeepfireDeepfire Docs
Esc
↑↓navigate↵open⌘Jpreview

Queue a fire spread simulation

Seeds a run from the hotspots of a cluster, or from a single point, and queues it. Returns 202 Accepted immediately with a Location header to poll; the run itself takes from under a minute to several minutes depending on duration and ensemble size.

POST/v1/fire-spread/simulations
Authorization
AuthorizationBearer token (JWT) · headerrequired
Token from `POST /v1/token` — see the Authentication guide.
Request body
requiredapplication/json
One of:
any
any
any
any
Responses
202Queued. Poll the `Location` URL until `status` is `COMPLETED`, `NO_SPREAD` or `FAILED`.
idstring<uuid>
statusstring
`QUEUED` until the worker reports back. `NO_SPREAD` means the model completed but the fire did not grow meaningfully. `FAILED` carries `errorMessage`.
Allowed:QUEUEDCOMPLETEDNO_SPREADFAILED
clusterIdstring<uuid>
Absent for point ignitions.
modelstring
durationHoursinteger
ensembleMembersinteger
sourcesstring[]
The source codes that were eligible to seed the run: what you passed, or the defaults expanded.
lookbackHoursinteger | null
latitudenumber
longitudenumber
locationNamestring
ignitionPointCountinteger
Hotspots that seeded the run (at most 100; the most recent and most intense are kept when a cluster has more).
ignitionIgnitionFeatureCollection
GeoJSON `Point` features for the hotspots that seeded the run, with `hotspotId`, `source`, `observedAt` and `fireRadiativePower` properties.
Show properties
typestring
featuresobject[]
createdAtstring<date-time>
domainBufferKminteger
The domain buffer used: what you passed, or 25 once a defaulted run has reported. The only tunable parameter for `forefire` runs.
elmfireobject
Present for `elmfire` runs. Your overrides while `QUEUED`; the full resolved set, every parameter with the value the run used, once the run has reported. `seed` is only echoed when you pinned it.
Show properties
crown_fire_modelinteger
`1` Finney (2004), `2` Scott & Reinhardt (2001).
default: 2
Allowed:12
foliar_moisture_contentnumber
Percent. Lower values make crown fire initiation easier.
min 30 · max 200 · default: 110
max_lownumber
Caps the fire ellipse's length-to-width ratio.
min 1 · max 50 · default: 8
crown_fire_spread_rate_limitnumber
ft/min. Caps crown fire rate of spread.
max 5000 · default: 250
critical_canopy_covernumber
Canopy cover fraction below which crown fire cannot start.
min 0 · max 1 · default: 0.39
wind_speed_fluctuation_intensitynumber
Ensembles only (`ensembleMembers` > 1); 0 for single-member runs. Each member scales wind speed by `1 ± intensity/2`.
max 1 · default: 0.3
wind_direction_fluctuation_intensitynumber
Ensembles only; 0 for single-member runs. Each member rotates wind direction by `± intensity/2` of a full circle.
max 1 · default: 0.06
seedinteger
Random seed. Set it for a reproducible run; omitted, every run draws a fresh seed and none is echoed back.
min 0 · max 2147483647
spottingElmfireSpottingParameters
ELMFIRE's `&SPOTTING` group (ember transport), under its own namelist names. Each `_min`/`_max` and `_lo`/`_hi` pair is sampled afresh on every weather band, so set both ends to pin a value, and give both ends when changing one: ordering is only checked when both are present, and an end that conflicts with the other's default fails at run time as `FAILED`. Unknown fields are rejected.
Show properties
enable_spottingboolean
Master switch for ember spotting.
default: true
enable_surface_fire_spottingboolean
Allow surface fires to spot, not only crown fires.
default: true
spotting_distribution_typestring
Distribution ember travel distances are drawn from.
default: "LOGNORMAL"
Allowed:LOGNORMALUNIFORM
critical_spotting_fireline_intensitynumber
kW/m. Surface fires below this intensity do not spot.
min 0 · default: 1000
mean_spotting_dist_minnumber
Metres. Lower end of the mean ember travel distance.
min 0 · default: 5
mean_spotting_dist_maxnumber
Metres. Upper end of the mean ember travel distance.
min 0 · default: 15
normalized_spotting_dist_variance_minnumber
Lower end of the normalised variance of the spotting distance distribution.
min 0 · default: 250
normalized_spotting_dist_variance_maxnumber
Upper end of the normalised variance of the spotting distance distribution.
min 0 · default: 600
spot_ws_exp_lonumber
Lower end of the wind speed exponent of the spotting distance; the dominant control on ember reach.
min 0 · max 2 · default: 0.4
spot_ws_exp_hinumber
Upper end of the wind speed exponent.
min 0 · max 2 · default: 0.7
spot_flin_exp_lonumber
Lower end of the fireline intensity exponent of the spotting distance.
min 0 · max 2 · default: 0.2
spot_flin_exp_hinumber
Upper end of the fireline intensity exponent.
min 0 · max 2 · default: 0.4
nembers_mininteger
Embers per spotting event, lower bound.
min 1 · default: 1
nembers_max_lointeger
Lower end of the upper bound on embers per event.
min 1 · default: 1
nembers_max_hiinteger
Upper end of the upper bound on embers per event.
min 1 · default: 1
global_surface_fire_spotting_percent_minnumber
Percent of burning surface-fire pixels that launch embers, lower end.
min 0 · max 100 · default: 0
global_surface_fire_spotting_percent_maxnumber
Percent of burning surface-fire pixels that launch embers, upper end.
min 0 · max 100 · default: 0.13
crown_fire_spotting_percent_minnumber
Percent of burning crown-fire pixels that launch embers, lower end.
min 0 · max 100 · default: 0.1
crown_fire_spotting_percent_maxnumber
Percent of burning crown-fire pixels that launch embers, upper end.
min 0 · max 100 · default: 1.2
pign_minnumber
Percent chance a landed ember ignites a spot fire, lower end.
min 0 · max 100 · default: 100
pign_maxnumber
Percent chance a landed ember ignites a spot fire, upper end.
min 0 · max 100 · default: 100
errorMessagestring
Present when `FAILED`.
summaryobject
Model outputs. Absent until the worker has reported back.
Show properties
burnedAreaM2number
Final burned area in square metres.
edgeReachedboolean
True when the fire reached the edge of the modelled domain, so the last polygons are clipped.
windSpeedAvgMsnumber
Mean wind speed over the run, m/s.
windDirectionAvgnumber
Mean wind direction, degrees.
resultobject
GeoJSON `FeatureCollection`, present once `COMPLETED`. One `MultiPolygon` feature per simulated hour with `properties.hour` (1…durationHours), `properties.elapsed_seconds`, and `properties.burn_probability` for ensemble runs. Each polygon is cumulative: the area burned by that hour.
linksobject
Show properties
selfstring<uri>
404`cluster-not-found`: no cluster with that id.
codestring
Stable machine-readable code: `invalid-request`, `cluster-not-found`, `simulation-not-found`, `too-many-simulations`.
messagestring
422`invalid-request`: malformed JSON, an unknown field (the message lists the accepted names, nested ones as `elmfire.spotting.<name>`), a wrong type (integers must be JSON numbers, booleans `true`/`false`), a value out of range, an unknown `sources` code or `model`, an `elmfire` block with `model: forefire`, a wind fluctuation intensity without an ensemble, an inverted `_min`/`_max` pair, or no cluster hotspot matches the sources and lookback. The message names the field.
codestring
Stable machine-readable code: `invalid-request`, `cluster-not-found`, `simulation-not-found`, `too-many-simulations`.
messagestring
429`too-many-simulations`: you already have two simulations queued or running. Wait for one to finish.
codestring
Stable machine-readable code: `invalid-request`, `cluster-not-found`, `simulation-not-found`, `too-many-simulations`.
messagestring
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST "https://api.deepfire.co/v1/fire-spread/simulations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "clusterId": "a3d24843-7014-4490-bdd3-b7cb39b400c8",
  "latitude": -90,
  "longitude": -180,
  "model": "elmfire",
  "durationHours": 1,
  "ensembleMembers": 1,
  "sources": [
    "string"
  ],
  "lookbackHours": 24,
  "domainBufferKm": 25,
  "elmfire": {
    "crown_fire_model": 1,
    "foliar_moisture_content": 110,
    "max_low": 8,
    "crown_fire_spread_rate_limit": 250,
    "critical_canopy_cover": 0.39,
    "wind_speed_fluctuation_intensity": 0.3,
    "wind_direction_fluctuation_intensity": 0.06,
    "seed": 0,
    "spotting": {
      "enable_spotting": true,
      "enable_surface_fire_spotting": true,
      "spotting_distribution_type": "LOGNORMAL",
      "critical_spotting_fireline_intensity": 1000,
      "mean_spotting_dist_min": 5,
      "mean_spotting_dist_max": 15,
      "normalized_spotting_dist_variance_min": 250,
      "normalized_spotting_dist_variance_max": 600,
      "spot_ws_exp_lo": 0.4,
      "spot_ws_exp_hi": 0.7,
      "spot_flin_exp_lo": 0.2,
      "spot_flin_exp_hi": 0.4,
      "nembers_min": 1,
      "nembers_max_lo": 1,
      "nembers_max_hi": 1,
      "global_surface_fire_spotting_percent_min": 0,
      "global_surface_fire_spotting_percent_max": 0.13,
      "crown_fire_spotting_percent_min": 0.1,
      "crown_fire_spotting_percent_max": 1.2,
      "pign_min": 100,
      "pign_max": 100
    }
  }
}'
Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "QUEUED",
  "clusterId": "a3d24843-7014-4490-bdd3-b7cb39b400c8",
  "model": "string",
  "durationHours": 0,
  "ensembleMembers": 0,
  "sources": [
    "string"
  ],
  "lookbackHours": 0,
  "latitude": 0,
  "longitude": 0,
  "locationName": "string",
  "ignitionPointCount": 0,
  "ignition": {
    "type": "FeatureCollection",
    "features": [
      {}
    ]
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "domainBufferKm": 0,
  "elmfire": {
    "crown_fire_model": 1,
    "foliar_moisture_content": 110,
    "max_low": 8,
    "crown_fire_spread_rate_limit": 250,
    "critical_canopy_cover": 0.39,
    "wind_speed_fluctuation_intensity": 0.3,
    "wind_direction_fluctuation_intensity": 0.06,
    "seed": 0,
    "spotting": {
      "enable_spotting": true,
      "enable_surface_fire_spotting": true,
      "spotting_distribution_type": "LOGNORMAL",
      "critical_spotting_fireline_intensity": 1000,
      "mean_spotting_dist_min": 5,
      "mean_spotting_dist_max": 15,
      "normalized_spotting_dist_variance_min": 250,
      "normalized_spotting_dist_variance_max": 600,
      "spot_ws_exp_lo": 0.4,
      "spot_ws_exp_hi": 0.7,
      "spot_flin_exp_lo": 0.2,
      "spot_flin_exp_hi": 0.4,
      "nembers_min": 1,
      "nembers_max_lo": 1,
      "nembers_max_hi": 1,
      "global_surface_fire_spotting_percent_min": 0,
      "global_surface_fire_spotting_percent_max": 0.13,
      "crown_fire_spotting_percent_min": 0.1,
      "crown_fire_spotting_percent_max": 1.2,
      "pign_min": 100,
      "pign_max": 100
    }
  },
  "errorMessage": "string",
  "summary": {
    "burnedAreaM2": 0,
    "edgeReached": true,
    "windSpeedAvgMs": 0,
    "windDirectionAvg": 0
  },
  "result": {},
  "links": {
    "self": "http://example.com"
  }
}