HTTP API#
The interactive OpenAPI documentation lives at /api/docs and the schema at
/api/openapi.json. Request and response models are the Pydantic classes in
openworld_radio_twin.models and openworld_radio_twin.batch
(API reference). All examples below assume the default loopback address.
Health and catalogs#
GET /api/healthVersion, API revision, capability flags and the runtime status of each engine.
GET /api/enginesEvery engine of the engine registry with its label, description, input and output contracts, parameters and runtime status. An engine whose runtime is not available is listed with the message that says why.
GET /api/building-sourcesauto,globaland every registered building source with title, version, attribution, licence and whether it takes part in automatic routing.GET /api/antenna-sourcesautoand every registered antenna source with title, version, attribution, licence, whether it takes part in automatic routing, and whether it is configured, with the setting it needs when it is not.GET /api/search?q=<text>Location search through Nominatim (
OWRT_NOMINATIM_URL). Returns502when the service is unavailable.
Buildings for browsing#
GET /api/buildings?latitude=&longitude=&radius_m=&building_source=Buildings around a point for display, with
radius_mfrom 100 to 2,500 m, limited toOWRT_MAX_VIEW_BUILDINGS. The response carries the features, their native or extruded geometry context, warnings and a provenance record with the resolved source, release, counts and limit status.422for an invalid source or a source that does not cover the point,502for a provider failure or for source geometry that cannot be placed.
Compiled scenes#
POST /api/scenesBody: a
SceneRequestwithlatitude,longitude,radius_m,include_buildings,building_source,include_terrain,material_profileandterrain_resolution_m, the same inputs asowrt.load_scene. Compiles into the shared scene cache, or reuses the directory for identical inputs, and returns aSceneResponse: thescene_id(the cache directory name), whether it was a cache hit, the bounds with WGS84 corners, the persisted buildings and their native geometry, the terrain grid and surface classes, warnings and provenance.422for invalid inputs or a source that does not cover the centre,502for a provider failure.GET /api/scenes/{scene_id}The same payload for a scene already in the cache, read without a provider query.
404when it is not there,422for a malformed identifier or a scene that declares another RF material profile version; compile such a scene again withPOST /api/scenes.
Antennas#
POST /api/antennasBody: an
AntennaRequestwith either ascene_id, whose scene must be in the cache, orlatitude,longitudeandradius_m(100 to 5,000 m), and the optionalantenna_source(defaultauto),operator,radio,channelas{"low_mhz", "high_mhz"}anddefaults(Antennas). With ascene_id, the antennas are placed in that scene as its Sionna transmitters would be and recorded in the scene directory; with an area, they are completed with the defaults but not placed. TheAntennaResponseholds the selected antennas, the operators, radios and channels present before selection, the selected channel, the defaults, warnings and provenance.404when the scene is not in the cache,422for invalid inputs, a scene of another RF material profile version, or a source that does not cover the centre or is not configured,502for a provider failure.
Simulations#
POST /api/simulationsBody: a
SimulationRequest(Sionna RT lists theengine_configkeys). The optionalscene_centersets the centre of the compiled square; without it the first transmitter is the centre. Every transmitter must lie inside the square, otherwise the request is rejected with422.radius_mruns from 100 to 5,000 m andresolution_mfrom 0.1 to 200 m. The radio grid may hold at most 20,000 cells for the preview and 2,250,000 for Sionna and the other engines, the terrain grid of a DEM scene at most 250,000 cells, and the transmitters share the budgets of Resolution and ray budget.curl -s http://127.0.0.1:8765/api/simulations \ -H 'Content-Type: application/json' \ -d '{ "engine": "preview", "radius_m": 500, "resolution_m": 25, "include_terrain": false, "transmitters": [ {"position": {"latitude": 52.3762, "longitude": 4.8993, "altitude_m": 25}, "frequency_ghz": 3.5, "power_dbm": 30, "antenna_pattern": "sector"} ] }'
The service first compiles or reuses the scene at that centre, as
POST /api/sceneswould, then runs the solve on the persisted scene assets. TheSimulationResponsecontains the simulation ID, the selectedengine, elapsed time, a coverage grid with the display layers and grid mapping, the buildings and geometry context, warnings, solver details, provenance (includingscene_idandscene_cache_hit), the environment context and the full scene payload. Errors:409when the runtime of the engine is unavailable,422for invalid parameters,502for provider failures,500when the solve fails.GET /api/simulations/{id}/raster.png?metric=rss&mask_buildings=true&smooth=falseA north-up PNG of one metric (
path_gain,rss,sinr,association) rendered from the stored arrays, one pixel per solver cell;mask_buildingsleaves the cells whose receiver point lies inside a building transparent. Withsmooth=trueandmask_buildings=true, a continuous metric on cells coarser than 2 m is drawn on finer samples instead, at most 2 m apart unless the image would exceed 2048 pixels per side: colours are interpolated between cell centres, cells whose receiver point lies inside a building take the mean colour of the drawn cells around them, and the samples inside a building stay transparent. Grids of more than 1024 cells per side, and scenes in which no sample lies inside a building, keep one pixel per cell.GET /api/simulations/{id}/artifacts.zipThe artifact bundle (Exports).
The service keeps the 16 most recent results in memory; older IDs return 404.
Batches#
POST /api/batches/planBody: a
BatchDatasetRequest. Returns the expandedBatchPlanwithout touching providers.POST /api/batches?resume=falseStarts generation and returns
202with a job record.409when the dataset exists without resume, when the same dataset is already running, or when Sionna radio maps are requested without the runtime.GET /api/batchesAll jobs known to this process, newest first.
GET /api/batches/{job_id}One job: status (
queued,running,completed,completed_with_errors,failed), completed and total radio maps (completed_radio_maps,total_radio_maps), message, output directory, error.GET /api/batches/{job_id}/manifestThe dataset manifest once the job has completed.
Python client sketch#
import httpx
with httpx.Client(base_url="http://127.0.0.1:8765") as client:
health = client.get("/api/health").json()
response = client.post("/api/simulations", json=request, timeout=600).json()
png = client.get(f"/api/simulations/{response['simulation_id']}/raster.png",
params={"metric": "sinr"}).content