DEVS-Fire API

Examples

Predefined workflows from the Playground, ready to copy into your own project

View for LLMs

Overview

These are the same four "Quick Start" flows available in the Playground's preset picker, written as standalone scripts that call the DEVS-Fire API directly (https://firesim.cs.gsu.edu/api) instead of through the playground's proxy. Copy any of them into your own project as a starting point.

Contained Burn (Quick Start)

A full contained-burn scenario: a 200×200 cell grid at 30m resolution, strong wind (23 @ 129°), a 6km fuel-break boundary traced around the grid's edge, a 3km square ignition front lit by four dynamic burn teams, and a 12,000-timestep run.

import requests

BASE = "https://firesim.cs.gsu.edu/api"

# 1. Connect and capture token
user_token = requests.post(f"{BASE}/connectToServer", data="testtest", headers={"accept": "application/json"}).text

# 2. Configure the grid and weather
requests.post(f"{BASE}/setCellResolution/", params={"userToken": user_token, "cellResolution": 30, "cellDimension": 200})
requests.post(f"{BASE}/setCellSpaceLocation/", params={"userToken": user_token, "lat": 37.523454, "lng": -97.511525})
requests.post(f"{BASE}/setWindCondition/", params={"userToken": user_token, "windSpeed": 23, "windDirection": 129})

# 3. Trace a fuel-break boundary around the grid's edge (four segments)
boundary = [
    (0, 0, 199, 0),
    (199, 0, 199, 199),
    (199, 199, 0, 199),
    (0, 199, 0, 0),
]
for x1, y1, x2, y2 in boundary:
    requests.post(f"{BASE}/setSuppressedCell/", params={"userToken": user_token, "x1": x1, "y1": y1, "x2": x2, "y2": y2})

# 4. Light a 3km square ignition front with four dynamic burn teams
ignition = [
    ("team0", 50, 50, 150, 50),
    ("team1", 150, 50, 150, 150),
    ("team2", 150, 150, 50, 150),
    ("team3", 50, 150, 50, 50),
]
for team, x1, y1, x2, y2 in ignition:
    requests.post(f"{BASE}/setDynamicIgnition/", params={
        "userToken": user_token, "teamNum": team, "x1": x1, "y1": y1, "x2": x2, "y2": y2, "speed": 3,
    })

# 5. Run the simulation
events = requests.post(f"{BASE}/runSimulation/", params={"userToken": user_token, "time": 12000}).json()
print("Fire events:", len(events))
const BASE = "https://firesim.cs.gsu.edu/api";

// 1. Connect and capture token
const userToken = await (await fetch(`${BASE}/connectToServer`, {
  method: "POST",
  headers: { accept: "application/json" },
  body: "testtest",
})).text();

// 2. Configure the grid and weather
await fetch(`${BASE}/setCellResolution/?` + new URLSearchParams({ userToken, cellResolution: "30", cellDimension: "200" }), { method: "POST" });
await fetch(`${BASE}/setCellSpaceLocation/?` + new URLSearchParams({ userToken, lat: "37.523454", lng: "-97.511525" }), { method: "POST" });
await fetch(`${BASE}/setWindCondition/?` + new URLSearchParams({ userToken, windSpeed: "23", windDirection: "129" }), { method: "POST" });

// 3. Trace a fuel-break boundary around the grid's edge (four segments)
const boundary = [
  ["0", "0", "199", "0"],
  ["199", "0", "199", "199"],
  ["199", "199", "0", "199"],
  ["0", "199", "0", "0"],
];
for (const [x1, y1, x2, y2] of boundary) {
  await fetch(`${BASE}/setSuppressedCell/?` + new URLSearchParams({ userToken, x1, y1, x2, y2 }), { method: "POST" });
}

// 4. Light a 3km square ignition front with four dynamic burn teams
const ignition = [
  ["team0", "50", "50", "150", "50"],
  ["team1", "150", "50", "150", "150"],
  ["team2", "150", "150", "50", "150"],
  ["team3", "50", "150", "50", "50"],
];
for (const [teamNum, x1, y1, x2, y2] of ignition) {
  await fetch(`${BASE}/setDynamicIgnition/?` + new URLSearchParams({ userToken, teamNum, x1, y1, x2, y2, speed: "3" }), { method: "POST" });
}

