Schnellstart: einen Raum mit cURL steuern

Dies ist die „gib mir einfach die Befehle“-Anleitung, um alles in einem Raum über HTTP mit einem raumbezogenen Token (cmap_…) zu erledigen — ohne Browsersitzung, ohne Benutzeranmeldung. Die vollständige Endpunktliste steht in der Referenz.

Denkmodell

Ein Raum-Token ist eigenständig: Stellen Sie es einmal für einen Raum aus und verwenden Sie es direkt. Es handelt für die Daten dieses Raums wie dessen Eigentümer, kann aber nie Eigentümer-/Admin-Dinge tun (Raum löschen/umbenennen, Mitglieder einladen, Ihr Konto lesen, weitere Tokens ausstellen) — die liefern absichtlich 403 api_token_not_allowed.

1. Ein Token besorgen

Stellen Sie ein Token als Raumeigentümer aus — in der App (Meine Räume → Schaltfläche API auf der Raumkarte) oder über HTTP mit Ihrem Eigentümer-JWT. Einzelheiten unter Raum-API-Tokens.

curl -X POST "$API/api/rooms/$ROOM/api-tokens" \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name":"my-script","permissions":["read","write","upload"],"expiresInDays":30}'
# → { "token": "cmap_…", "id": "…" }

2. Die Shell einrichten

export API=https://collmap.com     # production  (use http://localhost:3001 for local dev)
export ROOM=aB3dEfGhIj             # the 10-char room id — it's in the map URL: /map/<ROOM>
export TOKEN=cmap_xxxxxxxxxxxx     # your room token
AUTH="Authorization: Bearer $TOKEN"

(Die Beispiele leiten zur besseren Lesbarkeit durch jq — optional.)

3. Kurzer Funktionstest

curl -s "$API/api/rooms/$ROOM" -H "$AUTH" | jq .     # → room metadata (200) for a read token

• 200 → alles verdrahtet.
• 403 „API token is not scoped to this room“ → $ROOM passt nicht zum Raum des Tokens.
• 403 „API token lacks ‘read’ permission“ → neu ausstellen, read einschließen.

4. Daten in den Raum schreiben

Eine Vektorebene hochladen upload

GeoJSON, gezipptes Shapefile oder GeoPackage. Größere Vektorverarbeitung läuft asynchron → Sie bekommen eine jobId.

curl -X POST "$API/api/layers/upload" -H "$AUTH" \
  -F "roomName=$ROOM" -F "layerName=my-layer" -F "file=@data/my-layer.geojson"
# → { "jobId": "job-…", ... }   then poll:
curl -s "$API/api/layers/jobs/<jobId>" -H "$AUTH" | jq '{stage,progress,message}'

Ein GeoTIFF hochladen upload

Derselbe Endpunkt; eine .tif/.tiff wird in die Raster-Pipeline geleitet. Legen Sie die Darstellung gleich fest:

# single-band: colormap + stretch
curl -X POST "$API/api/layers/upload" -H "$AUTH" \
  -F "roomName=$ROOM" -F "layerName=elevation" -F "file=@data/dem.tif" \
  -F 'display={"colormap":"terrain","band":1,"vmin":0,"vmax":1500,"opacity":0.8}'

# multi-band: an RGB composite
curl -X POST "$API/api/layers/upload" -H "$AUTH" \
  -F "roomName=$ROOM" -F "layerName=truecolor" -F "file=@data/scene.tif" \
  -F 'display={"renderMode":"rgb","rgbBands":[1,2,3]}'

Einen einzelnen Marker anlegen write

Synchron — liefert den angelegten Marker samt Id zurück.

curl -X POST "$API/api/rooms/$ROOM/markers" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"latitude":47.5596,"longitude":7.5886,"title":"Site A","description":"first visit","tags":["survey"]}'
# → 201 { "success": true, "marker": { "id": "marker-…", ... } }

Pflicht sind nur latitude/longitude. Optional: title, description, color (Hex), tags, eventDate (Epoch ms), markerIconId, markerIconSize, imageKey/thumbnailKey, embeddedMediaUrl, mediaSize.

Einen Marker aktualisieren oder löschen write

# read one back
curl -s "$API/api/rooms/$ROOM/markers/$MARKER" -H "$AUTH" | jq '.marker.title'

# change only what you name; null clears a field
curl -X PATCH "$API/api/rooms/$ROOM/markers/$MARKER" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"title":"Site A (revisited)","description":null,"color":"#ef4444"}'

