Open-source platform that turns spreadsheets into interactive maps. Import tabular data, geocode locations, and explore everything visually.

TimeTiles is an open-source platform for visualizing events across time and space. Upload a spreadsheet, and it becomes an interactive map with timeline controls, filters, and rich visualizations — making complex stories accessible to everyone.

Built for journalists documenting events across regions, researchers analyzing historical patterns, activists tracking environmental or social issues, and organizations presenting data-driven narratives.

---

Features

Import & Processing — CSV, Excel, ODS, and JSON API sources with automatic format detection. Multi-provider geocoding (Nominatim, Photon, Google etc.). Scheduled URL imports, manual imports with real-time progress, and optional web scrapers running in isolated containers. Detects faulty data before importing.

Visualization — Interactive maps with clustering, timeline scrubbing, dynamic filters by category/date/location, automatic histograms and timeline charts, customizable UI and light/dark themes. Works for 1M+ events with server-side processing.

Sharing — Shareable URLs with filter state preserved, multi-user collaboration, public or private access control, embeddable views, and full data export.

Quick Start

git clone https://github.com/jfilter/timetiles.git
cd timetiles
make init          # setup + database + seed + dev server

Open localhost:3000. Go to localhost:3000/ingest, drop a CSV with title, date, and location columns, and watch your data come alive on the map.

Documentation

Full docs at docs.timetiles.io.

Getting Started	Overview and first steps
Use Cases	Real-world examples
Development Guide	Setup and workflows
Architecture	Technical deep dive
REST API	API reference
Contributing	How to contribute

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router), React 19, TypeScript
CMS	Payload CMS 3 (integrated mode)
Database	PostgreSQL 17 + PostGIS 3.5
Maps	MapLibre GL JS
UI	Tailwind CSS, Radix UI, shadcn/ui
i18n	next-intl (English, German)
Testing	Vitest, Playwright

Development

Prerequisites

• Node.js 24+, pnpm 10.12+
• Docker & Docker Compose or local PostgreSQL 17+ with PostGIS
• Git, Git LFS, Make

If you use mise, this repo now pins the toolchain in .mise.toml:

mise install

# macOS
brew install git git-lfs node pnpm docker postgresql jq curl

Commands

make dev            # Start dev server (auto-starts database)
make check          # Lint + typecheck
make test           # Run tests
make test-e2e       # Run E2E tests
make format         # Format code
make migrate        # Run database migrations
make seed           # Seed database
make fresh          # Clean reset: database + migrate + seed
make status         # Check environment health
make help           # Show all commands

Database Mode

Docker is the default. For local Homebrew PostgreSQL, set in .env:

PG_MODE=local
DATABASE_URL=postgresql://timetiles_user:timetiles_password@localhost:5433/timetiles

Project Structure

apps/
  web/              Next.js app, Payload CMS, API routes, components
  timescrape/       TimeScrape runner (optional, Podman-isolated)
  docs/             Documentation site (Nextra)

packages/
  ui/               Shared UI components (shadcn/ui)
  assets/           Logos and static assets
  payload-schema-detection/   CSV/Excel schema detection
  eslint-config/    Shared ESLint config
  typescript-config/ Shared TypeScript config
  prettier-config/  Shared Prettier config

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

GNU Affero General Public License v3.0

Acknowledgments

   

Funded in 2025 and 2026 by the Prototype Fund from the German Federal Ministry for Research, Technology and Space (BMFTR). FKZ 16IS25S03.

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: hi@timetiles.io