Data Export & Import

Export operational data and import markers.

GroundWave provides comprehensive export capabilities for all operational data collected during a mission, as well as import support for bringing markers from external sources or from a previous export. All export and import endpoints are admin-only and require a valid JWT with the admin role.

Export Formats

Each data type is exported in the most appropriate standard format for its content and for compatibility with common GIS tools and after-action analysis workflows.

Export Endpoints

All export endpoints are under the /api/admin/export prefix and require admin authentication.

ZIP Archive Export

The archive endpoint bundles multiple data types into a single downloadable ZIP file, making it straightforward to capture a complete operational picture in one request. Each included data type is written as a separate file inside the archive:

• positions.geojson — all position records as GeoJSON
• chat.json — all chat messages as JSON
• markers.geojson — all markers as GeoJSON

Include only the data types you need by specifying them in the include query parameter:

# Full export bundle
GET /api/admin/export/archive?include=positions,chat,markers

# Spatial data only
GET /api/admin/export/archive?include=markers

The response is a application/zip download. The filename is set to groundwave-export-{timestamp}.zip via the Content-Disposition header.

Importing Data

GroundWave supports importing markers from GeoJSON files. This enables faithfully round-tripping data between GroundWave deployments and loading externally prepared GeoJSON from planning tools.

The import endpoint is admin-only, accepts a JSON body with a GeoJSON FeatureCollection, and returns a result summary indicating how many features were imported successfully and how many failed validation.

Marker Import

The importer maps the GeoJSON feature properties back to the internal marker schema faithfully. The marker_type property determines how the geometry is stored and rendered. Style attributes such as color and label text are preserved in the marker's properties.

Example point marker from an export that can be re-imported:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  },
  "properties": {
    "marker_type": "point",
    "name": "Forward Aid Station",
    "category": "medical",
    "description": "Level 2 medical care, 2 medics on site",
    "color": "#EF4444"
  }
}

Real-Time Broadcasts

When markers are imported, the server broadcasts each new record to all connected clients via Socket.IO immediately after database insertion — the same events that fire when a user creates a record interactively:

• Imported markers emit marker:created for each feature, causing all connected clients to render the marker on the map without requiring a page refresh.

This means a large batch import becomes immediately visible to the entire team in real time, rather than requiring each client to reload data.

Round-Trip Fidelity

GroundWave's export and import system is designed for faithful round-trip accuracy: exporting data and re-importing it produces records that are functionally identical to the originals. All fields relevant to rendering and identification are preserved through the GeoJSON intermediary:

• Marker geometry type (point, line, polygon) and coordinates
• Marker style properties (color, label, stroke width, fill opacity)
• Marker name, category, and description

Fields that are intentionally not preserved in a round-trip include the original database row ID (a new ID is assigned on import), the creating user's callsign (set to the importing admin's callsign), and the original creation timestamp (set to the import time). These fields are metadata, not operational content.

Partial Success and Validation

Both import endpoints process features individually and support partial success. If some features in a FeatureCollection pass validation and others fail, the valid features are imported and the invalid ones are reported. The HTTP response always returns 200 OK with a result summary — the caller should inspect the response body to detect validation failures.

The import response body structure:

{
  "imported": 12,
  "failed": 2,
  "errors": [
    { "index": 4, "reason": "Missing required property: annotation_type" },
    { "index": 9, "reason": "Invalid category: 'unknown'" }
  ]
}

Common validation failure reasons include missing required properties, unrecognized category values, invalid geometry types (e.g., a LineString for a point marker), and out-of-range coordinate values.