Getting started

What Spatly is

Spatly is a spatial studio. One project holds datasets, layers, styles, live bindings and beats (saved map states). From that one project you publish up to four kinds of surface:

They share everything. A beat saved for chapter three of a story is the same object a slide flies to and a dashboard bookmarks. Switching surface does not copy data; it gives the same project a different reading order.

1. Create a workspace

Sign up at /signup with e-mail or Google. A workspace is created for you. The Free plan gives you 2 projects, 5 datasets, 50 MB of storage (10 MB per file), 1 live binding refreshing every 30 minutes, 3 AI story generations a month, 1 seat and the MCP server. See Plans & limits.

2. Start from data

The fastest path is the drop zone on the app home. Drag a file onto it, or press Browse, and Spatly ingests the file, creates a project, adds the first layer and opens a story in the Studio.

12345

1. 1Workspace rail: Projects, Data, Marks and Settings. It stays in place everywhere in the app.
2. 2New project: an empty project when you want to pick the basemap and add data yourself.
3. 3Start from data: drop a GeoJSON, CSV, KML, GPX or a zipped Shapefile here, up to your plan’s file size (10 MB on Free, 50 MB on Pro and Team). Spatly builds the project, the first layer and a story in one go.
4. 4Browse: the same thing through a file picker.
5. 5Project card: a static map frame of the cover beat, layer and dataset counts, and the last edit. Click it to open the project.

Accepted in this step: GeoJSON, CSV with lng/lat (or an address column), KML, GPX, zipped Shapefile, PMTiles. Bigger and live sources are covered in Data & live sources.

curl -X POST https://spatly.io/api/v1/upload \
  -H "Authorization: Bearer spk_…" \
  -F file=@airports.geojson

3. Look at what ingest found

Every field is sampled at ingest: type, role (id · label · category · measure · time · lng · lat), min/max, distinct count and nulls. That is what lets the style editor offer you the right classification without you counting anything.

Open Data in the rail to see it.

123456789

1. 1Upload: a file from your disk.
2. 2From URL: a GeoJSON, PMTiles, XYZ or TileJSON address that can refresh on a schedule.
3. 3REST API: an authenticated endpoint with headers, 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 names as you type.
7. 7Geometry: points, lines, polygons or mixed, detected at ingest.
8. 8Serve: geojson under about 5,000 features, tiles above it (served as MVT from PostGIS).
9. 9Status: LIVE when a connection refreshes it, FROZEN for an uploaded file.

4. Style the layer

Open the project in Studio and go to the Layers tab. Pick a render type, then either a flat colour or a classification over a field.

12345678

1. 1Add layer from dataset: every dataset attached to the project is offered here.
2. 2Layer stack: top of the stack draws first in the list, last on the map. Drag to reorder.
3. 3Eye and opacity: per layer, and overridable per beat.
4. 4Render: circle, fill, line, symbol, heatmap, fill-extrusion, raster or tiles.
5. 5Classify by field: turn a field into colour, size or opacity.
6. 6Method: categorical, quantize, equal interval, jenks or interpolate.
7. 7Ramp: the built-in ramps; the brand ramp is first.
8. 8Breaks: the class edges, editable by hand once the method has proposed them.

The full reference is in Layers & styling.

5. Save a beat

Move the map until it says what you mean, then press Save beat (or B). The beat records the camera, every layer's visibility, opacity and filter, the active annotations, the basemap, terrain and the time window.

Press Duplicate & nudge, move the camera, and you have chapter two. See Beats & camera.

6. Write the story

The Studio canvas is the real viewer, not a preview of it. Click text to edit it in place; press / for the block menu; @ mentions a layer, a feature or a KPI and stays live.

1234567891011

1. 1Panel rail: Scenes, Layers, Data, Library, Design and (on dashboards and insights) Actions.
2. 2Scenes: the chapters in order. Click one and the map flies to its beat; drag to reorder.
3. 3Surface switch: the same project as Story, Slides, Dashboard or Insight. The menu also creates and converts.
4. 4Canvas tools: select, pan, and the pin · callout · line · area drawing tools.
5. 5Save beat: writes the current map state onto the active scene.
6. 6Preview width: fit, wall, desktop, tablet, phone. Phone renders the real mobile layout.
7. 7Theme variant: light, dark, night, ops. This is not a preview toggle: it is saved on the surface and is what gets published.
8. 8Canvas: the published runtime, live and editable.
9. 9Beat inspector: camera, transition, per-beat layer states, highlights, annotations, time.
10. 10Status bar: cursor coordinates, zoom, pitch and bearing in mono.
11. 11Publish: snapshot and go live.

7. Publish

Share opens the publish settings; Publish writes a snapshot immediately. Pick who can see it, copy the link or the embed snippet.

12345678

1. 1Who can see it: draft, unlisted, public, password or domain-restricted.
2. 2Embedding: allow other sites to frame this surface.
3. 3Made with Spatly: the small plate bottom-left; removable on paid plans.
4. 4SEO title and description: used for the link preview and the OG image.
5. 5Custom slug: the pretty URL under your workspace.
6. 6Share link: the short /s/<publicId> link and the pretty link.
7. 7Embed code: the script loader and a plain iframe, both ready to paste.
8. 8Publish changes: snapshots the current state. Nothing you edit reaches readers until you press it.

<div data-spatly="<publicId>"></div>
<script async src="https://spatly.io/embed.js"></script>

8. Or let an agent do it

Every plan includes the MCP server. Point Claude Desktop, Cursor or Claude Code at your workspace and ask for a six-chapter story from the dataset you just uploaded.

{ "mcpServers": { "spatly": { "command": "npx", "args": ["-y", "@spatly/mcp"], "env": { "SPATLY_TOKEN": "spk_…" } } } }

See MCP server.

Where to next

• Stories: chapters, narrative blocks, scroll tween, layouts, mobile
• Beats & camera: the one object every surface reuses
• Layers & styling: render types, classification, labels, popups, legends
• Dashboards: widgets, bindings, the actions graph, spatial and attribute filters
• Publishing: states, passwords, domains, OG previews, analytics
• Studio reference: every panel, the keyboard map, ⌘K and the AI features