TM TalkingMaps Docs
Home GitHub

TalkingMaps Documentation

The open-source platform for interactive storymaps, participatory maps, data visualization and geospatial presentations.

Overview

TalkingMaps lets you create scroll-driven story maps that combine interactive 2D and 3D maps, text narratives, multimedia, charts and data layers. It's designed for journalists, researchers, educators, planners and anyone who needs to tell a story on a map.

Key features:

Quick Start

  1. Open TalkingMaps in your browser (e.g. http://localhost:8080)
  2. Log in with your username and password
  3. Click + New Story in the top bar
  4. Enter a title — the Editor opens with a cover slide ready to go
  5. Add slides, configure map views, write your narrative
  6. Click Preview to see the result, then Publish to share
Tip: You can explore public stories without logging in by clicking "Explore public stories" on the login page.

Dashboard

After logging in you'll see the Dashboard with:

Each story card has a three-dot menu (…) with actions: Edit, Preview, Publish/Unpublish, Duplicate, Export, Share, Delete.

Creating a Story

  1. Click + New Story in the navigation bar
  2. Enter the story title
  3. The Editor opens automatically with a first slide (cover layout)

Story Settings

In the Editor, click the gear icon () to access story-level settings:

The Editor

The editor has three panels:

Left — Slides Center — Map Right — Properties
List of slides. Drag & drop to reorder. Click + to add a new slide. Interactive map preview. Use the toolbar to add markers, manage layers, toggle 3D. Properties for the selected slide: layout, text, map view, styling, data, media.

Adding Slides

  1. Click the + button at the bottom of the slides panel
  2. Choose a slide type from the menu: Map, 3D Globe, Point Cloud, Navigable Image, Text Only, Text + Media, Full Media, Separator
  3. The new slide is added at the end — drag to reorder

Slide Properties Tabs

The right panel has several tabs:

Slide Layouts

Each slide can have a different layout. Choose the layout in the Content tab of the slide properties.

LayoutDescriptionMap visible?
CoverCentered title and text, ideal for the opening slide. Optional background image/video.No
Side LeftText panel on the left, map on the right. The default for map-driven narratives.Yes
Side RightText panel on the right, map on the left.Yes
CenterText overlaid at the center of the map.Yes
Full MapMap fills the entire screen. No text panel.Yes
Navigable Image New Display a high-resolution image (painting, floor plan, historical map) that users can zoom and pan. Configure the image URL in the Map tab. Yes (image)
3D Globe CesiumJS 3D globe with terrain, buildings, and 3D Tiles. Configure tileset in Media & 3D tab. Yes (3D)
Point Cloud Potree-based LiDAR / point cloud visualization. Configure the point cloud URL in Media & 3D tab. Yes (3D)
Full MediaFull-screen image or video with optional text overlay at the bottom.No
Text OnlyText-only slide for narratives, quotes, deep-dives. No map.No
Text + MediaSplit view: text on one side, image/video on the other.No
SeparatorLarge title to divide sections of your story.No

Writing Narrative

The narrative text editor supports:

Quick Actions

At the top of the narrative area you'll find quick action buttons to insert images, videos, charts or iframes with a single click.

Map Configuration

Capturing the Map View

For each slide you can set a specific map position (center, zoom, bearing, pitch):

  1. Navigate the map in the editor to the desired view
  2. Click Capture current view in the Map tab
  3. The position is saved for that slide

Animation Types

When the viewer transitions to a slide, the map animates to its saved position. Choose the animation:

AnimationDescription
Fly ToSmooth aerial arc (default). Best for long-distance transitions.
Ease ToLinear smooth pan. Best for short-distance transitions.
Jump ToInstant, no animation. Best for same-area layout changes.

Per-Slide Basemap

Each slide can use a different basemap. Select it in the Map tab dropdown. This is useful for comparing satellite vs. street views across slides.

Map Comparison (Swipe)

Enable a swipe comparison between two basemaps on a single slide. In the Style tab, toggle "Compare" and select a second basemap.

Layers & Data Sources

TalkingMaps supports multiple data source types that can be added as map layers:

TypeDescription
GeoJSONUpload a .geojson file from your computer. Points, lines and polygons are supported.
WMSWeb Map Service. Enter the URL and layer name. The built-in proxy handles CORS.
WMTS / XYZTiled services. Enter the tile URL template with {z}/{x}/{y} placeholders.
Vector TilesMapbox Vector Tiles (MVT) from a tile server.
Cloud Optimized GeoTIFFCOG rasters served directly from a URL, streamed on-the-fly.

Adding a Layer

  1. In the editor, click the layers icon () on the map toolbar
  2. Choose Upload GeoJSON or Add WMS/URL
  3. The layer appears in the layer panel and on the map

Per-Slide Layer Visibility

In the Layers tab of each slide's properties, toggle which layers are visible for that specific slide. This lets you progressively reveal data as the story unfolds.

Layer Catalog

Access the global layer catalog from the user menu → Layers. Layers are shared across all your stories.

Markers

  1. Click the marker icon () on the map toolbar
  2. Click on the map where you want the marker
  3. Enter a title and optional description

Markers are per-slide: each slide shows only its own markers. In the viewer, markers appear with a popup on click.

Charts & Dashboards

Adding a Chart

In the Data tab, use the Chart Wizard or paste a JSON configuration:

{
    "type": "bar",
    "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
    "data": [120, 190, 300, 250, 420],
    "options": { "label": "Monthly visitors" }
}

Supported chart types: bar, line, pie, doughnut, scatter, radar, polarArea. Horizontal bars: set "horizontal": true in options.

KPI Dashboard Widgets

Add dashboard-style KPI cards to any slide. In the style overrides:

{
    "dashboard": [
        {"label": "Population", "value": "59.5M", "icon": "people", "color": "#1a73e8"},
        {"label": "Area", "value": "301,340 km²", "icon": "geo-alt", "color": "#34a853"},
        {"label": "Municipalities", "value": "7,904", "icon": "building", "color": "#fbbc04"}
    ]
}

Timelines

Embed interactive timelines powered by TimelineJS. In the Data tab, paste the timeline JSON data. Timelines are great for historical storymaps.

Symbology & Styling

Customize how your layers look on the map:

Access the symbology editor from the layer panel. You can also use presets (Red-Yellow-Green, Blue-White-Red, Viridis, etc.) for quick setup.

3D Globe (Cesium)

Create slides with a 3D globe layout to show your data on a realistic 3D terrain with CesiumJS.

How to Use

  1. Add a new slide and choose 3D Globe as the slide type
  2. The editor switches to the Cesium 3D view automatically
  3. Navigate to the desired view and capture the camera position
  4. Optionally add a 3D Tileset (buildings, terrain mesh) in the Media & 3D tab

3D Tilesets

You can load 3D Tilesets from:

Tip: In the viewer, users can toggle between 2D and 3D views using the 3D button in the toolbar.

Point Clouds (Potree)

Visualize LiDAR and point cloud data using Potree.

  1. Add a new slide and choose Point Cloud as the slide type
  2. In the Media & 3D tab, enter the URL to your Potree-compatible point cloud (cloud.js or metadata.json)
  3. The point cloud renders in the viewer with full 3D navigation
Note: Point cloud data must be pre-processed into Potree format (use tools like PotreeConverter). The editor shows a placeholder; the full 3D rendering is in the story viewer.

Navigable Images New

Display a high-resolution image (painting, floor plan, historical map, aerial photo) as a zoomable, pannable layer — just like a map.

How to Use

  1. Add a new slide and choose Navigable Image as the slide type
  2. In the Map tab, you'll see the Navigable Image configuration section
  3. Paste the URL of a high-resolution image
  4. Click Apply — the image replaces the map and becomes navigable

Users can zoom in/out and pan the image in the viewer, just like they would with a map. This is perfect for art analysis, architectural plans, or detailed diagrams.

Participatory Maps New

Enable participatory mode to let registered users add geolocated contributions (points with text, photos, videos, or audio) to your story map.

Enabling Participatory Mode

  1. Open the story in the Editor
  2. In the right panel, find the Participatory Maps section (visible for all slides)
  3. Toggle Enable participatory mode to ON
  4. Optionally define categories (comma-separated) for contributions

How Contributions Work

WhoAction
Registered usersClick the Contribute button in the viewer, then click on the map to place a point. Fill in title, description, category, and optionally attach a photo, video or audio file.
Story owner / AdminReview contributions in the Moderation panel (Dashboard → story menu → Moderate). Approve or reject each contribution with an optional note.
EveryoneSee approved contributions as markers on the map with popups showing the content and media.

Upload Limits

The maximum file size for contribution attachments is configurable by the administrator (default: 10 MB). See System Settings.

Moderation Workflow

  1. A user submits a contribution → status: Pending
  2. The story owner or an admin reviews it in the Moderation panel
  3. They can Approve (visible to everyone) or Reject (hidden, with optional note)

AI Assistant

TalkingMaps integrates AI capabilities to help you create content faster:

Supported Providers

Configure your API keys in the user menu → Account → AI Settings. Keys are encrypted and stored per-user.

Collaboration

Invite other users to collaborate on your stories:

  1. Open a story in the Editor
  2. Click the collaborators icon ()
  3. Search for users and add them with a role: editor (can edit) or viewer (read-only)

Collaborators see the story in their dashboard and can access it based on their assigned role.

Publishing & Sharing

Publishing a Story

  1. In the Dashboard, click the … menu on your story card
  2. Click Publish
  3. Published stories are visible on the public stories page (accessible without login)

Sharing

Export & Import

Embedding

Embed a story in any website using an iframe:

<iframe src="https://your-server.com?story=STORY_ID"
        width="100%" height="600" frameborder="0"
        allow="fullscreen"></iframe>

The embedded viewer hides the toolbar and close button for a clean reading experience.

Viewer Controls

When viewing a story, the following controls are available:

ControlAction
Scroll wheelNavigate between slides
Arrow Up / DownPrevious / next slide
Arrow Left / RightPrevious / next slide
SpaceNext slide
EscapeClose the viewer
FToggle fullscreen
Map iconSwitch basemap
3D iconToggle 2D / 3D view
Search iconGeocode a place name and fly to it
Share iconCopy link to share

Media Library

Access the media library from the user menu → Media Library.

3D Assets

Upload and manage 3D model files (glTF, GLB) for use in your stories:

  1. User menu → Media Library → 3D Assets tab
  2. Upload a .glb or .gltf file
  3. Each user has a storage quota (default 100 MB, configurable by admin)

User Management

Admin only. User menu → Users.

RolePermissions
AdminFull access: manage users, basemaps, system settings, all stories
EditorCreate/edit own stories, upload layers & media, collaborate on shared stories
ViewerView public and shared stories only

Actions: Create user, Disable/enable (toggle), Reset password.

Self-Registration

Users can self-register from the login page. New users are created with the editor role by default.

Basemaps

Admin only. User menu → Basemaps.

Basemaps are the background maps available in all stories. Default basemaps:

To add a custom basemap: enter name, type (xyz, wms, wmts), URL, and optional config JSON (attribution, maxzoom, layers for WMS).

System Settings

Admin only. User menu → Settings.

SettingDescriptionDefault
cesium_ion_tokenCesium Ion access token for 3D tilesets(empty)
default_storage_limit_mbDefault storage quota per user1024 MB
max_upload_size_mbMax single file upload size50 MB
participatory_upload_limit_mbMax upload size for participatory contributions10 MB
analytics_enabledEnable story view trackingtrue

Installation & Deploy

Requirements

Quick Install

# Clone the repo
git clone https://github.com/fgianoli/talkingmaps.git
cd talkingmaps

# Copy and edit the environment file
cp .env.example .env
# Edit .env: set SECRET_KEY, POSTGRES_PASSWORD, ADMIN_PASSWORD, ALLOWED_ORIGINS

# Start everything
docker compose up -d --build

# Open http://localhost:8080

Updating

# Pull latest code
git pull

# Rebuild and restart
docker compose up -d --build

Production Deploy

For production, add a reverse proxy with HTTPS in front (Nginx Proxy Manager, Traefik, or Caddy):

# Example with Caddy (automatic HTTPS):
caddy reverse-proxy --from maps.yoursite.com --to localhost:8080

Backup & Restore

# Backup database
docker compose exec db pg_dump -U talkingmaps -d talkingmaps > backup_$(date +%Y-%m-%d).sql

# Backup media uploads
docker cp $(docker compose ps -q backend):/var/www/uploads ./uploads_backup

# Restore database
docker compose exec -T db psql -U talkingmaps -d talkingmaps < backup.sql

WMS Proxy Whitelist

The WMS proxy handles CORS for external services. To add a new host, edit backend/routers/wms_proxy.py and add it to the ALLOWED_HOSTS list, then restart the backend:

docker compose restart backend

Swagger API Docs

The full REST API documentation is available at /api/docs (auto-generated by FastAPI).

TalkingMaps is open source software. Made with passion by Federico Gianoli and Martino Boni (Tenoli).
GitHub  ·  Report bug  ·  Request feature