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>

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, a wrong type (integers must be JSON numbers), a value out of range, an unknown `sources` code or `model`, 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

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Bodyapplication/json

Request body

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

import requests

response = requests.post(
    "https://api.deepfire.co/v1/fire-spread/simulations",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"clusterId\": \"a3d24843-7014-4490-bdd3-b7cb39b400c8\",\n  \"latitude\": -90,\n  \"longitude\": -180,\n  \"model\": \"elmfire\",\n  \"durationHours\": 1,\n  \"ensembleMembers\": 1,\n  \"sources\": [\n    \"string\"\n  ],\n  \"lookbackHours\": 24\n}",
)

const response = await fetch("https://api.deepfire.co/v1/fire-spread/simulations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"clusterId\": \"a3d24843-7014-4490-bdd3-b7cb39b400c8\",\n  \"latitude\": -90,\n  \"longitude\": -180,\n  \"model\": \"elmfire\",\n  \"durationHours\": 1,\n  \"ensembleMembers\": 1,\n  \"sources\": [\n    \"string\"\n  ],\n  \"lookbackHours\": 24\n}"
});

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",
  "errorMessage": "string",
  "summary": {
    "burnedAreaM2": 0,
    "edgeReached": true,
    "windSpeedAvgMs": 0,
    "windDirectionAvg": 0
  },
  "result": {},
  "links": {
    "self": "http://example.com"
  }
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}