Zum Inhalt springen
DE

Wissenschaftspanel

Die Science-Konfiguration eines Raums (comap.science/2, siehe Wissenschaftspanel konfigurieren), das Lesen von Punkten, auf dem ihre Ansichten beruhen, und die Kennzahlen in einer Form, die Objekt-Popups lesen (siehe Die Raster unter einem Objekt lesen).

Methode Pfad Token-Berechtigung
GET /api/rooms/:roomId/science read (anonym in einem öffentlichen Raum)
PUT /api/rooms/:roomId/science write
DELETE /api/rooms/:roomId/science write
POST /api/rooms/:roomId/science/validate write; speichert nichts
POST /api/rooms/:roomId/science/sample read (anonym in einem öffentlichen Raum)
POST /api/rooms/:roomId/science/stats read (anonym in einem öffentlichen Raum)

Angemeldete Mitglieder brauchen dieselben Rechte: Eigentümer und Bearbeiter schreiben, und alle, die den Raum sehen können, lesen.

GET /api/rooms/:roomId/science

Antwortet mit { "settings": null }, wenn der Raum keine hat, sonst:

{ "settings": { "version": 2, "config": { "schema": "comap.science/2", "…": "…" },
"bindings": {}, "updatedAt": 1792300000000, "updatedBy": "api-token:my-script" } }

updatedBy ist die Client-ID des speichernden Tabs oder api-token:<name> des Tokens, nie ein Name oder eine E-Mail-Adresse.

PUT /api/rooms/:roomId/science
Content-Type: application/json
{ "config": { "schema": "comap.science/2", "…": "…" }, "bindings": { "obs-mean": "tiff-1760000000000-example" } }

bindings (optional) bindet einen Quellschlüssel an die ID einer Rasterebene, für einen Ebenennamen, der mehrdeutig ist oder sich geändert hat.

  • Eine ungültige Konfiguration wird als Ganzes abgelehnt und nie teilweise gespeichert: 400 invalid_science_config mit errors: [{ "path", "code" }] (zum Beispiel { "path": "sources[3].measure", "code": "unknown_measure" }) und warnings für unbekannte Schlüssel. Der Raum behält seine bisherige Konfiguration.
  • 503 room_snapshot_unavailable bedeutet, dass der Zustand des Raums nicht sicher gelesen werden konnte. Versuchen Sie es erneut.

DELETE /api/rooms/:roomId/science entfernt die Konfiguration.

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

Nimmt denselben Rumpf wie PUT und antwortet mit denselben Fehlern, ohne etwas zu schreiben.

POST /api/rooms/:roomId/science/sample
Content-Type: application/json
{ "lon": 8.553, "lat": 47.256, "layers": [{ "layerId": "tiff-1760000000000-example" }] }

Liest alle Bänder von 1 bis 24 Rasterebenen in der gespeicherten Zelle unter dem Punkt:

{ "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 enthält einen Wert pro Band. Nodata ist null, nie 0. Nichts wird interpoliert.
  • cell gibt Spalte und Zeile der Zelle an, ihre vier Ecken als [lon, lat] im Uhrzeigersinn ab oben links und, bei einem projizierten Raster, ihre Größe in den Einheiten des Rasters (sizeM).
  • status ist einer von:
    • ok;
    • outside: Der Punkt liegt außerhalb des Rasters;
    • warming: Der Server holt die Datei; fragen Sie nach retryAfter Sekunden erneut;
    • not_found: eine unbekannte ID oder eine Ebene eines anderen Raums (beide Antworten sind gleich);
    • error.

503 geo_service_busy (mit Retry-After) bittet, es später erneut zu versuchen, und 502 sample_failed bedeutet, dass das Lesen fehlgeschlagen ist. Der Endpunkt ist auf 120 Anfragen pro Minute und Aufrufer begrenzt.

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] }] }

Nimmt ein GeoJSON-Polygon oder -MultiPolygon in Länge und Breite sowie 1 bis 8 Rasterebenen mit den zu lesenden Bändern: höchstens 16 Paare aus Ebene und Band insgesamt und höchstens 5000 Positionen in der Form. Für jedes Band antwortet er mit den Kennzahlen der Zellen, deren Mittelpunkt in der Form liegt, Löcher ausgenommen:

{ "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 gibt an, wie viele der cellCount Zellen Daten enthalten. Zellen ohne Daten — Nodata, maskiert oder NaN — bleiben bei jeder Kennzahl weg, und bleibt keine übrig, ist jede Kennzahl null, nie 0.
  • Perzentile sind linear, std ist die Standardabweichung der Grundgesamtheit, und die Werte sind die gespeicherten, auf 7 signifikante Stellen gerundet.
  • Eine Form, die zu klein ist, um einen Zellmittelpunkt zu enthalten, liest stattdessen die Zelle darunter (cellRule: "point"), sodass auch eine kleine Form ihre eigene Zelle liest; dieser Wert ist derselbe wie beim Lesen am Punkt.
  • partial ist true, wenn die Form über das Raster hinausreicht, und cellSizeM ist die Größe einer Zelle am Boden in Metern. repaired ist true, wenn eine ungültige Form (selbstüberschneidend, überlappende Teile) vor dem Zählen repariert wurde.
  • status ist einer von:
    • ok;
    • outside: Die Form liegt außerhalb des Rasters;
    • warming: Der Server holt die Datei; fragen Sie nach retryAfter Sekunden erneut;
    • not_found: eine unbekannte ID oder eine Ebene eines anderen Raums (beide Antworten sind gleich);
    • too_large: Der umgebende Rahmen der Form würde mehr Zellen lesen, als eine Anfrage darf (windowCells sagt, wie viele);
    • invalid_band: Das Raster hat nur bandCount Bänder;
    • error.

Eine abgelehnte Anfrage antwortet mit 400 und dem ersten Problem samt seiner Stelle: { "error": "invalid_request" | "shape_too_complex" | "invalid_shape", "path": "layers[0].bands[1]" }. Eine Form, von der nach der Reparatur keine Fläche übrig bleibt, ist invalid_shape. Der Rumpf umfasst höchstens 256 KiB (413 darüber). 503 geo_service_busy (mit Retry-After) bittet, es später erneut zu versuchen, und 502 stats_failed bedeutet, dass das Lesen fehlgeschlagen ist. Der Endpunkt ist auf 120 Anfragen pro Minute und Aufrufer begrenzt.