daedal-map

DaedalMap

Use it as a hosted MCP server (no setup)

Most callers do not need to run anything - DaedalMap is a live remote MCP server (and HTTP API) for geographic data:

• MCP endpoint: https://app.daedalmap.com/mcp (streamable HTTP)
• Start with get_catalog, then get_pack for a pack's metrics and a

first-query example

• Free packs: currency (FX rates), volcanoes, hurricanes, floods, tornadoes,

UN SDG, World Factbook, WorldPop

• Paid via x402 on Base mainnet USDC: earthquakes, tsunamis (call unpaid first -

the server returns the exact price before any charge)

• Agent docs: https://daedalmap.com/docs/for-agents

The rest of this README is the self-host / local-runtime path.

---

DaedalMap is a map-first geographic query engine. This repository is the open app/runtime for developers who want to run it locally, self-host it, point it at their own data, or extend it with compatible geographic datasets.

Public surfaces:

• App: https://app.daedalmap.com
• Website/docs: https://daedalmap.com

There are now two valid ways to approach DaedalMap locally:

• GitHub/self-host path
• use this repo directly
• best for developers, custom data work, and users who want to control setup
• Downloadable launcher path
• curated wrapper + engine artifact + pack install flow
• best for users who want the same runtime with less setup friction

These should stay the same product at the runtime/contract level, but they do not need identical UI on every surface.

If you are using this public GitHub repo as a self-host/local runtime, the practical setup contract right now is:

• a local data location (DATA_ROOT, unless you use the default app-data path)
• optionally, an LLM API key for the built-in local chat UI

Hosted account wiring and private verifier endpoints are optional for self-host use. Hosted collector scheduling and scheduled-jobs hosts such as the private DigitalOcean nightly box are not part of this public repo.

What This Repo Is For

Use this repo if you want to:

• run the DaedalMap runtime on your own machine or server
• point the runtime at local data or a cloud-backed data plane you control
• inspect or extend the open runtime behavior
• build compatible geographic datasets and pack-style workflows around the engine

Typical use cases:

• show earthquakes, floods, wildfires, storms, volcanoes, or tsunamis for a place and time window
• compare population, economic, and disaster context in the same workflow
• move between local development, self-hosted runtime operation, and hosted-style runtime behavior without changing the basic mental model

DaedalMap itself is built around three ideas:

• ask in plain language instead of assembling GIS workflows first
• keep the map as the primary interface, not an afterthought
• separate runtime delivery from maintained data-pack delivery

This repo is therefore best read as:

• the open runtime engine
• the self-host/developer entry point
• the source of truth for the downloadable engine snapshot users install through

the launcher

It is not the hosted account, billing, or admin surface. Those product surfaces are separate from the public runtime and may evolve faster than the downloadable runtime UI.

Choosing A Local Path

If you are deciding between this repo and the downloadable launcher, use this rule of thumb:

• use the GitHub repo when you want:
• code access
• self-host setup
• custom data or custom pack work
• runtime-level experimentation
• use the downloadable launcher when you want:
• a curated install/update path
• a local Research-oriented runtime with less setup work
• pack installs and local runtime management without treating Git as the main UX

The goal is that both paths converge on the same core runtime behavior even if their setup UX differs.

GitHub Vs Downloadable

If you are browsing this repository, treat it as the developer and self-host entry point.

If you want a more guided local install path, use the downloadable launcher when it is available through release/distribution channels.

In other words:

• GitHub checkout = source, self-host, customization, local development
• downloadable launcher = curated local install and runtime management

Both paths are intended to lead to the same DaedalMap runtime family.

Data Coverage

The hosted runtime ships with 40+ curated sources across disasters, demographics, economics, and climate. Coverage below reflects the current maintained pack inventory.

Global Disasters

| Source | Scale | Time Range | |--------|-------|------------| | USGS Earthquakes | 1M+ events | 2150 BC - present | | IBTrACS Hurricanes/Cyclones | 13K storms | 1842 - present | | NOAA Tsunamis | 2.6K events | 2000 BC - present | | Smithsonian Volcanoes | 11K eruptions | Holocene | | Global Wildfires | 940K events/year | 2002 - 2024 | | USA/CAN Tornadoes | 81K events | 1950 - present | | Global Floods | 4.8K events | 1985 - 2019 | | Global Landslides | 45K events | 1760 - present |

Disaster events include 22M+ geographic location relationships and 566K cross-disaster links (aftershocks, triggered events).

Global Indicators

