Agent Examples - DaedalMap Docs

Step 1 — run these first

Treat these as the mandatory setup step. The first call tells you what is live. The second tells you exactly what one pack expects before you send a query. Run both once, then pick a pack below.

curl https://app.daedalmap.com/api/v1/catalog

curl https://app.daedalmap.com/api/v1/packs/earthquakes

Recommended first path: run the two discovery calls above, then use Currency if you want immediate free rows or Earthquakes if you want to use the full discovery -> 402 -> paid retry flow.

Step 2 — choose your pack for the first call

Pick the lane that matches what you want first: immediate free rows, or a paid pack that starts with a 402 challenge and then returns rows after payment.

Currency — free

Use pack_id = "currency". This pack returns local_per_usd and expects ISO date ranges plus an explicit filters.time.granularity such as daily, weekly, or monthly. The first call below returns monthly rows for three countries over one quarter.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_currency_example",
    "pack_id": "currency",
    "metrics": ["local_per_usd"],
    "filters": {
      "region_ids": ["ARG", "BRA", "CHL"],
      "time": {
        "start": "2024-01-01",
        "end": "2024-03-31",
        "granularity": "monthly"
      }
    },
    "sort": { "field": "date", "direction": "asc" },
    "limit": 12,
    "output": { "format": "rows", "include_provenance": true }
  }'

Once that works, widen or reshape it with one small change at a time:

Daily rates: set filters.time.granularity to daily and narrow the date range.
Compare currencies: include multiple region_ids over the same range.
Cross-rate (e.g. CAD/EUR): query both, then compute cad_per_usd / eur_per_usd client-side.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_currency_daily_example",
    "pack_id": "currency",
    "metrics": ["local_per_usd"],
    "filters": {
      "region_ids": ["EUR", "CAN"],
      "time": {
        "start": "2024-01-01",
        "end": "2024-01-31",
        "granularity": "daily"
      }
    },
    "sort": { "field": "date", "direction": "asc" },
    "limit": 31,
    "output": { "format": "rows" }
  }'

Currency via MCP

curl -X POST https://app.daedalmap.com/mcp/currency \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_fx_rates",
      "arguments": {
        "request_id": "docs_currency_mcp_example",
        "metrics": ["local_per_usd"],
        "filters": {
          "region_ids": ["ARG", "BRA", "CHL"],
          "time": {
            "start": "2024-01-01",
            "end": "2024-03-31",
            "granularity": "monthly"
          }
        },
        "sort": { "field": "date", "direction": "asc" },
        "limit": 12,
        "output": { "format": "rows", "include_provenance": true }
      }
    }
  }'

Earthquakes — paid (x402)

Use source_id = "earthquakes_events". This paid source uses ISO date ranges, country-style region_ids such as JPN, CHL, and IDN, and event-style metrics such as event_count and magnitude. The first unpaid call should return a 402; the payment-aware retry returns rows.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_earthquakes_example",
    "source_id": "earthquakes_events",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["JPN", "CHL", "IDN"],
      "time": { "start": "2011-01-01", "end": "2011-12-31" }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

The first success condition here is not "avoid the 402." The first success condition is: unpaid request returns 402, payment-aware retry returns rows.

Once that path works, move on to narrower variations:

Largest single event: metrics = ["magnitude"], sort value desc, limit = 1.
Events above a threshold: add filters.compare = [{"field":"magnitude","op":">=","value":6}].

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_earthquakes_largest_example",
    "source_id": "earthquakes_events",
    "metrics": ["magnitude"],
    "filters": {
      "region_ids": ["JPN"],
      "time": { "start": "2011-01-01", "end": "2011-12-31" }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 1,
    "output": { "format": "rows" }
  }'

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_earthquakes_threshold_count_example",
    "source_id": "earthquakes_events",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["JPN"],
      "time": { "start": "2011-01-01", "end": "2011-12-31" },
      "compare": [{ "field": "magnitude", "op": ">=", "value": 6 }]
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows" }
  }'

Earthquakes via MCP

curl -X POST https://app.daedalmap.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_earthquake_events",
      "arguments": {
        "request_id": "docs_mcp_earthquakes_example",
        "metrics": ["event_count"],
        "filters": {
          "region_ids": ["JPN", "CHL", "IDN"],
          "time": { "start": "2011-01-01", "end": "2011-12-31" }
        },
        "limit": 10,
        "output": { "format": "rows", "include_provenance": true }
      }
    }
  }'

Volcanoes — free

Use source_id = "volcanoes_events". This source uses year-style time filters, so pass time.value or a numeric year range rather than ISO date strings. The first call below returns event_count rows for three countries in one year.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_volcanoes_example",
    "source_id": "volcanoes_events",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["IDN", "JPN", "CHL"],
      "time": { "value": 2020 }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Largest eruption by VEI: metrics = ["VEI"], sort value desc, limit = 1.
Eruptions above a threshold: add filters.compare against VEI.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_volcanoes_largest_example",
    "source_id": "volcanoes_events",
    "metrics": ["VEI"],
    "filters": {
      "region_ids": ["IDN"],
      "time": { "start": 2015, "end": 2024 }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 1,
    "output": { "format": "rows" }
  }'