// 5. Run the simulation
const events = await (await fetch(`${BASE}/runSimulation/?` + new URLSearchParams({ userToken, time: "12000" }), { method: "POST" })).json();
console.log("Fire events:", events.length);
BASE="https://firesim.cs.gsu.edu/api"

# 1. Connect and capture token
USER_TOKEN=$(curl -s -X POST -H "accept: application/json" -d "testtest" "$BASE/connectToServer")

# 2. Configure the grid and weather
curl -s -X POST "$BASE/setCellResolution/?userToken=$USER_TOKEN&cellResolution=30&cellDimension=200"
curl -s -X POST "$BASE/setCellSpaceLocation/?userToken=$USER_TOKEN&lat=37.523454&lng=-97.511525"
curl -s -X POST "$BASE/setWindCondition/?userToken=$USER_TOKEN&windSpeed=23&windDirection=129"

# 3. Trace a fuel-break boundary around the grid's edge (four segments)
curl -s -X POST "$BASE/setSuppressedCell/?userToken=$USER_TOKEN&x1=0&y1=0&x2=199&y2=0"
curl -s -X POST "$BASE/setSuppressedCell/?userToken=$USER_TOKEN&x1=199&y1=0&x2=199&y2=199"
curl -s -X POST "$BASE/setSuppressedCell/?userToken=$USER_TOKEN&x1=199&y1=199&x2=0&y2=199"
curl -s -X POST "$BASE/setSuppressedCell/?userToken=$USER_TOKEN&x1=0&y1=199&x2=0&y2=0"

# 4. Light a 3km square ignition front with four dynamic burn teams
curl -s -X POST "$BASE/setDynamicIgnition/?userToken=$USER_TOKEN&teamNum=team0&x1=50&y1=50&x2=150&y2=50&speed=3"
curl -s -X POST "$BASE/setDynamicIgnition/?userToken=$USER_TOKEN&teamNum=team1&x1=150&y1=50&x2=150&y2=150&speed=3"
curl -s -X POST "$BASE/setDynamicIgnition/?userToken=$USER_TOKEN&teamNum=team2&x1=150&y1=150&x2=50&y2=150&speed=3"
curl -s -X POST "$BASE/setDynamicIgnition/?userToken=$USER_TOKEN&teamNum=team3&x1=50&y1=150&x2=50&y2=50&speed=3"

# 5. Run the simulation
curl -s -X POST "$BASE/runSimulation/?userToken=$USER_TOKEN&time=12000"
import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String base = "https://firesim.cs.gsu.edu/api";

// 1. Connect and capture token
HttpResponse<String> connectResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/connectToServer"))
    .header("accept", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("testtest")).build(),
  HttpResponse.BodyHandlers.ofString()
);
String userToken = connectResp.body();

// 2. Configure the grid and weather
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellResolution/?userToken=" + userToken + "&cellResolution=30&cellDimension=200")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellSpaceLocation/?userToken=" + userToken + "&lat=37.523454&lng=-97.511525")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setWindCondition/?userToken=" + userToken + "&windSpeed=23&windDirection=129")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());

