Data & live sources

The library

Data in the workspace rail holds every dataset and every live connection. Datasets are shared by all projects in the workspace; a project references the ones it uses.

12345678910

1. 1Upload: a file from your disk, up to 50 MB.
2. 2From URL: a GeoJSON, PMTiles, XYZ or TileJSON address, optionally refreshing.
3. 3REST API: an authenticated endpoint: method, headers, query parameters, a records path and a field map.
4. 4MCP source: a tool on your own MCP server becomes a dataset.
5. 5Connections: the live sources behind these datasets, with health and refresh history.
6. 6Filter: matches dataset names as you type.
7. 7Geometry: points, lines, polygons or mixed, detected at ingest.
8. 8Fields: how many attributes survived ingest, each with a type, a role and statistics.
9. 9Serve: geojson below roughly 5,000 features, tiles above it.
10. 10Status: LIVE when a connection refreshes it, FROZEN for an uploaded file.

Formats

3D coordinates are flattened to 2D on ingest, so a Z value in a GeoJSON point or a GPX track will not stop the load.

Ingest and field inference

GeoJSON, CSV, KML, GPX and Shapefile are parsed in process; everything else goes through GDAL. Geometries land in PostGIS as WGS84 ([lng, lat]).

Every field is then sampled for:

• type: string, number, integer, boolean, datetime
• role: id, label, category, measure, time, lng, lat
• statistics: min, max, distinct count, null count

That inference is what the rest of the product reads: the classification methods propose breaks from min/max and distinct counts, field pickers only offer numeric fields where a number is required, and label fields become the default popup title.

You can correct any of it in the dataset drawer. A code stored as a number is the usual case.

Time fields

A dataset with a datetime field can carry a time field. Setting it turns on:

• time-enabled layers (layer.timeField) that clip to the beat's time window
• dateRangeWidget presets and the mini timeline brush
• timeControl playback
• query_timeseries and the timeseries option on metrics

Set it at upload time (options.timeField) or later in the dataset drawer.

Serving: GeoJSON or tiles

The choice is automatic and shows in the Serve column. It matters in one place: on a tiled dataset the client only holds what is in the viewport, so client-side feature counts describe the viewport. Metrics are computed server-side and stay correct either way.

Address geocoding

A CSV with an address column and no coordinates is geocoded at ingest: up to 500 rows, one request per second, against a cached Nominatim proxy. Rows that fail are flagged, not dropped: fix the address in the dataset drawer and re-geocode.

Geocoding is also available directly:

curl -H "Authorization: Bearer $TOKEN" "$BASE/geocode?q=Antakya&limit=1"
curl -H "Authorization: Bearer $TOKEN" "$BASE/reverse?lng=36.16&lat=36.20"

Results are cached for seven days. Attribution (© OpenStreetMap contributors) is required wherever they are shown.

Live connections

1234

1. 1Connections tab: everything that refreshes, separate from the datasets it feeds.
2. 2Kind and target: url, rest, xyz, pmtiles, feature service, wms, webhook or mcp.
3. 3Refresh: interval or cron, and when it last succeeded.
4. 4Health: consecutive failures and the last error, verbatim.

Secrets (bearer tokens, header values) are encrypted at rest with CONNECTION_SECRET_KEY and never reach a viewer.

Refresh policies

{ "mode": "interval", "intervalSec": 60 }
{ "mode": "schedule", "cron": "*/15 * * * *" }
{ "mode": "webhook" }
{ "mode": "static" }

The minimum interval is 15 s. Sources are fetched server-side and cached, so a thousand viewers cost the upstream one request per interval, not a thousand.

The scheduler runs a tick every 30 s (SPATLY_SCHEDULER=off disables it), takes a lock so only one instance refreshes, runs at most five refreshes in parallel, and evaluates alerts after each one. For a serverless deployment, drive it from an external cron instead:

curl "https://spatly.io/api/internal/cron?key=$CRON_KEY"

Health and stale state

Every connection carries lastSuccessAt, lastErrorAt, lastError, latencyMs and consecutiveFailures. After three consecutive failures the dependent widgets go stale: hatched, with last success N minutes ago. Nothing is silently wrong.

Webhooks

Create a connection of kind webhook and push into its URL. mode=replace (the default) makes the payload the current state; mode=append adds to it.

curl -X POST "https://spatly.io/api/webhooks/data/$CONNECTION_ID?secret=$WEBHOOK_SECRET&mode=replace" \
  -H "Content-Type: application/json" \
  --data @vehicles.geojson
# → { "received": 128, "featureCount": 128, "mode": "replace" }

The secret can travel as ?secret=, as X-Spatly-Secret, or as a bearer token. Both GeoJSON and a bare array of records are accepted; records need lngField/latField set on the connection.

Live source catalog

One-click public feeds, each with a refresh interval, a suggested style and ready-made metrics:

Each becomes an ordinary connection you can edit afterwards. OpenSky is rate-limited upstream, so 15 minutes is the floor.

MCP sources

Data → MCP source: paste the server URL (streamable HTTP), add a bearer token if it needs one, press Discover tools (tools/list), pick a tool and its JSON arguments, map the result (recordsPath, lngField/latField, idField), test, save.

Spatly then calls that tool on the refresh interval and turns the result (structuredContent, or the first JSON text block) into a dataset like any other. Layers, metrics and alerts work unchanged. See MCP server for the other direction, where agents read your workspace.

Query policy and the agent budget

Each connection has a query policy:

On top of that, the workspace agent budget (Settings → General) bounds every token: maxCallsPerMin (60), maxRowsPerCall (500), requireBbox. The tighter of the two wins. Lists page with nextCursor; nothing is ever dumped wholesale.

Limits