Skip to Content
⚠️Active Development Notice: TimeTiles is under active development. Information may be placeholder content or not up-to-date.
Frequently Asked Questions

FAQ

General

What is TimeTiles?

An open-source platform that turns spreadsheets of events into interactive maps with timeline controls. Upload a CSV with dates and locations, and it becomes an explorable interface — pan the map, scrub the timeline, filter by category.

How is it different from other tools?

TimeTiles is purpose-built for storytelling with geo-temporal data. It sits between simple tools (TimelineJS, StoryMapJS) that handle ~200 events and complex GIS software (QGIS, ArcGIS) that requires expertise. See the full comparison.

Do I need technical skills?

To use it: No. Import data, configure settings, and share — all through the web interface.

To self-host: Basic Docker and Linux skills. See the Self-Hosting guide.

Is it free?

Yes. TimeTiles is open source (AGPL-3.0). Self-host on your own servers at no cost.

Data

What formats can I import?

CSV, Excel (.xlsx/.xls), ODS, and JSON API endpoints via URL. Files can be uploaded manually or fetched on a schedule.

My data only has addresses, not coordinates. Will it work?

Yes. TimeTiles geocodes text addresses automatically using three free providers out of the box — Photon (VersaTiles), Photon (Komoot), and Nominatim — with weighted distribution and automatic fallback. Paid providers (Google Maps, OpenCage, LocationIQ) can be added for higher accuracy.

How much data can it handle?

Tested with 100,000+ events. Server-side clustering via PostGIS keeps the map responsive regardless of dataset size. The bottleneck is import time for very large files, not runtime performance.

What fields do I need?

Three required fields: title (what happened), date (when), and location (where — address or coordinates). An optional end date lets TimeTiles represent date ranges. Any additional fields become filterable in the interface.

Technical

What are the system requirements?

Minimum: 2 CPU cores, 4 GB RAM, 20 GB SSD, Docker. Recommended: 4+ cores, 8+ GB RAM, 50+ GB SSD. See Prerequisites.

Can I integrate with other systems?

Yes. Versioned REST API (/api/v1/) for querying events, clusters, and statistics. Payload CMS REST API for CRUD on all collections. Webhook triggers for automation. Scheduled URL imports for external data feeds.

Is my data secure?

Your data stays on your servers when self-hosting. Access control supports public and private catalogs. HTTPS with Let’s Encrypt. Rate limiting and trust levels for API protection.

What languages are supported?

The UI is available in English and German. The import system detects field mappings in 7 languages (English, German, French, Spanish, Italian, Dutch, Portuguese).

Can I customize the appearance?

Yes — themes, branding, logos, custom CSS, and layout templates. All configurable from the admin dashboard without code changes. See UI Customization.

Sharing

How do I share a dataset?

Every view has a unique URL with filters, map position, and time range encoded. Share the link — recipients see exactly what you see.

Can multiple people collaborate?

Yes. Role-based access (User, Editor, Admin), multi-dataset catalogs, and a full audit log for accountability.

Can I export my data?

Yes. Download all your data as a ZIP archive from Account Settings. Includes catalogs, datasets, events, and import history.

Troubleshooting

The map isn’t loading

Check that your location data contains valid coordinates (decimal degrees) or geocodable addresses. Verify geocoding completed successfully in the import progress view.

Import is slow

Geocoding is the slowest stage — it makes external API calls for each unique address. The default configuration distributes requests across multiple Photon providers at ~40 req/s combined. If your data already has coordinates, geocoding is skipped and imports are much faster.

My scheduled import stopped running

Check whether the schedule was automatically disabled after an invalid cron/frequency setting or repeated failures. TimeTiles records the last error and emails the schedule owner when this happens. Fix the configuration, then re-enable the schedule.

I’m getting permission errors

Check your user role in the admin dashboard. Verify the feature flags are enabled (Settings > Feature Flags). For API access, ensure you’re authenticated with a valid session.

Support

Last updated on
Glossary