// 3. Trace a fuel-break boundary around the grid's edge (four segments)
String[][] boundary = {
  {"0", "0", "199", "0"},
  {"199", "0", "199", "199"},
  {"199", "199", "0", "199"},
  {"0", "199", "0", "0"},
};
for (String[] seg : boundary) {
  String url = base + "/setSuppressedCell/?userToken=" + userToken + "&x1=" + seg[0] + "&y1=" + seg[1] + "&x2=" + seg[2] + "&y2=" + seg[3];
  client.send(HttpRequest.newBuilder().uri(URI.create(url)).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
}

// 4. Light a 3km square ignition front with four dynamic burn teams
String[][] ignition = {
  {"team0", "50", "50", "150", "50"},
  {"team1", "150", "50", "150", "150"},
  {"team2", "150", "150", "50", "150"},
  {"team3", "50", "150", "50", "50"},
};
for (String[] team : ignition) {
  String url = base + "/setDynamicIgnition/?userToken=" + userToken + "&teamNum=" + team[0]
    + "&x1=" + team[1] + "&y1=" + team[2] + "&x2=" + team[3] + "&y2=" + team[4] + "&speed=3";
  client.send(HttpRequest.newBuilder().uri(URI.create(url)).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
}

// 5. Run the simulation
HttpResponse<String> runResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/runSimulation/?userToken=" + userToken + "&time=12000"))
    .POST(HttpRequest.BodyPublishers.noBody()).build(),
  HttpResponse.BodyHandlers.ofString()
);
System.out.println("Fire events response: " + runResp.body());

Step-by-Step (Continue Loop)

Runs several smaller continueSimulation intervals instead of one long runSimulation call, so you can inspect or react to the fire's progression between steps.

import requests

BASE = "https://firesim.cs.gsu.edu/api"

user_token = requests.post(f"{BASE}/connectToServer", data="testtest", headers={"accept": "application/json"}).text

requests.post(f"{BASE}/setCellSpaceLocation/", params={"userToken": user_token, "lat": 37.523454, "lng": -97.511525})
requests.post(f"{BASE}/setCellResolution/", params={"userToken": user_token, "cellResolution": 30, "cellDimension": 100})
requests.post(f"{BASE}/setWindCondition/", params={"userToken": user_token, "windSpeed": 8, "windDirection": 90})
requests.post(f"{BASE}/setPointIgnition/", params={"userToken": user_token, "xs": 50, "ys": 50})

total = 0
for step in range(1, 5):
    events = requests.post(f"{BASE}/continueSimulation/", params={"userToken": user_token, "time": 20}).json()
    total += len(events)
    print(f"Step {step}: {len(events)} events, total {total}")
const BASE = "https://firesim.cs.gsu.edu/api";

const userToken = await (await fetch(`${BASE}/connectToServer`, {
  method: "POST",
  headers: { accept: "application/json" },
  body: "testtest",
})).text();

await fetch(`${BASE}/setCellSpaceLocation/?` + new URLSearchParams({ userToken, lat: "37.523454", lng: "-97.511525" }), { method: "POST" });
await fetch(`${BASE}/setCellResolution/?` + new URLSearchParams({ userToken, cellResolution: "30", cellDimension: "100" }), { method: "POST" });
await fetch(`${BASE}/setWindCondition/?` + new URLSearchParams({ userToken, windSpeed: "8", windDirection: "90" }), { method: "POST" });
await fetch(`${BASE}/setPointIgnition/?` + new URLSearchParams({ userToken, xs: "50", ys: "50" }), { method: "POST" });

let total = 0;
for (let step = 1; step <= 4; step += 1) {
  const res = await fetch(`${BASE}/continueSimulation/?` + new URLSearchParams({ userToken, time: "20" }), { method: "POST" });
  const events = await res.json();
  total += events.length;
  console.log(`Step ${step}: ${events.length} events, total ${total}`);
}
BASE="https://firesim.cs.gsu.edu/api"

USER_TOKEN=$(curl -s -X POST -H "accept: application/json" -d "testtest" "$BASE/connectToServer")

curl -s -X POST "$BASE/setCellSpaceLocation/?userToken=$USER_TOKEN&lat=37.523454&lng=-97.511525"
curl -s -X POST "$BASE/setCellResolution/?userToken=$USER_TOKEN&cellResolution=30&cellDimension=100"
curl -s -X POST "$BASE/setWindCondition/?userToken=$USER_TOKEN&windSpeed=8&windDirection=90"
curl -s -X POST "$BASE/setPointIgnition/?userToken=$USER_TOKEN&xs=50&ys=50"

for i in 1 2 3 4; do
  curl -s -X POST "$BASE/continueSimulation/?userToken=$USER_TOKEN&time=20"
done
import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String base = "https://firesim.cs.gsu.edu/api";

HttpResponse<String> connectResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/connectToServer"))
    .header("accept", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("testtest")).build(),
  HttpResponse.BodyHandlers.ofString()
);
String userToken = connectResp.body();

client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellSpaceLocation/?userToken=" + userToken + "&lat=37.523454&lng=-97.511525")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellResolution/?userToken=" + userToken + "&cellResolution=30&cellDimension=100")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setWindCondition/?userToken=" + userToken + "&windSpeed=8&windDirection=90")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setPointIgnition/?userToken=" + userToken + "&xs=50&ys=50")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());