Tsunamis — paid (x402)

Use source_id = "tsunamis_events". This paid source uses year-style time filters, so pass numeric years rather than ISO dates. Region filters accept both ISO3 country ids such as JPN and ocean-region ids such as XOO. The first unpaid call should return a 402; the payment-aware retry returns rows.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_tsunamis_example",
    "source_id": "tsunamis_events",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["JPN", "IDN", "XOO"],
      "time": { "value": 2011 }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Largest wave height: metrics = ["max_water_height_m"], sort value desc, limit = 1.
Events above a threshold: add filters.compare against max_water_height_m.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_tsunamis_largest_example",
    "source_id": "tsunamis_events",
    "metrics": ["max_water_height_m"],
    "filters": {
      "region_ids": ["JPN", "XOO"],
      "time": { "start": 2000, "end": 2024 }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 1,
    "output": { "format": "rows" }
  }'

Hurricanes — free

Use source_id = "hurricanes". This source uses ISO date ranges, not numeric years. Region filters accept basin ids such as XNA, XOP, and XIN, and they also accept ISO3 country ids for landfall-style queries. The first call below returns event_count rows for one basin over a date range.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_hurricanes_example",
    "source_id": "hurricanes",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["XNA"],
      "time": { "start": "2000-01-01", "end": "2024-12-31" }
    },
    "sort": { "field": "year", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Most intense storm: metrics = ["max_wind_kt"], sort value desc, limit = 1.
Landfalling storms in a country: replace basin code with an ISO3 id such as USA or PHL.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_hurricanes_intensity_example",
    "source_id": "hurricanes",
    "metrics": ["max_wind_kt"],
    "filters": {
      "region_ids": ["XNA"],
      "time": { "start": "2005-01-01", "end": "2005-12-31" }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 5,
    "output": { "format": "rows" }
  }'

UN SDG — free

UN SDG is pack-shaped but source-driven: use goal ids 01 through 17 as the source_id. Time uses numeric years. Metrics are indicator ids scoped to that goal. The first call below uses source 01 and one poverty indicator across three countries.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_unsdg_example",
    "source_id": "01",
    "metrics": ["ind_1_1_1"],
    "filters": {
      "region_ids": ["BRA", "IND", "NGA"],
      "time": { "start": 2010, "end": 2022 }
    },
    "sort": { "field": "year", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Check the pack detail for available indicator codes per goal before querying.
Track one indicator over time or compare the same indicator across countries in a single year.
Separate questions by SDG goal using source ids 01 through 17.

World Factbook — free

Use source_id = "world_factbook". This source uses numeric years and returns country-level reference metrics whose field names map directly to the metric ids. The first call below returns airports across five countries over time.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_worldfactbook_example",
    "source_id": "world_factbook",
    "metrics": ["airports"],
    "filters": {
      "region_ids": ["USA", "CAN", "BRA", "AUS", "IND"],
      "time": { "start": 2010, "end": 2024 }
    },
    "sort": { "field": "year", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Check the pack detail for available metric names — Factbook field names map directly.
Works well as a cross-reference layer alongside disaster or SDG data.

WorldPop — free

Use source_id = "worldpop". This source requires a geo_level filter to select the geographic grain: admin_0 for country totals, admin_1 for states and provinces, admin_2 for districts. Country totals at admin_0 are pre-aggregated. The first call below returns population for three countries in 2020.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_worldpop_example",
    "source_id": "worldpop",
    "metrics": ["population"],
    "filters": {
      "region_ids": ["USA", "BRA", "IND"],
      "geo_level": "admin_0",
      "time": { "value": 2020 }
    },
    "sort": { "field": "value", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

geo_level is required — omitting it will return an error.
Coverage: global at admin_0, admin_1, admin_2; USA only at admin_3 (Census tract).
Temporal range: 2000–2030 (projections included).

Floods — free

Use source_id = "floods". This source uses numeric years and returns admin2-level aggregate metrics including event counts, severity, affected area, and duration. Coverage runs 1985–2019.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_floods_example",
    "source_id": "floods",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["BGD", "IND", "CHN"],
      "time": { "start": 2000, "end": 2019 }
    },
    "sort": { "field": "year", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Coverage ends at 2019 — queries for later years will return no rows.
Check pack detail for the full metric list including area, duration, and severity fields.

Tornadoes — free

Use source_id = "tornadoes". This source uses numeric years and returns admin2-level aggregate metrics including event counts, EF scale severity, track miles, casualties, and damage. Coverage runs 1950–2025. Data is primarily USA-focused.

curl -X POST https://app.daedalmap.com/api/v1/query/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "docs_tornadoes_example",
    "source_id": "tornadoes",
    "metrics": ["event_count"],
    "filters": {
      "region_ids": ["USA"],
      "time": { "start": 2010, "end": 2024 }
    },
    "sort": { "field": "year", "direction": "desc" },
    "limit": 25,
    "output": { "format": "rows", "include_provenance": true }
  }'

Results are at admin2 (county) level — use a state prefix such as USA-TX- in region_ids to scope to one state.
Check pack detail for EF scale and damage metrics.