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
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, 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, texture_error or water_error. 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.