Science Panel
A room’s Science configuration (comap.science/2, see Configure the Science
Panel), the point sampling its views read, and the statistics inside a shape
that feature popups read (see Read the rasters under a
feature).
| Method | Path | Token permission |
|---|---|---|
GET |
/api/rooms/:roomId/science |
read (anonymous in a public room) |
PUT |
/api/rooms/:roomId/science |
write |
DELETE |
/api/rooms/:roomId/science |
write |
POST |
/api/rooms/:roomId/science/validate |
write; saves nothing |
POST |
/api/rooms/:roomId/science/sample |
read (anonymous in a public room) |
POST |
/api/rooms/:roomId/science/stats |
read (anonymous in a public room) |
Signed-in members need the same rights: owners and editors write, and anyone who can view the room reads.
Read the configuration
Section titled “Read the configuration”GET /api/rooms/:roomId/scienceAnswers { "settings": null } when the room has none, or:
{ "settings": { "version": 2, "config": { "schema": "comap.science/2", "…": "…" }, "bindings": {}, "updatedAt": 1792300000000, "updatedBy": "api-token:my-script" } }updatedBy is the saving tab’s client ID or the token’s api-token:<name>, never a name or e-mail
address.
Store or remove it
Section titled “Store or remove it”PUT /api/rooms/:roomId/scienceContent-Type: application/json{ "config": { "schema": "comap.science/2", "…": "…" }, "bindings": { "obs-mean": "tiff-1760000000000-example" } }bindings (optional) pins a source key to a raster layer ID, for a layer name that is ambiguous or
has changed.
- An invalid configuration is refused whole and never stored in part:
400 invalid_science_config, witherrors: [{ "path", "code" }](for example{ "path": "sources[3].measure", "code": "unknown_measure" }) andwarningsfor unknown keys. The room keeps its previous configuration. 503 room_snapshot_unavailablemeans the room’s state could not be read safely. Retry.
DELETE /api/rooms/:roomId/science removes the configuration.
Check without saving
Section titled “Check without saving”POST /api/rooms/:roomId/science/validateTakes the same body as PUT and answers with the same errors, without writing anything.
Read values at a point
Section titled “Read values at a point”POST /api/rooms/:roomId/science/sampleContent-Type: application/json{ "lon": 8.553, "lat": 47.256, "layers": [{ "layerId": "tiff-1760000000000-example" }] }Reads every band of 1 to 24 raster layers at the stored cell under the point:
{ "layers": [{ "layerId": "tiff-1760000000000-example", "status": "ok", "bandCount": 1, "values": [2.2], "cell": { "col": 1150, "row": 422, "corners": [[8.5509, 47.2575], [8.5532, 47.2575], [8.5532, 47.2560], [8.5509, 47.2560]], "sizeM": 250 } }] }valuesholds one value per band. Nodata isnull, never0. Nothing is interpolated.cellgives the cell’s column and row, its four corners as[lon, lat]clockwise from the top left, and, for a projected raster, its size in the raster’s own units (sizeM).statusis one of:ok;outside: the point lies off the raster;warming: the server is fetching the file; ask again afterretryAfterseconds;not_found: an unknown ID, or a layer of another room (the two answers are identical);error.
503 geo_service_busy (with Retry-After) asks you to try again later, and 502 sample_failed means
the read failed. The endpoint is rate-limited to 120 requests per minute per caller.
Read statistics inside a shape
Section titled “Read statistics inside a shape”POST /api/rooms/:roomId/science/statsContent-Type: application/json{ "geometry": { "type": "Polygon", "coordinates": [[[8.55, 47.25609], [8.55013, 47.25609], [8.55013, 47.256], [8.55, 47.256], [8.55, 47.25609]]] }, "layers": [{ "layerId": "tiff-1760000000000-example", "bands": [1] }] }Takes a GeoJSON Polygon or MultiPolygon in longitude and latitude, and 1 to 8 raster layers with
the bands to read: at most 16 layer–band pairs in all, and at most 5,000 positions in the shape. For each
band it answers the statistics of the cells whose centre lies inside the shape, holes excluded:
{ "repaired": false, "layers": [{ "layerId": "tiff-1760000000000-example", "status": "ok", "bandCount": 1, "cellCount": 25, "cellRule": "centre", "partial": false, "cellSizeM": 2, "bands": [{ "band": 1, "count": 25, "mean": 0.4312, "median": 0.4357, "p10": 0.3904, "p90": 0.4655, "min": 0.3725, "max": 0.4801, "std": 0.0291 }] }] }countis how many of thecellCountcells hold data. Cells without data — nodata, masked or NaN — are left out of every statistic, and with none left, every statistic isnull, never0.- Percentiles are linear,
stdis the population standard deviation, and the values are the stored ones, rounded to 7 significant digits. - A shape too small to hold a cell’s centre reads the cell under it instead (
cellRule: "point"), so a small shape still reads its own cell; that value equals the point sample’s. partialistruewhen the shape reaches beyond the raster, andcellSizeMis a cell’s size on the ground in metres.repairedistruewhen an invalid shape (self-intersecting, overlapping parts) was repaired before counting.statusis one of:ok;outside: the shape lies off the raster;warming: the server is fetching the file; ask again afterretryAfterseconds;not_found: an unknown ID, or a layer of another room (the two answers are identical);too_large: the shape’s bounding box would read more cells than one request may (windowCellssays how many);invalid_band: the raster has onlybandCountbands;error.
A refused request answers 400 with the first problem and where it is:
{ "error": "invalid_request" | "shape_too_complex" | "invalid_shape", "path": "layers[0].bands[1]" }.
A shape without any area left after repair is invalid_shape. The body is at most 256 KiB (413
above). 503 geo_service_busy (with Retry-After) asks you to try again later, and 502 stats_failed
means the read failed. The endpoint is rate-limited to 120 requests per minute per caller.