curl -X DELETE "$API/api/rooms/$ROOM/markers/$MARKER" -H "$AUTH"
# → 200 { "success": true, "markerId": "marker-…" }

latitude, longitude, title und color lassen sich ändern, aber nicht leeren; imageKey und thumbnailKey müssen gemeinsam gesendet werden. Ein leerer Rumpf wird als empty_update abgelehnt. Beide Aufrufe erscheinen live in offenen Browsern und landen im Verlauf des Raums.

Achtung

Ein write-Token kann jeden Marker im Raum bearbeiten oder löschen, nicht nur selbst angelegte.

Marker massenhaft aus Punkt-GeoJSON anlegen write

curl -X POST "$API/api/rooms/$ROOM/bulk-import" -H "$AUTH" -F "file=@data/points.geojson"
# → { "jobId": "bulk-import-…" };  poll: curl -s "$API/api/jobs/<jobId>" -H "$AUTH" | jq .

Eine Ebene aus Inline-GeoJSON erzeugen write

curl -X POST "$API/api/rooms/$ROOM/layers" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"drawn","description":"study area","geojson":{"type":"FeatureCollection","features":[]},
       "color":"e11d48","opacity":0.35,"strokeWeight":3,"visible":true}'

Hinweis

Setzen Sie den Stil (color, opacity, strokeWeight, visible, description) beim Anlegen bzw. Hochladen — er wirkt sofort. PATCH /api/layers/:id aktualisiert die Datenbankzeile, gestaltet die Karte aber nicht neu.

5. Daten zurücklesen

curl -s "$API/api/layers/$ROOM" -H "$AUTH" | jq '.layers[].name'                 # layers
curl -s "$API/api/rooms/$ROOM/markers" -H "$AUTH" | jq '.count'                  # markers
curl -s "$API/api/rooms/$ROOM/raster-layers" -H "$AUTH" | jq '.rasterLayers[] | {id,name,display}'

6. Kommentare readwrite

curl -s "$API/api/rooms/$ROOM/comments?resolved=false" -H "$AUTH" | jq '.comments[].body'
curl -X POST "$API/api/rooms/$ROOM/comments" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"objectId":"marker-1","objectType":"marker","body":"needs review","lat":47.56,"lng":7.59}'

7. Die Darstellung eines Rasters ändern write

curl -X PATCH "$API/api/rooms/$ROOM/raster-layers/<layerId>/display" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"colormap":"viridis","band":1,"vmin":0,"vmax":3000}'

8. Export / Import readwrite

curl -X POST "$API/api/rooms/$ROOM/export" -H "$AUTH" -H "Content-Type: application/json" -d '{}' -o room.gpkg
curl -X POST "$API/api/rooms/$ROOM/import" -H "$AUTH" -F "file=@room.gpkg"   # ≤ 2 GiB

Große Räume: mit GET /api/rooms/$ROOM/export-size sondieren, dann die asynchronen Export-Aufträge nutzen.

9. Der bequeme Weg: das Import-Skript

scripts/import_geo_data.mjs erkennt Formate automatisch, teilt große Dateien auf und fragt Aufträge für Sie ab:

COMAP_API_TOKEN=$TOKEN node scripts/import_geo_data.mjs --room $ROOM data/my-folder
COMAP_API_TOKEN=$TOKEN node scripts/import_geo_data.mjs --room $ROOM points.csv imagery.tiff
node scripts/import_geo_data.mjs --room $ROOM --dry-run data/my-folder     # preview only

10. Fehlersuche

Symptom	Ursache → Abhilfe
403 api_token_not_allowed an einem Datenendpunkt	Sie haben einen Eigentümer-/Admin-Endpunkt getroffen (siehe was ein Token nicht darf); in Produktion ist ein neues Deployment womöglich noch nicht live
403 „API token is not scoped to this room“	roomName/$ROOM ≠ Raum des Tokens
403 „API token lacks 'X' permission“	Token neu ausstellen, Berechtigung X einschließen
401 Invalid or expired API token	Token widerrufen/abgelaufen — ein neues ausstellen
413 quota_exceeded	Die Speichergrenze des Raumeigentümers ist erreicht — Platz schaffen oder Tarif anheben
413 file_too_large	Datei > 50 MB in einer Anfrage — Import-Skript / stückweisen Upload verwenden