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/health

Version, API revision, capability flags and the runtime status of each engine.

GET /api/engines

Every 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-sources

auto, global and every registered building source with title, version, attribution, licence and whether it takes part in automatic routing.

GET /api/antenna-sources

auto and 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). Returns 502 when the service is unavailable.

Buildings for browsing#

GET /api/buildings?latitude=&longitude=&radius_m=&building_source=

Buildings around a point for display, with radius_m from 100 to 2,500 m, limited to OWRT_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. 422 for an invalid source or a source that does not cover the point, 502 for a provider failure or for source geometry that cannot be placed.

Compiled scenes#

POST /api/scenes

Body: a SceneRequest with latitude, longitude, radius_m, include_buildings, building_source, include_terrain, material_profile and terrain_resolution_m, the same inputs as owrt.load_scene. Compiles into the shared scene cache, or reuses the directory for identical inputs, and returns a SceneResponse: the scene_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. 422 for invalid inputs or a source that does not cover the centre, 502 for a provider failure.

GET /api/scenes/{scene_id}

The same payload for a scene already in the cache, read without a provider query. 404 when it is not there, 422 for a malformed identifier or a scene that declares another RF material profile version; compile such a scene again with POST /api/scenes.

Antennas#

POST /api/antennas

Body: an AntennaRequest with either a scene_id, whose scene must be in the cache, or latitude, longitude and radius_m (100 to 5,000 m), and the optional antenna_source (default auto), operator, radio, channel as {"low_mhz", "high_mhz"} and defaults (Antennas). With a scene_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. The AntennaResponse holds the selected antennas, the operators, radios and channels present before selection, the selected channel, the defaults, warnings and provenance. 404 when the scene is not in the cache, 422 for invalid inputs, a scene of another RF material profile version, or a source that does not cover the centre or is not configured, 502 for a provider failure.

Simulations#

POST /api/simulations

Body: a SimulationRequest (Sionna RT lists the engine_config keys). The optional scene_center sets 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 with 422. radius_m runs from 100 to 5,000 m and resolution_m from 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/scenes would, then runs the solve on the persisted scene assets. The SimulationResponse contains the simulation ID, the selected engine, elapsed time, a coverage grid with the display layers and grid mapping, the buildings and geometry context, warnings, solver details, provenance (including scene_id and scene_cache_hit), the environment context and the full scene payload. Errors: 409 when the runtime of the engine is unavailable, 422 for invalid parameters, 502 for provider failures, 500 when the solve fails.

GET /api/simulations/{id}/raster.png?metric=rss&mask_buildings=true&smooth=false

A north-up PNG of one metric (path_gain, rss, sinr, association) rendered from the stored arrays, one pixel per solver cell; mask_buildings leaves the cells whose receiver point lies inside a building transparent. With smooth=true and mask_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.zip

The artifact bundle (Exports).

The service keeps the 16 most recent results in memory; older IDs return 404.

Batches#

POST /api/batches/plan

Body: a BatchDatasetRequest. Returns the expanded BatchPlan without touching providers.

POST /api/batches?resume=false

Starts generation and returns 202 with a job record. 409 when the dataset exists without resume, when the same dataset is already running, or when Sionna radio maps are requested without the runtime.

GET /api/batches

All 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}/manifest

The 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