Data Import

Three ways to get data into TimeTiles. All three go through the same pipeline: schema detection, deduplication, geocoding, and event creation.

Upload CSV, Excel, or ODS files manually.

File Upload

Fetch data from a URL on a recurring schedule.

Scheduled Imports

Pre-configured datasets with FtM-compatible metadata.

Data Packages

Run custom Python or Node.js scripts to extract data.

Scrapers

The Pipeline

Every import — regardless of source — follows the same stages:


Source (file, URL, or scraper output)
  → Detect sheets and datasets
    → Analyze for duplicates
      → Detect schema (field types, dates, locations)
        → You review and approve the schema
          → Geocode addresses to coordinates
            → Create events

Supported Formats

Format	Extensions	Notes
CSV	`.csv`	Comma, semicolon, or tab delimited — auto-detected
Excel	`.xlsx`, `.xls`	Multi-sheet files create one dataset per sheet
OpenDocument	`.ods`	Spreadsheet format
JSON API	URL	Available via Scheduled Imports only (not direct upload). Fetched from a remote endpoint and converted to tabular data.

Schema Detection

TimeTiles analyzes your data and identifies:

Field types — strings, numbers, dates, booleans
Date fields — timestamps, start dates, and end dates when present
Location fields — addresses, coordinate pairs, or separate lat/lng columns
Enum fields — columns with few unique values (become interactive filters)

You review and adjust the mappings before processing begins. If your file uses a single combined coordinate column, confirm whether the values are lat,lng or lng,lat before starting.

Geocoding

Text addresses are converted to coordinates using multiple providers with automatic fallback:

Provider	Notes
Nominatim	Free, based on OpenStreetMap
Google Maps	Paid, highest accuracy
OpenCage	Paid, good international coverage

Results are cached. If your data already has latitude/longitude columns, geocoding is skipped.

Deduplication

When importing into a dataset that already has events, TimeTiles compares incoming rows:

External ID — use a unique identifier field from your data
Computed hash — hash a combination of fields (title + date + location)
Content hash — hash the entire row

Schema Evolution

As your data changes over time, TimeTiles tracks schema versions:

New optional fields — auto-approved, existing events unaffected
Type changes or removed fields — require your approval

Troubleshooting

Issue	Solution
Import stuck	Check that background workers are running
Schema approval needed	Review detected mappings, including combined coordinate order, before continuing
Geocoding failures	Verify API keys and address formatting
Duplicate events	Configure a deduplication strategy on the dataset
Large file timeout	Split into smaller files or increase batch size