Analyzer
The Analyzer API provides access to simulation output data that is used by the SESAM Analyzer. The endpoints described here are intended for retrieving result data of an existing simulation run or a simulation-level overview.
Most endpoints require the simulation_run_id of a simulation run that belongs to the current user.
The simulation runs overview endpoints require the simulation_id instead.
Simulation runs can be retrieved through the workspace simulation endpoints.
Note
Some analyzer datasets are only available when the corresponding output was enabled for the simulation. For example, trip data requires tripinfo output and FCD (Floating Car Data) playback data requires geo FCD output.
Scenario Data
These endpoints describe the underlying scenario rather than the result of a specific run. They are addressed by a simulation_run_id, but the data is the same for every run of the simulation.
Network
The analyzer/ds/network/{simulation_run_id} endpoint returns the detailed road-network GeoJSON for the simulation that owns the given simulation run.
The response is a GeoJSON FeatureCollection and contains the network representation used by the Analyzer map.
| HTTP Example | |
|---|---|
Vehicle Types
The analyzer/ds/vtypes/{simulation_run_id} endpoint returns SUMO vehicle type definitions for a simulation run as JSON.
The Analyzer uses this data for vehicle classes, dimensions, and rendering metadata.
SESAM extracts the available vehicle types from the running SUMO simulation and stores them with the simulation results.
| HTTP Example | |
|---|---|
Simulation Runs Overview
The simulation runs overview aggregates the results of all successful runs of a simulation into a single set of artifacts.
Unlike the other analyzer endpoints, the overview endpoints are addressed by the simulation_id of the simulation (not a single simulation_run_id), because they describe the simulation as a whole.
The simulation_id can be retrieved through the workspace simulation endpoints.
Note
An overview is only built when a simulation has at least two successful simulation runs.
For simulations with fewer than two successful runs, the overview endpoints return 404.
Each numeric metric is aggregated across the runs into three columns: <metric> (mean across the runs), <metric>_stddev (standard deviation across the runs, 0.0 for a single sample), and <metric>_count (number of runs that contained a value for that element).
Elements that are missing from a run simply do not contribute, so <metric>_count reflects how many runs actually had the value.
Overview Metadata
The analyzer/ds/overview/{simulation_id} endpoint returns the database metadata of the simulation runs overview as JSON.
Use this endpoint when accessing overview results through the backend API without loading the Analyzer frontend.
The response includes the overview analysis id, lifecycle state, aggregated simulation run ids, and global database-backed metrics.
Each metric under metrics contains sample_count, mean, and stddev.
| HTTP Example | |
|---|---|
Overview Edge Data
The analyzer/ds/overview-edges/{simulation_id} endpoint streams the aggregated edge data of the simulation runs overview as a Parquet file.
The response uses the content type application/vnd.apache.parquet and supports byte-range requests.
There is one row per edge id, aggregated across all successful runs; streetname is carried over from the runs.
The underlying per-run values are based on SUMO lane-/edge-based traffic measures; see the SUMO Lane- or Edge-based Traffic Measures documentation for the meaning of the metrics.
Use a Parquet-capable client library such as PyArrow, pandas, DuckDB, or hyparquet to read the response.
| HTTP Example | |
|---|---|
Overview Trips Data
The analyzer/ds/overview-trips/{simulation_id} endpoint streams the aggregated trips data of the simulation runs overview as a Parquet file.
The response uses the content type application/vnd.apache.parquet and supports byte-range requests.
There is one row per trip id, aggregated across all successful runs; trip_kind, vtype, and vclass are carried over from the runs.
This data is available only when tripinfo output was enabled for the simulation.
The underlying per-run values are derived from SUMO tripinfo output; see the SUMO TripInfo output documentation for the meaning of the trip fields.
As with the per-run Trips Data, all time values are in seconds, route_length is in meters, depart_speed / arrival_speed are in m/s, and speed_factor is dimensionless.
Use a Parquet-capable client library such as PyArrow, pandas, DuckDB, or hyparquet to read the response.
| HTTP Example | |
|---|---|
Overview Trip Info
The analyzer/ds/overview-tinfos/{simulation_id} endpoint returns pooled trip histogram data of the simulation runs overview as JSON.
This data is used for the Analyzer trip statistics chart in the overview.
In contrast to the per-trip aggregation of the other overview artifacts, the histograms pool every (trip, run) value into one distribution, so the real run-to-run spread of the trip outcomes is preserved.
The response shape matches the per-run Trip Info endpoint: one histogram per metric under metrics (duration, route_length, time_loss, waiting_time), each with an all histogram and optional by_trip_kind and by_vclass breakdowns, where every histogram contains bins (bin edges) and counts (count per bin, length len(bins) - 1). In addition to num_trips, available_trip_kinds, and available_vclasses, the top-level meta object reports num_runs (the number of pooled runs).
This endpoint is available only when tripinfo output was generated for the simulation; if the histograms were not produced, the response is an empty JSON object.
| HTTP Example | |
|---|---|
Single Run Data
These endpoints return the result data of a single simulation run and are addressed by its simulation_run_id.
Edge Data
The analyzer/ds/edges/{simulation_run_id} endpoint returns aggregated edge result data for a simulation run as JSON.
This data is used for the Analyzer edge table and analysis map.
The values are based on SUMO lane-/edge-based traffic measures; see the SUMO Lane- or Edge-based Traffic Measures documentation for the meaning of the underlying output fields.
If the optional edge data file is not available, the endpoint returns an empty JSON object.
| HTTP Example | |
|---|---|
Trips Data
The analyzer/ds/trips/{simulation_run_id} endpoint streams normalized trip output for a simulation run as a Parquet file.
This data is available only when tripinfo output was generated for the simulation.
The response combines vehicle trips and person trips into a single dataset and includes both completed and uncompleted trips.
Uncompleted trips (entities that were still in transit when the simulation ended) can be identified by arrival being null. For those trips the metrics duration, route_length, time_loss, and waiting_time contain the partial values accumulated up to the simulation cutoff, not the values of a finished trip.
Use a Parquet-capable client library such as PyArrow, pandas, DuckDB, or hyparquet to read the response.
The Parquet file is derived from SUMO tripinfo output; see the SUMO TripInfo output documentation for the meaning of the underlying trip fields.
All time values (depart, arrival, duration, time_loss, waiting_time) are in seconds of simulation time, route_length is in meters, and depart_speed / arrival_speed are in m/s. speed_factor is dimensionless. trip_kind is either vehicle or person.
| HTTP Example | |
|---|---|
| Parquet Schema | |
|---|---|
Trip Info
The analyzer/ds/tinfos/{simulation_run_id} endpoint returns precomputed trip histogram data as JSON.
This data is used for the Analyzer trip statistics chart.
The histograms are computed from completed trips only and cover both vehicle trips and person trips.
Trips that did not finish within the simulation are not included.
The response contains one histogram per metric under metrics. The available metrics are duration (seconds), route_length (meters), time_loss (seconds), and waiting_time (seconds). Each metric provides an all histogram and may additionally provide breakdowns under by_trip_kind (keys vehicle, person) and by_vclass (keys are SUMO vehicle classes). Each histogram contains bins (bin edges) and counts (count per bin, length len(bins) - 1). The top-level meta object reports num_trips, available_trip_kinds, and available_vclasses.
This endpoint is available only when tripinfo output was generated for the simulation.
| HTTP Example | |
|---|---|
Vehicle Routes
The analyzer/ds/vroutes/{simulation_run_id} endpoint returns vehicle route data for a simulation run as JSON.
The Analyzer uses this data to show and highlight vehicle routes.
The values are derived from SUMO vehicle routes output; see the SUMO VehRoutes output documentation for details.
If the optional route data file is not available, the endpoint returns an empty JSON object.
| HTTP Example | |
|---|---|
FCD Metadata
The analyzer/ds/fcd/meta/{simulation_run_id} endpoint returns metadata for generated FCD playback data as JSON.
This metadata describes how the FCD Parquet data is organized for playback and provides the mapping from the numeric entity_id used in the FCD Parquet file to the original SUMO entity id and its kind.
The response contains the time and step layout of the recording (scenario_begin, scenario_duration, step_min, step_max, step_length, time_min, time_max, step_count), a summary of the recorded entities (entity_count, has_vehicles, has_persons, row_group_count), and the per-entity table under entities. Each entry in entities provides entity_id (the numeric id used in the FCD Parquet rows), entity (the original SUMO id string), is_vehicle (true for vehicles, false for persons), and vtype. step_length is given in seconds and is the same simulation step length that the step column in the FCD and TLS Parquet files refers to.
This endpoint is available only when FCD output was generated for the simulation.
| HTTP Example | |
|---|---|
FCD Parquet
The analyzer/ds/fcd/parquet/{simulation_run_id} endpoint streams generated geo FCD playback data for a simulation run as a Parquet file.
The response uses the content type application/vnd.apache.parquet and supports byte-range requests.
The dataset combines vehicle and person movements into a single Parquet file, with each row identified by entity_id.
entity_id is a numeric id that is assigned by SESAM and only valid within this simulation run. To resolve it to the original SUMO entity id and to determine whether the row belongs to a vehicle or a person, use the FCD Metadata endpoint, which provides the entity_id → (entity, is_vehicle, vtype) mapping under entities.
step is a zero-based simulation step index that matches step_min / step_max / step_count in the FCD metadata. Multiply step by step_length (from the FCD metadata, in seconds) and add scenario_begin to obtain the simulation time in seconds. lon and lat are WGS84 coordinates in degrees, angle is the heading in degrees, and speed is in m/s.
This endpoint is available only when FCD output was generated for the simulation.
| HTTP Example | |
|---|---|
Example schema and rows after reading the Parquet response:
| Parquet Schema | |
|---|---|
| Example Rows | |
|---|---|
TLS Parquet
The analyzer/ds/tls/parquet/{simulation_run_id} endpoint streams traffic light state data for a simulation run as a Parquet file.
The response uses the content type application/vnd.apache.parquet and supports byte-range requests.
The fields are derived from SUMO traffic light state output; see the SUMO Traffic Lights output documentation for the meaning of tls_id, program_id, phase, and state.
step uses the same zero-based simulation step index as the FCD Parquet file. To convert it to simulation time in seconds, multiply by step_length from the FCD Metadata response and add scenario_begin.
| HTTP Example | |
|---|---|
Example schema and rows after reading the Parquet response:
| Parquet Schema | |
|---|---|