REST API

The web app is a front end for this API. Interactive docs, generated by FastAPI, are at /docs on a running server.

Endpoints

Method	Path	Purpose
GET	/api/presets	Named example areas, grouped
GET	/api/search?q=...	Place search; each hit has a bbox
POST	/api/upload	Multipart heightmap upload; returns an upload_id
POST	/api/model	Build a model; returns stats, a preview PNG and download URLs
POST	/api/jobs	Same body as /api/model, built in the background; returns a job_id
GET	/api/jobs/{id}	Job status, current stage with done and total, and the /api/model response as result when done
GET	/api/model/{id}/{name}.stl	Binary STL
GET	/api/model/{id}/{name}.glb	Textured GLB, when glb_url is set
GET	/api/model/{id}/{name}.3mf	Multi-color 3MF, when threemf_url is set
GET	/api/model/{id}/heightmap.png	Hillshade preview

Build a model

curl -s localhost:7417/api/model -H 'content-type: application/json' -d '{
  "source": "terrarium",
  "bbox": {"south": 35.28, "west": 138.65, "north": 35.45, "east": 138.82},
  "width_mm": 150, "exaggeration": 1.2, "resolution": 512, "name": "fuji"
}' | python -c 'import json,sys; j=json.load(sys.stdin); print(j["stl_url"], j["info"]["height_mm"])'

The request body takes the same settings as the web app:

Field	Default	Meaning
source	terrarium	terrarium (satellite elevation), synthetic or upload
bbox		{south, west, north, east}, for terrarium
upload_id		From /api/upload, for upload
resolution	256	Grid columns, 32 to 1024
width_mm	100	Model width
base_mm	3	Base thickness
exaggeration	1.5	Vertical exaggeration
relief_mm		Fixed relief height; overrides exaggeration
smoothing	0	Gaussian smoothing, in grid pixels
clamp_sea_level	true	Flatten below-sea-level data
texture	true	Also write the textured GLB
buildings	false	Add OpenStreetMap buildings
building_scale	1	Building height multiplier
building_source	auto	auto, openfreemap, overpass or overture
bridges	false	Add OpenStreetMap bridges over water
bridge_piers_mm	20	Longest distance between bridge piers; 0 for none
roads	false	Add OpenStreetMap roads as raised strips
road_detail	auto	auto (by model scale), major (motorway to secondary) or all
multicolor	false	Also write the multi-color 3MF
frame_mm	0	Border frame width; 0 for none
frame_height_mm	base + 1	Frame height
name	terrain	Model name, used in the file names

Buildings, bridges, roads, the texture and the multi-color 3MF need a terrarium source. When one of their downloads fails, you still get the STL, and info says why in building_error, bridge_error, road_error, texture_error or water_error. With bridges on, info.bridges is the number of bridges built, and with roads on, info.roads is the number of connected road networks. When the roof shapes could not be fetched, the buildings are flat-roofed and building_warning says so.

Build in the background

POST /api/jobs takes the same body and returns at once. Poll GET /api/jobs/{id} until status is done or error:

{"job_id": "a156e11b566b", "status": "running", "stage": "buildings",
 "done": 4, "total": 9, "elapsed_s": 1.2, "result": null, "error": null}

When it is done, result holds the same response /api/model returns.