int total = 0;
for (int step = 1; step <= 4; step++) {
  HttpResponse<String> res = client.send(
    HttpRequest.newBuilder().uri(URI.create(base + "/continueSimulation/?userToken=" + userToken + "&time=20"))
      .POST(HttpRequest.BodyPublishers.noBody()).build(),
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Step " + step + ": " + res.body());
}

Terrain Lookup

Configures a location and grid, then fetches the fuel matrix for that grid — useful for inspecting terrain data before running a simulation, or building a fuel-map overlay.

import requests

BASE = "https://firesim.cs.gsu.edu/api"

user_token = requests.post(f"{BASE}/connectToServer", data="testtest", headers={"accept": "application/json"}).text

requests.post(f"{BASE}/setCellSpaceLocation/", params={"userToken": user_token, "lat": 37.523454, "lng": -97.511525})
requests.post(f"{BASE}/setCellResolution/", params={"userToken": user_token, "cellResolution": 30, "cellDimension": 80})

matrix = requests.post(f"{BASE}/getCellFuel/", params={"userToken": user_token}).json()
print("Fuel rows:", len(matrix) if isinstance(matrix, list) else "unknown")
const BASE = "https://firesim.cs.gsu.edu/api";

const userToken = await (await fetch(`${BASE}/connectToServer`, {
  method: "POST",
  headers: { accept: "application/json" },
  body: "testtest",
})).text();

await fetch(`${BASE}/setCellSpaceLocation/?` + new URLSearchParams({ userToken, lat: "37.523454", lng: "-97.511525" }), { method: "POST" });
await fetch(`${BASE}/setCellResolution/?` + new URLSearchParams({ userToken, cellResolution: "30", cellDimension: "80" }), { method: "POST" });

const matrix = await (await fetch(`${BASE}/getCellFuel/?` + new URLSearchParams({ userToken }), { method: "POST" })).json();
console.log("Fuel rows:", Array.isArray(matrix) ? matrix.length : "unknown");
BASE="https://firesim.cs.gsu.edu/api"

USER_TOKEN=$(curl -s -X POST -H "accept: application/json" -d "testtest" "$BASE/connectToServer")

curl -s -X POST "$BASE/setCellSpaceLocation/?userToken=$USER_TOKEN&lat=37.523454&lng=-97.511525"
curl -s -X POST "$BASE/setCellResolution/?userToken=$USER_TOKEN&cellResolution=30&cellDimension=80"
curl -s -X POST "$BASE/getCellFuel/?userToken=$USER_TOKEN"
import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String base = "https://firesim.cs.gsu.edu/api";

HttpResponse<String> connectResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/connectToServer"))
    .header("accept", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("testtest")).build(),
  HttpResponse.BodyHandlers.ofString()
);
String userToken = connectResp.body();

client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellSpaceLocation/?userToken=" + userToken + "&lat=37.523454&lng=-97.511525")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellResolution/?userToken=" + userToken + "&cellResolution=30&cellDimension=80")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());

HttpResponse<String> fuelResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/getCellFuel/?userToken=" + userToken))
    .POST(HttpRequest.BodyPublishers.noBody()).build(),
  HttpResponse.BodyHandlers.ofString()
);
System.out.println("Fuel matrix: " + fuelResp.body());

Metrics After Run

Runs a compact simulation, then queries summary metrics — burned area, perimeter length, and burning/unburned cell counts — from the finished run.

import requests

BASE = "https://firesim.cs.gsu.edu/api"

user_token = requests.post(f"{BASE}/connectToServer", data="testtest", headers={"accept": "application/json"}).text

requests.post(f"{BASE}/setCellSpaceLocation/", params={"userToken": user_token, "lat": 37.523454, "lng": -97.511525})
requests.post(f"{BASE}/setCellResolution/", params={"userToken": user_token, "cellResolution": 30, "cellDimension": 100})
requests.post(f"{BASE}/setWindCondition/", params={"userToken": user_token, "windSpeed": 5, "windDirection": 180})
requests.post(f"{BASE}/setPointIgnition/", params={"userToken": user_token, "xs": 50, "ys": 50})

events = requests.post(f"{BASE}/runSimulation/", params={"userToken": user_token, "time": 50}).json()
print("Events:", len(events))

for endpoint in ["computeBurnedArea", "computePerimeterLength", "getBurningCellNum", "getUnburnedCellNum"]:
    res = requests.post(f"{BASE}/{endpoint}/", params={"userToken": user_token})
    print(endpoint, res.text)