| Source | Countries | Years | Category | |--------|-----------|-------|----------| | Our World in Data CO2 | 217 | 1750 - 2024 | Environment | | WHO Health Statistics | 198 | 2015 - 2024 | Health | | IMF Balance of Payments | 195 | 2005 - 2022 | Economy | | UN Sustainable Development Goals | 200+ | 2000 - 2023 | SDGs 1-17 | | Eurostat Demographics | 37 European countries | 2000 - 2024 | Demographics |

Country-Specific Sources

| Country | Source Count | Examples | |---------|-------------|---------| | USA | 15+ | Census, FEMA National Risk Index, NOAA storms | | Canada | 3 | Statistics Canada, NRCan earthquakes, drought | | Australia | 2 | ABS population, BOM cyclones |

Disaster Display

Disasters are displayed with animated, type-specific rendering:

• Point + radius: earthquakes, volcanoes, tornadoes
• Track/trail: hurricanes and cyclones
• Radial wave: tsunamis
• Polygon fill: wildfires, floods

Current Runtime Shape

DaedalMap now treats runtime behavior as a 2-axis matrix:

• INSTALL_MODE
• local = local app/runtime install
• cloud = hosted/server deployment
• RUNTIME_MODE
• local = query local data
• cloud = query managed cloud-backed data via local cache + DuckDB httpfs

Supported combinations:

• local install + local data
• local install + cloud data
• cloud install + cloud data

Not supported as a first-class runtime shape:

• cloud install + local data

The current hosted/runtime direction is:

• a hosted app runtime
• object storage for runtime data
• optional auth and account services

In RUNTIME_MODE=cloud, the runtime:

• eagerly syncs only small metadata files to local cache
• queries parquet directly from object storage via DuckDB httpfs
• does not sync the full parquet tree at startup

Hosted deployment topology, release lanes, and operator control-plane details belong in private deployment notes.

That means the same codebase can be used in:

• full local-data mode
• hosted-style cloud-data mode

Guest And Logged-In Behavior

Guest users can open the app and try the public workflow without logging in.

Logged-in users currently get:

• authenticated session identity
• user-scoped frontend persistence
• user-scoped backend session cache
• account-owned settings and login on daedalmap.com

The public app no longer owns the account/settings UI. app.daedalmap.com stays focused on the runtime and map engine, while .com owns login, account, billing, and admin/runtime control-plane views.

Quick Start

1. Install dependencies

cd county-map
pip install -r requirements.txt

2. Add environment variables

For the smallest GitHub/local setup:

Copy-Item .env.example .env

Then edit DATA_ROOT. The minimum local configuration is:

DEPLOYMENT=local
INSTALL_MODE=local
RUNTIME_MODE=local
DATA_ROOT=C:/path/to/your/local/data

If you leave DATA_ROOT blank, DaedalMap uses the default local app-data path and expects your data to live there. No S3, R2, AWS, database, account, or hosted-control-plane configuration is needed for this path.

No model API key is required for local data operations. Set OPENAI_API_KEY or ANTHROPIC_API_KEY only for the built-in local chat UI. For research using the model from an MCP-capable subscription client, see docs/RESEARCH_MCP.md.

Hosted-style object-storage configuration is intentionally deployment-specific. For public self-hosting, start with local data. Operators who run a cloud-backed deployment should provide their own object-storage bucket, endpoint, and credentials through environment variables.

Most local users should leave these blank unless they intentionally want overrides:

DATA_ROOT=
APP_URL=
SITE_URL=

What they mean:

• DATA_ROOT

only used in RUNTIME_MODE=local; leave blank to use the default local app-data folder

• APP_URL

optional advertised app URL; leave blank for normal local runs

• SITE_URL

optional website/docs/account URL override; leave blank for normal local runs

If you are configuring your own hosted deployment, set:

INSTALL_MODE=cloud
RUNTIME_MODE=cloud
PORT=7000

If you want hosted account behavior, connect this runtime to your own auth, database, and analytics stack or to a separate private control plane you operate. Those business-side services are intentionally not bundled here.

3. Run the app

python app.py

Open:

• http://localhost:7000

API Discovery

The runtime exposes discovery and query endpoints on your local instance.

Discovery (no auth, no payment):

• GET /api/v1/guide
• GET /api/v1/catalog
• GET /api/v1/packs/{pack_id}

Execution:

• POST /api/v1/query/dataset

Self-host instances return commercial_access_unavailable for the paid execution lane unless a commercial verifier is configured. Discovery endpoints work without additional setup.

