In order to run a simulation, a token must first be created for a simulation. Generate this token by requesting /api/connectToServer. All other commands require this token. Each new simulation will need a new token, so a new token must be produced for each simulation run. All commands will start with "https://firesim.cs.gsu.edu/api/".
The example codes are in Java, but any language or HTTP requester can be used to access the API.
none
userToken (String) - key used to refer requests to a specific simulation
1
2
3
4
5
6
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/connectToServer"))
.header("accept", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("testtest"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Sets multiple simulation parameters with one command, so you don't have to request the endpoint for each parameter individually.
userToken (String) - Your simulation token.
x (int)(OPTIONAL) - The "row" of the ignition point.
y (int)(OPTIONAL) - The "column" of the ignition point.
lat (double)(OPTIONAL) - Center simulation map on given latitude.
lng (double)(OPTIONAL) - Center simulation map on given longitude.
windSpeed (double)(OPTIONAL) - The wind's speed for the simulation. Default is 0.
windDirection (double)(OPTIONAL) - The wind's blowing direction in the simulation. Set in degrees, where south is 0 and increasing values move clockwise (e.g. west is 90 and so on). Default is 0.
cellResolution (int)(OPTIONAL) - The cubic area of each cell. Default is 30.
cellDimension (int)(OPTIONAL) - the number of cells per row and column. Default is 200.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setMultiParameters/?userToken="+key+"&x="+5+"&y="+5+"&lat="+1526555.822562622+"&lng="+-35655.01701560877+"&windDirection="+180))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Runs a simulation using the current parameters.
userToken (String) - Your simulation token.
time (int) - Number of timesteps to run the simulation for.
JSON (List <String>) - List of all operations on coordinates executed during the simulation. Each operation is a JSON object with the properties:
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/runSimulation/?userToken="+key+"&time="+simTime))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
[{"x":"80" ,"y":"80" ,"Operation":"BurnTeam" ,"time":"0.0" }...]
Starts a simulation or continues it by an interval of time. allows a user to run a simulation in steps, where changes can be made or data collected between each.
userToken (String) - Your simulation token.
time (int) - Number of timesteps to advance the simulation by.
JSON (List <String>) - List of all operations on coordinates executed during the simulation. Each operation is a JSON object with the properties:
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/continueSimulation/?userToken="+key+"&time="+simTime))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
[{"x":"80" ,"y":"80" ,"Operation":"BurnTeam" ,"time":"0.0" }...]
Set the size of each cell and the dimensions of the cell space. If this is not set, the simulation will run with the default cell resolution and dimensions of 30 and 200x200. Inputting a custom fuel map will update the dimensions automatically to match the given map.
userToken (String) - Your simulation token.
cellResolution (int) - The cubic area of each cell.
cellDimension (int) - The height and width of the cell space.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setCellResolution/?userToken="+key+"&cellResolution="+30+"&cellDimension="+200))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
If using the online fuel data, then the location must be picked before a simulation can run. Inputting any coordinate in the US will set the center of the simulation to the given position.
userToken (String) - Your simulation token.
lat (double) - Latitude of the center of the simulation area.
lng (double) - Longitude of the center of the simulation area.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setCellSpaceLocation/?userToken="+key+"&lat="+1526555.822562622+"&lng="+-35655.01701560877))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Set the winds speed and direction.
userToken (String) - Your simulation token.
windSpeed (double)(OPTIONAL) - The wind's speed for the simulation. Default is 0.
windDirection (double)(OPTIONAL) - The wind's blowing direction in the simulation. Set in degrees, where south is 0 and increasing values move clockwise (e.g. west is 90 and so on). Default is 0.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setWindCondition/?userToken="+key+"&windSpeed="+5+"&windDirection="+180))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Set one or more cells to burn simultaneously at the start of the simulation. Both coordinate parameters should be formatted as comma-separated strings with no spaces between values, i.e. "x1,x2,x3" and "y1,y2,y3" to define 3 points of ignition.
userToken (String) - Your simulation token.
xs (String) - Comma-separated rows of cells to ignite.
ys (String) - Comma-separated columns of cells to ignite.
1
2
3
4
5
// Ignite at points (50, 50) and (100,100)
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setPointIgnition/?userToken="+key+"&xs="+"50,100"+"&ys="+"50,100"))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Set a team to burn over a specified path. Teams with different teamNums will follow their paths simultaneously. Calling this multiple times with the same team will make that team follow each path in sequence from first to last.
userToken (String) - Your simulation token.
teamNum (String) - The team name and ID.
x1 (int) - starting position's row.
y1 (int) - starting position's column.
x2 (int) - ending position's row.
y2 (int) - ending position's column.
speed (double) - The speed at which the team moves.
mode (String)(OPTIONAL) - Set to "spot" for individual ignition points separated by distance; set to "continuous" for a continuous line of ignition. Default is "continuous".
distance (double)(OPTIONAL) - If mode is set to "spot", this is the distance between each ignition point. Default is 0.
waitTime (double)(OPTIONAL) - Wait for this many timesteps before burning. Default is -1 to start immediately.
BurnTeams (String) - Returns a list of all burn teams and paths set up so far.
1
2
3
4
5
// These two teams "team0" and "team1" will run simultaneously
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setDynamicIgnition/?userToken="+key+"&teamNum=team0&x1="+1+"&y1="+1+"&x2="+100+"&y2="+100+"&speed="+0.4))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
HttpRequest request2 = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setDynamicIgnition/?userToken="+key+"&teamNum=team1&x3="+1+"&y3="+1+"&x4="+100+"&y4="+100+"&speed="+0.4))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response2 = HttpClient.newHttpClient().send(request2, HttpResponse.BodyHandlers.ofString());
// This one team named "team2" will follow the first path, then the second path.
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setDynamicIgnition/?userToken="+key+"&teamNum=team2&x1="+1+"&y1="+1+"&x2="+100+"&y2="+100+"&speed="+0.4))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
HttpRequest request2 = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setDynamicIgnition/?userToken="+key+"&teamNum=team2&x3="+1+"&y3="+1+"&x4="+100+"&y4="+100+"&speed="+0.4))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response2 = HttpClient.newHttpClient().send(request2, HttpResponse.BodyHandlers.ofString());
Set the simulation to use a custom fuel map from a .txt file with space or tab-separated values. See this file for an example.
userToken (String) - Your simulation token.
fuelMap (File) - A tab- or space-separated .txt file of custom fuel data.
1
2
3
4
5
6
7
8
9
File fuel = new File("fuel.txt");
Path path = fuel.toPath();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/loadFuel/?userToken="+key+"&fuelMap="+fuel)))
.header("Content-Type", "text/plain")
.header("fileName", path.getFileName().toString())
.POST(HttpRequest.BodyPublishers.ofFile(path))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Set the simulation to use a custom aspect map from a .txt file with space or tab-separated values. See this file for an example.
userToken (String) - Your simulation token.
AspectMap (File) - A tab- or space-separated .txt file of custom aspect data.
1
2
3
4
5
6
7
8
9
File aspect = new File("aspect.txt");
Path path = aspect.toPath();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/loadAspect/?userToken="+key+"&aspectMap="+aspect)))
.header("Content-Type", "text/plain")
.header("fileName", path.getFileName().toString())
.POST(HttpRequest.BodyPublishers.ofFile(path))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Set the simulation to use a custom slope map from a .txt file with space or tab-separated values. See this file for an example.
userToken (String) - Your simulation token.
SlopeMap (File) - A tab- or space-separated .txt file of custom slope data.
1
2
3
4
5
6
7
8
9
File slope = new File("slope.txt");
Path path = fuel.toPath();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/loadSlope/?userToken="+key+"&slopeMap="+slope)))
.header("Content-Type", "text/plain")
.header("fileName", path.getFileName().toString())
.POST(HttpRequest.BodyPublishers.ofFile(path))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Upload a windflow file for dynamically changing wind data. See this file for an example. The first line is the number of columns (currently unused), and the second line is the number of rows. The third line is column headers. The fourth line onwards represents a wind change, which consists of tab-separated values for the hour, minute, temperature, wind speed, and wind direction. For each wind change line, the wind is scheduled at the given hour and minute to blow with the given speed and direction.
userToken (String) - Your simulation token.
WeatherFlowFile (File) - A txt file including data as described above
1
2
3
4
5
6
7
8
9
File weather = new File("weather_artificial.txt");
Path weatherPath = weather.toPath();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(base_url+"/api/loadWindFlow/?userToken="+key+"&weatherMap="+weather))
.header("Content-Type", "text/plain")
.header("fileName", weatherPath.getFileName().toString())
.POST(HttpRequest.BodyPublishers.ofFile(weatherPath))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Suppresses a single cell or a line of cells between two given cells.
userToken (String) - Your simulation token.
x1 (int) - Starting/single cell's row.
y1 (int) - Starting/single cell's column.
x2 (int)(OPTIONAL) - Ending cell's row, for linear suppression.
y2 (int)(OPTIONAL) - Ending cell's column, for linear suppression.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/setSuppressedCell/?userToken="+key+"&x1="+5+"&y1="+5+"&x2="+5+"&y2="+10))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
Returns the perimeter of the fire at the end of the simulation.
userToken (String) - Your simulation token.
Perimeter cells (List <String>) - A list of coordinates of each cell forming the perimeter, formatted as "x,y".
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getPerimeterCells/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
[84,77, 83,77, 82,76, 81,76, 80,76, 79,76, 78,76, 77,77, 76,77, 75,78, 75,79, 75,80, 75,81, 75,82, 75,83, 75,84, 76,84, 77,84, 78,84, 79,84, 80,84, 81,84, 82,84, 83,84, 84,84, 85,84, 85,83, 85,82, 85,81, 85,80, 85,79, 85,78]
Returns the state of a given cell.
userToken (String) - Your simulation token.
x (int) - Row to select.
y (int) - Column to select.
cellState (String) - State of the cell.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getCellState/?userToken="+key+"&x="+5+"&y="+10))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
"Burning"
Computes the length of the perimeter around the burn area.
userToken (String) - Your simulation token.
perimeterLength (double) - The perimeter of the burn area.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/computePerimeterLength/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
370
Computes the total burned area
userToken (String) - Your simulation token.
BurnedArea (double) - Total burned area.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/computeBurnedArea/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
890.0
Returns the total number of burning cells.
userToken (String) - Your simulation token.
totalBurningCells (int) - total number of burning cells.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getBurningCellNum/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
1240
Returns the total number of unburned cells.
userToken (String) - Your simulation token.
totalUnburnedCells (int) - total number of unburned cells.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getUnburnedCellNum/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
38760
Returns the dimensions of the cell space
userToken (String) - Your simulation token.
cellDimension (int) - the length and width of the cell space.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getCellSpaceSize/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
200
Returns the area of each cell.
userToken (String) - Your simulation token.
cellSize (int) - the cubic area of a cell.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getCellSize/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
30
Returns the direction the wind is blowing in.
userToken (String) - Your simulation token.
windDirection (double) - Set in degrees, where south is 0 and increasing values move clockwise (e.g. west is 90 and so on).
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getWindDegree/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
90
Returns the wind speed.
userToken (String) - Your simulation token.
windSpeed (double) - The speed the wind is moving.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getWindSpeed/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
5
Returns the current fuel map in use.
userToken (String) - Your simulation token.
fuelMap (int[][]) - A 2D array of numerical fuel values.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getCellFuel/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
[[1,1,1,1,1,1],[1,1,1,1,1,1],[1,1,1,1,1,1],...]
Returns the current slope map in use.
userToken (String) - Your simulation token.
slopeMap (double[][]) - A 2D array of numerical slope values.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getCellSlope/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
[[1,1,1,1,1,1],[1,1,1,1,1,1],[1,1,1,1,1,1],...]
Returns the current Aspect map in use.
userToken (String) - Your simulation token.
AspectMap (double[][]) - A 2D array of numerical aspect values.
1
2
3
4
5
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://firesim.cs.gsu.edu/api/getCellAspect/?userToken="+key))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
[[1,1,1,1,1,1],[1,1,1,1,1,1],[1,1,1,1,1,1],...]