const BASE = "https://firesim.cs.gsu.edu/api";

const userToken = await (await fetch(`${BASE}/connectToServer`, {
  method: "POST",
  headers: { accept: "application/json" },
  body: "testtest",
})).text();

await fetch(`${BASE}/setCellSpaceLocation/?` + new URLSearchParams({ userToken, lat: "37.523454", lng: "-97.511525" }), { method: "POST" });
await fetch(`${BASE}/setCellResolution/?` + new URLSearchParams({ userToken, cellResolution: "30", cellDimension: "100" }), { method: "POST" });
await fetch(`${BASE}/setWindCondition/?` + new URLSearchParams({ userToken, windSpeed: "5", windDirection: "180" }), { method: "POST" });
await fetch(`${BASE}/setPointIgnition/?` + new URLSearchParams({ userToken, xs: "50", ys: "50" }), { method: "POST" });

const events = await (await fetch(`${BASE}/runSimulation/?` + new URLSearchParams({ userToken, time: "50" }), { method: "POST" })).json();
console.log("Events:", events.length);

for (const endpoint of ["computeBurnedArea", "computePerimeterLength", "getBurningCellNum", "getUnburnedCellNum"]) {
  const res = await fetch(`${BASE}/${endpoint}/?` + new URLSearchParams({ userToken }), { method: "POST" });
  console.log(endpoint, await res.text());
}
BASE="https://firesim.cs.gsu.edu/api"

USER_TOKEN=$(curl -s -X POST -H "accept: application/json" -d "testtest" "$BASE/connectToServer")

curl -s -X POST "$BASE/setCellSpaceLocation/?userToken=$USER_TOKEN&lat=37.523454&lng=-97.511525"
curl -s -X POST "$BASE/setCellResolution/?userToken=$USER_TOKEN&cellResolution=30&cellDimension=100"
curl -s -X POST "$BASE/setWindCondition/?userToken=$USER_TOKEN&windSpeed=5&windDirection=180"
curl -s -X POST "$BASE/setPointIgnition/?userToken=$USER_TOKEN&xs=50&ys=50"
curl -s -X POST "$BASE/runSimulation/?userToken=$USER_TOKEN&time=50"

for endpoint in computeBurnedArea computePerimeterLength getBurningCellNum getUnburnedCellNum; do
  curl -s -X POST "$BASE/$endpoint/?userToken=$USER_TOKEN"
done
import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String base = "https://firesim.cs.gsu.edu/api";

HttpResponse<String> connectResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/connectToServer"))
    .header("accept", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("testtest")).build(),
  HttpResponse.BodyHandlers.ofString()
);
String userToken = connectResp.body();

client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellSpaceLocation/?userToken=" + userToken + "&lat=37.523454&lng=-97.511525")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setCellResolution/?userToken=" + userToken + "&cellResolution=30&cellDimension=100")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setWindCondition/?userToken=" + userToken + "&windSpeed=5&windDirection=180")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());
client.send(HttpRequest.newBuilder().uri(URI.create(base + "/setPointIgnition/?userToken=" + userToken + "&xs=50&ys=50")).POST(HttpRequest.BodyPublishers.noBody()).build(), HttpResponse.BodyHandlers.ofString());

HttpResponse<String> runResp = client.send(
  HttpRequest.newBuilder().uri(URI.create(base + "/runSimulation/?userToken=" + userToken + "&time=50"))
    .POST(HttpRequest.BodyPublishers.noBody()).build(),
  HttpResponse.BodyHandlers.ofString()
);
System.out.println("Events: " + runResp.body());

for (String endpoint : new String[]{"computeBurnedArea", "computePerimeterLength", "getBurningCellNum", "getUnburnedCellNum"}) {
  HttpResponse<String> res = client.send(
    HttpRequest.newBuilder().uri(URI.create(base + "/" + endpoint + "/?userToken=" + userToken))
      .POST(HttpRequest.BodyPublishers.noBody()).build(),
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println(endpoint + ": " + res.body());
}

Open the Playground to run any of these live in TypeScript or cURL, or see the Quickstart guide to build the request sequence yourself.

Quickstart

Run your first DEVS-Fire simulation in minutes

Authentication

How authentication works with the DEVS-Fire API

On this page

OverviewContained Burn (Quick Start)Step-by-Step (Continue Loop)Terrain LookupMetrics After Run