Skip to content
EN

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.

GET /api/rooms/:roomId/science

Answers { "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.

PUT /api/rooms/:roomId/science
Content-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, with errors: [{ "path", "code" }] (for example { "path": "sources[3].measure", "code": "unknown_measure" }) and warnings for unknown keys. The room keeps its previous configuration.
  • 503 room_snapshot_unavailable means the room’s state could not be read safely. Retry.

DELETE /api/rooms/:roomId/science removes the configuration.

POST /api/rooms/:roomId/science/validate

Takes the same body as PUT and answers with the same errors, without writing anything.

POST /api/rooms/:roomId/science/sample
Content-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 } }] }
  • values holds one value per band. Nodata is null, never 0. Nothing is interpolated.
  • cell gives 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).
  • status is one of:
    • ok;
    • outside: the point lies off the raster;
    • warming: the server is fetching the file; ask again after retryAfter seconds;
    • 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.

POST /api/rooms/:roomId/science/stats
Content-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 }] }] }
  • count is how many of the cellCount cells hold data. Cells without data — nodata, masked or NaN — are left out of every statistic, and with none left, every statistic is null, never 0.
  • Percentiles are linear, std is 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.
  • partial is true when the shape reaches beyond the raster, and cellSizeM is a cell’s size on the ground in metres. repaired is true when an invalid shape (self-intersecting, overlapping parts) was repaired before counting.
  • status is one of:
    • ok;
    • outside: the shape lies off the raster;
    • warming: the server is fetching the file; ask again after retryAfter seconds;
    • 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 (windowCells says how many);
    • invalid_band: the raster has only bandCount bands;
    • 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.