For managed data access via the hosted API or MCP, see daedalmap.com/docs/for-agents.

Data Resolution

The runtime resolves behavior from two explicit modes:

1. INSTALL_MODE

controls deployment defaults like writable directories and default URLs

1. RUNTIME_MODE

controls the data plane

Data mode behavior:

1. RUNTIME_MODE=local

uses DATA_ROOT

1. RUNTIME_MODE=cloud

uses the hydrated local cloud cache as DATA_ROOT

Default local writable folders on Windows:

• CONFIG_DIR=%LOCALAPPDATA%\DaedalMap\config
• STATE_DIR=%LOCALAPPDATA%\DaedalMap\state
• CACHE_DIR=%LOCALAPPDATA%\DaedalMap\cache
• LOG_DIR=%LOCALAPPDATA%\DaedalMap\logs
• PACKS_ROOT=%LOCALAPPDATA%\DaedalMap\packs
• DATA_ROOT=%LOCALAPPDATA%\DaedalMap\data

In hosted/cloud mode:

• metadata is cached locally
• parquet is queried remotely from object storage

That makes local cloud-mode testing useful for reproducing hosted-runtime behavior before deploy.

Important note:

• the current public repo does not include a bundled data/ demo tree
• a source checkout therefore needs either DATA_ROOT in local mode, or RUNTIME_MODE=cloud with cloud storage configured
• built-in local chat needs OPENAI_API_KEY or ANTHROPIC_API_KEY; the hosted

Research MCP instead uses the model in the researcher's MCP-capable client

Data And Pack Direction

The old “demo data folder plus converters” framing is no longer the whole story.

The current direction is:

• the engine stays open
• maintained data is packaged as packs
• packs are validated and promoted with explicit release gates
• runtime catalogs eventually depend on pack availability, installation, and entitlement state

Key concepts:

• available packs
• installed packs
• entitled packs
• active runtime catalog

These are intentionally distinct.

Explore And Research Contract

Explore chat and Research chat use different discovery paths:

• Explore starts from the runtime catalog, then selects sources.
• Research starts from the active corpus manifest or loaded artifacts, then selects sources.

After a specific source is selected, they should follow the same source contract:

• source-level temporal_coverage is discovery guidance
• metric-level metrics.{metric_id}.years is the execution truth
• default year windows, slider bounds, and metric year ranges should clamp to the selected metric when available

That shared source-specific logic now lives in mapmover/source_time_contract.py. Use that helper module for metric-aware year bounds instead of re-implementing time-range logic separately in Explore or Research code paths.

Settings Page

/settings now behaves differently depending on mode:

• hosted/account-aware mode: redirects to the paired account surface
• self-host/local mode: shows local runtime setup guidance

For self-host users, /settings is the in-app reminder page for:

• required LLM key setup
• current runtime/data/config paths
• the current state of local data vs future pack install flow

Useful Paths In This Repo

Important files and folders:

• app.py - FastAPI app entrypoint
• mapmover/ - runtime logic, routes, path helpers, DuckDB helpers
• static/ - frontend app modules and styles
• templates/ - app HTML shell
• docs/ - local documentation for schemas, runtime notes, and reference material

Documentation In This Repo

Public runtime docs live in docs/README.md.

Recommended starting points:

• docs/CONTEXT.md - technical router for contributors and researchers
• docs/LOCAL_AND_HOSTED.md - runtime mode selection and self-host basics
• docs/RUNTIME_MODES.md - Explore, Research, Ops, and Tutorial
• docs/RUNTIME_UNIFICATION.md - shared architecture and mode extension contract
• docs/DATA_SCHEMAS.md - schema and loc_id conventions
• docs/DATA_PREPARATION.md - convert and validate your own data
• docs/PACK_AUTHORING.md - build research packs and corpora

Local Development Modes

Useful local modes:

1. Full local-data mode

• points at your local DATA_ROOT
• best current self-host mode for GitHub users

1. Hosted-style S3 mode

• local server, but object-storage-backed data path
• best for reproducing hosted runtime behavior before deploy

1. Installed/runtime-pack mode

• planned product direction beyond raw source checkout
• engine/runtime installed separately from data packs
• pack selection and updates handled outside the repo clone flow

Contact

Questions, feedback, or self-host issues: support@daedalmap.com

License

MIT

---

If an agent or tool was pointed at this README for programmable access, use:

• Agent docs: https://daedalmap.com/docs/for-agents
• Machine-readable entry: https://daedalmap.com/llms.txt