Getting Started

This guide walks you through importing your first dataset and exploring it on the map.

Developers: If you need to install TimeTiles locally, see the Quick Start Guide.

Prepare Your Data

TimeTiles works with CSV, Excel, or ODS files. Each row becomes an event on the map. Your data needs three fields:

Field	Required	Example
Title	Yes	”Earthquake in San Francisco”
Date	Yes	2024-03-15 (ISO 8601 recommended)
Location	Yes	”San Francisco, CA” or `37.7793, -122.4193`

You can include any additional fields — description, category, source, severity, URLs. These become filterable in the interface.

Example CSV:


title,date,location,category,description
"City Council Meeting","2024-01-10","Berlin, Germany","Politics","Budget debate for 2024"
"Factory Fire","2024-02-14","Hamburg, Germany","Incident","Chemical plant fire, no injuries"
"Climate March","2024-03-15","Munich, Germany","Protest","5,000 participants"
"Data Leak Published","2024-04-02","Frankfurt, Germany","Investigation","Financial records from 2019-2023"
"River Pollution Report","2024-05-20","Cologne, Germany","Environment","Elevated lead levels detected"

Import Your Data

Go to the import page

Navigate to /ingest or click the import button in the interface.

Choose or create a catalog

Catalogs are project-level containers. Create one for your topic (e.g., “German Events 2024”) or select an existing one.

Upload your file

Drag and drop your CSV, Excel, or ODS file. You can also paste a URL to fetch data from a remote source.

Review the detected schema

TimeTiles analyzes your data and identifies field types — dates, locations, categories, numbers. Verify the mappings look correct and adjust if needed.

Start processing

Click Start. TimeTiles will:

Validate your data
Geocode text addresses to coordinates (or use coordinates directly if provided)
Create events and add them to the map

A progress bar shows the current stage and estimated time remaining.

Explore Your Chronicle

Once processing completes, your data is live on the map.

Map — Events appear as markers, clustered when zoomed out. Click a cluster to zoom in. Click an individual marker to see full event details.

Timeline — A histogram at the bottom shows event density over time. Drag the handles to filter to a specific date range. Watch how patterns shift as you narrow the window.

Filters — Sidebar filters are generated from your data. If you have a “category” field, you’ll see checkboxes for each value. Combine multiple filters to drill down.

Search — Find specific events by text. Search works across all fields.

URL state — As you pan the map, adjust the timeline, or toggle filters, the URL updates. Bookmark it to save your exact view.

Every view has a shareable URL. Filters, map position, and time range are all encoded in the link — recipients see exactly what you see.

You can also export all your data as a ZIP archive from your account settings.

Tips

Start small — Test with 100-500 events before importing large datasets
Use consistent dates — ISO 8601 (YYYY-MM-DD) works best
Add categories — Fields with a small number of distinct values become interactive filters
Include coordinates — If you already have latitude/longitude, TimeTiles skips geocoding (faster and more accurate)
Preview first — Review the schema detection before starting the full import

Next Steps

Data Import — Scheduled imports, scrapers, deduplication, schema evolution
Exploring Data — Map, timeline, filters, and sharing
Use Cases — Real-world examples