Skip to content

160-tool MCP server for real-time global intelligence from free public APIs: markets, liquidity, prediction markets, SEC filings, conflict, military, aircraft-cohort early warning, migration and border flows, cyber, climate, news and more. Dated observation history, 29 research prompts, cited briefs, geofences, SSE dashboard. MIT, no paid API keys.

Dashboard: migration corridor map layer (UNHCR flows between World Bank capitals)

Phoenix Agent (mac-studio)f7ea31cde25d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29ba7c9..7950eb3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,18 @@ Cross-border migration and a fix to the displacement summary.
absolute and per-1,000 terms with world regions, a World Bank region
filter, or one country's series since 1960.
+### Added: migration corridor map layer
+- The dashboard gains a "Migration Flows" layer and `GET /api/migration`
+ (`?limit=` 1-150, default 40; `?year=`): the largest UNHCR origin ->
+ destination corridors plus the fastest-rising ones, drawn capital to
+ capital with weight by people and colour by year-over-year change.
+ Coordinates are the capital-city latitude/longitude of the World Bank
+ country list (`wb_countries` now returns `capital`, `latitude`,
+ `longitude`); the legend says so. Corridors with no coordinates (UNHCR
+ "Unknown" origin, Stateless, West Bank and Gaza) are counted in
+ `unplotted` and listed, never dropped. An upstream failure is a 503 with
+ `error`, shown as `!` and a red legend line, never an empty map.
+
### Added: migration in the CLI and collector
- `intel migration-flows`, `intel migration-surges`, `intel migration-history`
and `intel net-migration` render the four tools as tables, with the same
diff --git a/README.md b/README.md
index 3d5824f..249ba22 100644
--- a/README.md
+++ b/README.md
@@ -120,7 +120,7 @@ intel report -o brief.pdf # custom output path
intel report -s markets,cyber,earthquakes # select sections
```
-Map-first ops center: Leaflet map with toggle-able layers (quakes, military, conflict, fires, convergence, nuclear, infrastructure, your AOI geofences with last-sweep counts), 47 live SSE feeds, HUD bar, glassmorphic panels, per-source circuit breaker health.
+Map-first ops center: Leaflet map with toggle-able layers (quakes, military, conflict, fires, convergence, nuclear, infrastructure, your AOI geofences with last-sweep counts, UNHCR migration corridors between capitals), 47 live SSE feeds, HUD bar, glassmorphic panels, per-source circuit breaker health.
### CLI
diff --git a/src/world_intel_mcp/dashboard/app.py b/src/world_intel_mcp/dashboard/app.py
index d81be81..d1ea96a 100644
--- a/src/world_intel_mcp/dashboard/app.py
+++ b/src/world_intel_mcp/dashboard/app.py
@@ -49,6 +49,7 @@ from world_intel_mcp.sources import (
service_status,
traffic,
webcams,
+ migration,
)
from world_intel_mcp.analysis.alerts import fetch_alert_digest, fetch_weekly_trends
from world_intel_mcp.analysis.posture import fetch_strategic_posture
@@ -581,6 +582,112 @@ async def api_aois(request):
)
+_MIGRATION_DEFAULT_LIMIT = 40
+_MIGRATION_MAX_LIMIT = 150
+_MIGRATION_RISING_LIMIT = 15
+
+
+def _capital_point(iso3: str, wb: dict[str, dict]) -> dict | None:
+ """The country's capital as a map anchor, from the World Bank country list.
+ None for UNHCR's non-country buckets (Unknown, Stateless), for aggregates and
+ for places the World Bank gives no capital coordinates."""
+ c = wb.get(iso3)
+ if not c or c.get("aggregate") or c.get("latitude") is None or c.get("longitude") is None:
+ return None
+ return {"lat": c["latitude"], "lon": c["longitude"], "capital": c.get("capital")}
+
+
+def _place_corridors(corridors: list[dict], wb: dict[str, dict]) -> tuple[list[dict], list[dict]]:
+ """Split corridors into (plotted, unplotted). A plotted corridor gains
+ ``origin_point`` / ``destination_point``; an unplotted one is summarised with
+ the endpoints that have no coordinates, so nothing is dropped silently."""
+ plotted, unplotted = [], []
+ for c in corridors:
+ o = _capital_point(c["origin_iso3"], wb)
+ d = _capital_point(c["destination_iso3"], wb)
+ if o and d:
+ plotted.append({**c, "origin_point": o, "destination_point": d})
+ continue
+ unplotted.append({
+ "origin": c["origin"], "origin_iso3": c["origin_iso3"],
+ "destination": c["destination"], "destination_iso3": c["destination_iso3"],
+ "people": c["people"],
+ "no_coordinates": [side for side, pt in (("origin", o), ("destination", d)) if pt is None],
+ })
+ return plotted, unplotted
+
+
+async def api_migration(request):
+ """Largest origin -> destination migration corridors (UNHCR) anchored on
+ capital-city coordinates (World Bank), plus the fastest-rising corridors.
+
+ ``?limit=`` (1-150, default 40) is how many of the largest corridors to
+ examine; ``?year=`` pins the UNHCR year. Corridors whose endpoint has no
+ coordinates are counted in ``unplotted`` and listed in ``unplotted_corridors``.
+ An upstream failure is a 503 carrying ``error``, never an empty corridor
+ list, so the map cannot show an outage as a quiet world. The rising list is
+ secondary: if only it fails, the largest corridors are still returned with
+ ``rising_error`` set.
+ """
+ cors = {"Access-Control-Allow-Origin": "*"}
+ try:
+ limit = int(request.query_params.get("limit", _MIGRATION_DEFAULT_LIMIT))
+ year_param = request.query_params.get("year")
+ year = int(year_param) if year_param else None
+ except ValueError:
+ return JSONResponse({"error": "limit and year must be integers"}, status_code=400, headers=cors)
+ if not 1 <= limit <= _MIGRATION_MAX_LIMIT:
+ return JSONResponse(
+ {"error": f"limit must be between 1 and {_MIGRATION_MAX_LIMIT}"}, status_code=400, headers=cors
+ )
+
+ fetcher = _ensure_fetcher()
+ try:
+ flows, surges, wb = await asyncio.gather(
+ migration.fetch_migration_flows(fetcher, year=year, limit=limit),
+ migration.fetch_migration_surges(fetcher, year=year, limit=_MIGRATION_RISING_LIMIT),
+ migration.wb_countries(fetcher),
+ )
+ except Exception as exc:
+ logger.warning("Migration layer unavailable: %s", exc)
+ return JSONResponse(
+ {"error": f"Migration fetch failed: {exc}", "corridors": [], "rising": []},
+ status_code=503, headers=cors,
+ )
+ if "error" in flows:
+ return JSONResponse({**flows, "corridors": [], "rising": []}, status_code=503, headers=cors)
+ if wb is None:
+ return JSONResponse(
+ {"error": "World Bank country coordinates unavailable", "source": "worldbank",
+ "corridors": [], "rising": []},
+ status_code=503, headers=cors,
+ )
+
+ plotted, unplotted = _place_corridors(flows["corridors"], wb)
+ payload = {
+ "year": flows["year"],
+ "limit": limit,
+ "corridors": plotted,
+ "plotted": len(plotted),
+ "unplotted": len(unplotted),
+ "unplotted_corridors": unplotted,
+ "corridor_count": flows["corridor_count"],
+ "prior_year_available": flows["prior_year_available"],
+ "anchor": "capital city (World Bank country list); a corridor is drawn capital to capital, "
+ "not along a route",
+ "measure": flows["measure"],
+ "source": "unhcr+worldbank",
+ "timestamp": flows["timestamp"],
+ }
+ if "error" in surges:
+ payload.update(rising=[], rising_unplotted=0, rising_error=surges["error"])
+ else:
+ rising, rising_unplotted = _place_corridors(surges["corridor_increases"], wb)
+ payload.update(rising=rising, rising_unplotted=len(rising_unplotted),
+ compared_with=surges["compared_with"])
+ return JSONResponse(payload, headers=cors)
+
+
async def api_health(request):
"""Health check."""
return JSONResponse({"status": "ok"})
@@ -735,6 +842,7 @@ app = Starlette(
Route("/api/stream", api_stream),
Route("/api/static", api_static),
Route("/api/aois", api_aois),
+ Route("/api/migration", api_migration),
Route("/api/health", api_health),
Route("/api/report/pdf", api_report_pdf),
Route("/sse/vector-analytics", sse_vector_analytics),
diff --git a/src/world_intel_mcp/dashboard/index.html b/src/world_intel_mcp/dashboard/index.html
index fc1377d..e1bf2fe 100644
--- a/src/world_intel_mcp/dashboard/index.html
+++ b/src/world_intel_mcp/dashboard/index.html
@@ -562,6 +562,11 @@ a { color: var(--accent); text-decoration: none; }
}
.leaflet-tooltip.mk-tip::before { border-top-color: var(--border); }
+/* Migration corridor legend (under the layer row) */
+.mig-legend { font-family: var(--mono); font-size: 0.55rem; line-height: 1.5; color: rgba(255,255,255,0.55); padding: 2px 4px 6px 16px; }
+.mig-legend .sw { display: inline-block; width: 14px; height: 3px; vertical-align: middle; margin-right: 4px; border-radius: 2px; }
+.mig-legend.err { color: var(--red); }
+
/* ═══════════════ UTILITY ═══════════════ */
.up { color: var(--green); } .down { color: var(--red); }
.warn { color: var(--amber); } .dim { color: var(--dim); }
@@ -748,6 +753,13 @@ a { color: var(--accent); text-decoration: none; }
<span class="layer-count" id="cntAoi">—</span>
<div class="toggle on" style="--lc:#ff7f50"><div class="knob"></div></div>
</div>
+ <div class="layer-row" data-layer="migration">
+ <span class="layer-dot" style="background:#f472b6"></span>
+ <span class="layer-label">Migration Flows</span>
+ <span class="layer-count" id="cntMigration">—</span>
+ <div class="toggle on" style="--lc:#f472b6"><div class="knob"></div></div>
+ </div>
+ <div class="mig-legend" id="migLegend">loading UNHCR corridors…</div>
<div style="border-top:1px solid rgba(255,255,255,0.08);margin-top:4px;padding-top:6px">
<div style="font-size:0.55rem;letter-spacing:1px;color:rgba(255,255,255,0.35);margin-bottom:4px">REGION</div>
<div id="regionPresets" style="display:flex;flex-wrap:wrap;gap:2px">
@@ -835,7 +847,7 @@ function _withinTimeWindow(ts) { if (!ts) return true; var age = Date.now() - ne
var latestData = null;
var map = null;
var mapLayers = {};
-var layerState = { quakes: true, military: true, conflict: true, fires: true, convergence: true, nuclear: true, infra: true, exposure: true, airtraffic: true, traffic: true, navwarnings: true, webcams: true, climate: true, news: true, aoi: true };
+var layerState = { quakes: true, military: true, conflict: true, fires: true, convergence: true, nuclear: true, infra: true, exposure: true, airtraffic: true, traffic: true, navwarnings: true, webcams: true, climate: true, news: true, aoi: true, migration: true };
// Restore saved layer toggles from localStorage
try { var _saved = JSON.parse(localStorage.getItem('phoenix-layers')); if (_saved) { for (var _k in _saved) { if (layerState.hasOwnProperty(_k)) layerState[_k] = _saved[_k]; } } } catch(e) {}
var drawerOpen = false;
@@ -933,6 +945,10 @@ function initMap() {
mapLayers.climate = L.layerGroup().addTo(map);
mapLayers.news = L.markerClusterGroup(clusterOpts(null, 35)).addTo(map);
mapLayers.aoi = L.layerGroup().addTo(map);
+ mapLayers.migration = L.layerGroup().addTo(map);
+ // The legend explains the lines (or the outage), so it follows the layer however it is toggled.
+ mapLayers.migration.on('add', function() { $('#migLegend').style.display = ''; });
+ mapLayers.migration.on('remove', function() { $('#migLegend').style.display = 'none'; });
}
// ════════════ LAYER TOGGLES ════════════
@@ -958,8 +974,8 @@ $('#drawerToggle').addEventListener('click', function() {
});
// ════════════ DETAIL MODAL ════════════
-var COLORS = { earthquake: 'var(--red)', military: 'var(--blue)', conflict: 'var(--amber)', fire: 'var(--gold)', convergence: 'var(--purple)', nuclear: 'var(--green)', military_base: 'var(--teal)', port: 'var(--blue)', nuclear_facility: 'var(--gold)', pipeline: 'var(--purple)', exposure: '#e040fb', waterway: 'var(--accent)', cable: 'var(--blue)', airtraffic: '#00c8ff', traffic_city: '#e0e0e0', navwarn: '#ffc832', webcam: '#909090', aoi: '#ff7f50' };
-var LABELS = { earthquake: 'EARTHQUAKE', military: 'MILITARY AIRCRAFT', conflict: 'CONFLICT EVENT', fire: 'WILDFIRE CLUSTER', convergence: 'SIGNAL CONVERGENCE', nuclear: 'NUCLEAR MONITOR', military_base: 'MILITARY BASE', port: 'STRATEGIC PORT', nuclear_facility: 'NUCLEAR FACILITY', pipeline: 'PIPELINE', exposure: 'POPULATION EXPOSURE', waterway: 'STRATEGIC WATERWAY', cable: 'CABLE CORRIDOR', airtraffic: 'AIRCRAFT', traffic_city: 'TRAFFIC CONGESTION', navwarn: 'NAVIGATION WARNING', webcam: 'WEBCAM', aoi: 'AOI GEOFENCE' };
+var COLORS = { earthquake: 'var(--red)', military: 'var(--blue)', conflict: 'var(--amber)', fire: 'var(--gold)', convergence: 'var(--purple)', nuclear: 'var(--green)', military_base: 'var(--teal)', port: 'var(--blue)', nuclear_facility: 'var(--gold)', pipeline: 'var(--purple)', exposure: '#e040fb', waterway: 'var(--accent)', cable: 'var(--blue)', airtraffic: '#00c8ff', traffic_city: '#e0e0e0', navwarn: '#ffc832', webcam: '#909090', aoi: '#ff7f50', migration: '#f472b6' };
+var LABELS = { earthquake: 'EARTHQUAKE', military: 'MILITARY AIRCRAFT', conflict: 'CONFLICT EVENT', fire: 'WILDFIRE CLUSTER', convergence: 'SIGNAL CONVERGENCE', nuclear: 'NUCLEAR MONITOR', military_base: 'MILITARY BASE', port: 'STRATEGIC PORT', nuclear_facility: 'NUCLEAR FACILITY', pipeline: 'PIPELINE', exposure: 'POPULATION EXPOSURE', waterway: 'STRATEGIC WATERWAY', cable: 'CABLE CORRIDOR', airtraffic: 'AIRCRAFT', traffic_city: 'TRAFFIC CONGESTION', navwarn: 'NAVIGATION WARNING', webcam: 'WEBCAM', aoi: 'AOI GEOFENCE', migration: 'MIGRATION CORRIDOR' };
function showDetail(type, d) {
var title = '', subtitle = '', fields = [], link = '';
@@ -1164,6 +1180,20 @@ function showDetail(type, d) {
['Significant', d.is_significant ? 'YES' : 'No', d.is_significant ? 'crit' : 'ok'],
['Coordinates', d.lat != null ? d.lat.toFixed(3) + ', ' + d.lon.toFixed(3) : '\u2014']
];
+ } else if (type === 'migration') {
+ title = (d.origin || '?') + ' \u2192 ' + (d.destination || '?');
+ subtitle = 'UNHCR year-end stock, capital to capital';
+ fields = [
+ ['Origin', d.origin || '\u2014'],
+ ['Destination', d.destination || '\u2014'],
+ ['People', fmtPeople(d.people)],
+ ['Refugees', d.refugees != null ? fmtPeople(d.refugees) : '\u2014'],
+ ['Asylum seekers', d.asylum_seekers != null ? fmtPeople(d.asylum_seekers) : '\u2014'],
+ ['Other in need of protection', d.other_in_need_of_protection != null ? fmtPeople(d.other_in_need_of_protection) : '\u2014'],
+ ['Prior year', d.prior_year_people != null ? fmtPeople(d.prior_year_people) : 'n/a'],
+ ['Change', fmtPeopleChange(d.change), d.change > 0 ? 'high' : ''],
+ ['Anchors', (d.origin_point.capital || '?') + ' \u2192 ' + (d.destination_point.capital || '?')]
+ ];
}
var hdr = '<div class="detail-cat"><span class="detail-cat-dot" style="background:' + c + ';--cat-color:' + c + '"></span><span class="detail-cat-label">' + esc(LABELS[type] || type) + '</span></div>' +
@@ -1529,7 +1559,7 @@ function _toggleHelp() {
document.body.appendChild(_helpOverlay);
}
-var _layerKeys = ['quakes','military','conflict','fires','convergence','nuclear','infra','exposure','airtraffic','news','aoi'];
+var _layerKeys = ['quakes','military','conflict','fires','convergence','nuclear','infra','exposure','airtraffic','news','aoi','migration'];
function _toggleLayerByIndex(idx) {
var key = _layerKeys[idx];
if (!key || !mapLayers[key]) return;
@@ -3251,6 +3281,70 @@ function updateMapAois(data) {
cnt.textContent = aois.length;
cnt.title = '';
}
+// Migration corridors: UNHCR origin -> destination year-end stocks, drawn capital to capital
+// (the World Bank gives one coordinate per country). Line weight = people, colour = year-over-year
+// change. An outage shows in the count and legend; it must never read as a quiet world.
+function fmtPeople(n) { return n == null ? '\u2014' : Number(n).toLocaleString('en-US'); }
+function fmtPeopleChange(n) { return n == null ? 'n/a' : (n > 0 ? '+' : '') + Number(n).toLocaleString('en-US'); }
+function _migArc(a, b) {
+ // Short way round the globe, bowed to the left of travel so opposite flows do not overlap.
+ var lon2 = b.lon;
+ if (lon2 - a.lon > 180) lon2 -= 360; else if (lon2 - a.lon < -180) lon2 += 360;
+ var mx = (a.lat + b.lat) / 2, my = (a.lon + lon2) / 2;
+ var dx = b.lat - a.lat, dy = lon2 - a.lon;
+ var cx = mx - dy * 0.18, cy = my + dx * 0.18;
+ var pts = [];
+ for (var i = 0; i <= 20; i++) {
+ var t = i / 20, u = 1 - t;
+ pts.push([u * u * a.lat + 2 * u * t * cx + t * t * b.lat, u * u * a.lon + 2 * u * t * cy + t * t * lon2]);
+ }
+ return pts;
+}
+function updateMapMigration(data) {
+ mapLayers.migration.clearLayers();
+ var cnt = $('#cntMigration'), lg = $('#migLegend');
+ if (!data || data.error) {
+ var msg = (data && data.error) || 'migration fetch failed';
+ cnt.textContent = '!'; cnt.title = msg;
+ lg.className = 'mig-legend err'; lg.textContent = 'Migration data unavailable: ' + msg;
+ return;
+ }
+ var drawn = {}, maxPeople = 1;
+ var all = (data.corridors || []).map(function(c) { return { c: c, rising: false }; });
+ all.forEach(function(x) { drawn[x.c.origin_iso3 + '|' + x.c.destination_iso3] = true; });
+ (data.rising || []).forEach(function(c) {
+ if (!drawn[c.origin_iso3 + '|' + c.destination_iso3]) all.push({ c: c, rising: true });
+ });
+ all.forEach(function(x) { if (x.c.people > maxPeople) maxPeople = x.c.people; });
+ all.forEach(function(x) {
+ var c = x.c;
+ var col = c.change == null || c.change === 0 ? '#8a94a6' : c.change > 0 ? '#FF3B3B' : '#2DD4BF';
+ var w = 1.5 + 9 * Math.sqrt(c.people / maxPeople);
+ var line = L.polyline(_migArc(c.origin_point, c.destination_point), { color: col, weight: w, opacity: 0.7, dashArray: x.rising ? '6 5' : null, className: 'migration-line' });
+ var tip = '<b>' + esc(c.origin) + ' \u2192 ' + esc(c.destination) + '</b><br>' + esc(fmtPeople(c.people)) + ' people' +
+ '<br><span style="opacity:0.7">change ' + esc(fmtPeopleChange(c.change)) + (c.pct_change != null ? ' (' + esc((c.pct_change > 0 ? '+' : '') + c.pct_change) + '%)' : '') + '</span>';
+ line.bindTooltip(tip, { className: 'mk-tip', sticky: true });
+ line.on('click', function() { showDetail('migration', c); });
+ line.addTo(mapLayers.migration);
+ // The head marks the destination end, so direction reads without arrowheads.
+ L.circleMarker([c.destination_point.lat, c.destination_point.lon], { radius: w / 2 + 2, color: col, weight: 1, fillColor: col, fillOpacity: 0.9 }).addTo(mapLayers.migration);
+ });
+ cnt.textContent = (data.corridors || []).length;
+ cnt.title = '';
+ lg.className = 'mig-legend';
+ var parts = [];
+ parts.push('UNHCR ' + esc(String(data.year)) + ' year-end stock, ' + esc(String(data.plotted)) + ' largest corridors, capital to capital (World Bank).');
+ parts.push('<span class="sw" style="background:#FF3B3B"></span>up <span class="sw" style="background:#2DD4BF"></span>down <span class="sw" style="background:#8a94a6"></span>n/a; width = people; dot = destination; dashed = rising corridor outside the top list.');
+ if (data.unplotted) parts.push(esc(String(data.unplotted)) + ' corridor(s) unplotted, no coordinates: ' + esc((data.unplotted_corridors || []).slice(0, 5).map(function(u) { return u.origin + ' \u2192 ' + u.destination; }).join('; ')) + (data.unplotted > 5 ? '; \u2026' : ''));
+ if (data.rising_error) parts.push('<span style="color:var(--red)">Rising corridors unavailable: ' + esc(data.rising_error) + '</span>');
+ else if (data.rising_unplotted) parts.push(esc(String(data.rising_unplotted)) + ' rising corridor(s) unplotted.');
+ lg.innerHTML = parts.join('<br>');
+}
+fetch('/api/migration')
+ .then(function(r) { return r.json(); })
+ .then(function(data) { try { updateMapMigration(data); } catch(e) { console.warn('migration layer failed:', e); updateMapMigration({ error: String(e) }); } })
+ .catch(function(e) { console.warn('migration fetch failed:', e); updateMapMigration({ error: String(e) }); });
+
fetch('/api/aois')
.then(function(r) { return r.json(); })
.then(function(data) { try { updateMapAois(data); } catch(e) { console.warn('aoi layer failed:', e); } })
diff --git a/src/world_intel_mcp/sources/migration.py b/src/world_intel_mcp/sources/migration.py
index a0a2344..108a9b8 100644
--- a/src/world_intel_mcp/sources/migration.py
+++ b/src/world_intel_mcp/sources/migration.py
@@ -179,8 +179,18 @@ async def _wb_indicator(fetcher: Fetcher, indicator: str, country: str = "all",
return rows
+def _coord(value: Any) -> float | None:
+ """A World Bank coordinate string ("15.5932"), or None for the empty string
+ it returns for aggregates and for places without a capital (West Bank and Gaza)."""
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ return None
+
+
async def wb_countries(fetcher: Fetcher) -> dict[str, dict] | None:
- """ISO-3 -> {name, region, income, aggregate} from the World Bank country list."""
+ """ISO-3 -> {name, region, income, aggregate, capital, latitude, longitude}
+ from the World Bank country list. The coordinates are the capital city's."""
data = await fetcher.get_json(
url=_WB + "country", source="worldbank", cache_key="migration:wb:countries",
cache_ttl=_META_TTL, params={"format": "json", "per_page": 1000},
@@ -197,6 +207,9 @@ async def wb_countries(fetcher: Fetcher) -> dict[str, dict] | None:
"region_id": region.get("id"),
"income": ((c.get("incomeLevel") or {}).get("value") or "").strip(),
"aggregate": region.get("id") == "NA",
+ "capital": (c.get("capitalCity") or "").strip() or None,
+ "latitude": _coord(c.get("latitude")),
+ "longitude": _coord(c.get("longitude")),
}
return out
diff --git a/src/world_intel_mcp/tests/test_dashboard_migration.py b/src/world_intel_mcp/tests/test_dashboard_migration.py
new file mode 100644
index 0000000..cb28a41
--- /dev/null
+++ b/src/world_intel_mcp/tests/test_dashboard_migration.py
@@ -0,0 +1,201 @@
+"""Tests for the dashboard's /api/migration endpoint (migration corridor map layer).
+
+The map draws the largest UNHCR origin -> destination corridors as lines between
+capital-city coordinates taken from the World Bank country list. The fetch
+functions are faked at the ``sources.migration`` module boundary (their own
+parsing is covered by test_migration.py); these tests pin what the endpoint adds:
+coordinates attached from World Bank data, corridors without coordinates counted
+and listed instead of dropped, and upstream failure surfaced as an error instead
+of an empty (quiet-looking) corridor list.
+
+Gaps / not covered: the Leaflet rendering (index.html JS) has no automated test;
+it is verified by loading the dashboard in a headless browser by hand.
+"""
+
+from __future__ import annotations
+
+import pytest
+from starlette.testclient import TestClient
+
+from world_intel_mcp.dashboard import app as dashboard_app
+from world_intel_mcp.sources import migration
+
+
+def _wb(iso, capital, lat, lon, aggregate=False):
+ return {"name": iso, "iso2": None, "region": "", "region_id": "NA" if aggregate else "X",
+ "income": "", "aggregate": aggregate, "capital": capital, "latitude": lat, "longitude": lon}
+
+
+_WB = {
+ "SDN": _wb("SDN", "Khartoum", 15.5932, 32.5363),
+ "TCD": _wb("TCD", "N'Djamena", 12.1048, 15.0445),
+ "EGY": _wb("EGY", "Cairo", 30.0982, 31.2461),
+ "PSE": _wb("PSE", None, None, None), # real World Bank row: no capital, empty coordinates
+ "WLD": _wb("WLD", None, None, None, aggregate=True),
+}
+
+
+def _corridor(o, d, people, change=None, prior=None, **extra):
+ return {"origin": o, "origin_iso3": o, "destination": d, "destination_iso3": d,
+ "people": people, "refugees": people, "asylum_seekers": 0,
+ "other_in_need_of_protection": 0, "prior_year_people": prior, "change": change, **extra}
+
+
+_FLOWS = {
+ "year": 2025, "corridor_count": 4, "prior_year_available": True, "measure": "stock",
+ "timestamp": "2026-10-11T00:00:00Z", "source": "unhcr",
+ "corridors": [
+ _corridor("SDN", "TCD", 1_200_000, change=800_000, prior=400_000),
+ _corridor("UNK", "EGY", 900_000, change=0, prior=900_000), # UNHCR "Unknown" bucket
+ _corridor("PSE", "EGY", 50_000), # no capital coordinates, prior year unknown
+ _corridor("SDN", "EGY", 700_000, change=-10, prior=700_010),
+ ],
+}
+
+_SURGES = {
+ "year": 2025, "compared_with": 2024, "source": "unhcr",
+ "corridor_increases": [
+ _corridor("SDN", "TCD", 1_200_000, change=800_000, prior=400_000, pct_change=200.0),
+ _corridor("SDN", "XXA", 99_000, change=60_000, prior=39_000, pct_change=153.8),
+ ],
+}
+
+
+def faked(monkeypatch: pytest.MonkeyPatch) -> dict:
+ """Replace the three upstream calls; each test edits the returned dict."""
+ state = {"flows": _FLOWS, "surges": _SURGES, "wb": _WB, "calls": []}
+
+ async def flows(fetcher, year=None, limit=25, **_):
+ state["calls"].append(("flows", year, limit))
+ return state["flows"]
+
+ async def surges(fetcher, year=None, limit=20, **_):
+ state["calls"].append(("surges", year, limit))
+ return state["surges"]
+
+ async def wb(fetcher):
+ return state["wb"]
+
+ monkeypatch.setattr(migration, "fetch_migration_flows", flows)
+ monkeypatch.setattr(migration, "fetch_migration_surges", surges)
+ monkeypatch.setattr(migration, "wb_countries", wb)
+ monkeypatch.setattr(dashboard_app, "_ensure_fetcher", lambda: object())
+ return state
+
+
+def client() -> TestClient:
+ return TestClient(dashboard_app.app)
+
+
+def test_coordinates_attached_from_world_bank_capitals(client, faked) -> None:
+ r = client.get("/api/migration")
+ assert r.status_code == 200
+ body = r.json()
+ assert "error" not in body
+ assert r.headers.get("access-control-allow-origin") == "*"
+ by_pair = {(c["origin_iso3"], c["destination_iso3"]): c for c in body["corridors"]}
+ sdn_tcd = by_pair[("SDN", "TCD")]
+ assert sdn_tcd["origin_point"] == {"lat": 15.5932, "lon": 32.5363, "capital": "Khartoum"}
+ assert sdn_tcd["destination_point"] == {"lat": 12.1048, "lon": 15.0445, "capital": "N'Djamena"}
+ assert sdn_tcd["people"] == 1_200_000 and sdn_tcd["change"] == 800_000
+ assert set(by_pair) == {("SDN", "TCD"), ("SDN", "EGY")}
+ assert body["plotted"] == 2
+ assert body["year"] == 2025
+ assert "capital" in body["anchor"]
+
+
+def test_unplotted_corridors_are_counted_and_named_not_dropped(client, faked) -> None:
+ body = client.get("/api/migration").json()
+ assert body["unplotted"] == 2
+ assert body["plotted"] + body["unplotted"] == len(_FLOWS["corridors"])
+ missing = {(u["origin_iso3"], u["destination_iso3"]): u for u in body["unplotted_corridors"]}
+ assert missing[("UNK", "EGY")]["no_coordinates"] == ["origin"]
+ assert missing[("PSE", "EGY")]["no_coordinates"] == ["origin"]
+ assert missing[("UNK", "EGY")]["people"] == 900_000
+
+
+def test_aggregate_and_unknown_iso_have_no_anchor(client, faked) -> None:
+ faked["flows"] = {**_FLOWS, "corridors": [_corridor("SDN", "WLD", 5), _corridor("SDN", "ZZZ", 6)]}
+ body = client.get("/api/migration").json()
+ assert body["plotted"] == 0
+ assert body["unplotted"] == 2
+ assert all(u["no_coordinates"] == ["destination"] for u in body["unplotted_corridors"])
+
+
+def test_rising_corridors_placed_and_unplotted_counted(client, faked) -> None:
+ body = client.get("/api/migration").json()
+ assert [(c["origin_iso3"], c["destination_iso3"]) for c in body["rising"]] == [("SDN", "TCD")]
+ assert body["rising"][0]["destination_point"]["capital"] == "N'Djamena"
+ assert body["rising_unplotted"] == 1 # SDN -> XXA (stateless bucket)
+ assert body["compared_with"] == 2024
+ assert "rising_error" not in body
+
+
+def test_flows_error_passes_through_as_503_not_an_empty_map(client, faked) -> None:
+ faked["flows"] = {"error": "UNHCR population API unavailable", "degraded": True, "source": "unhcr"}
+ r = client.get("/api/migration")
+ assert r.status_code == 503
+ body = r.json()
+ assert body["error"] == "UNHCR population API unavailable"
+ assert body["corridors"] == [] and body["rising"] == []
+ assert "plotted" not in body # no zero count that could read as "quiet"
+
+
+def test_missing_world_bank_coordinates_is_an_error(client, faked) -> None:
+ faked["wb"] = None
+ r = client.get("/api/migration")
+ assert r.status_code == 503
+ assert "World Bank" in r.json()["error"]
+
+
+def test_upstream_exception_is_an_error(client, faked, monkeypatch) -> None:
+ async def boom(fetcher, **_):
+ raise RuntimeError("socket closed")
+
+ monkeypatch.setattr(migration, "fetch_migration_flows", boom)
+ r = client.get("/api/migration")
+ assert r.status_code == 503
+ assert "socket closed" in r.json()["error"]
+
+
+def test_surge_failure_keeps_corridors_and_reports_rising_error(client, faked) -> None:
+ faked["surges"] = {"error": "UNHCR has no data for 2025 and 2024 to compare", "degraded": True}
+ r = client.get("/api/migration")
+ assert r.status_code == 200
+ body = r.json()
+ assert body["plotted"] == 2
+ assert body["rising"] == []
+ assert body["rising_error"] == "UNHCR has no data for 2025 and 2024 to compare"
+
+
+def test_limit_and_year_are_passed_to_the_tools_and_validated(client, faked) -> None:
+ assert client.get("/api/migration?limit=12&year=2024").status_code == 200
+ assert ("flows", 2024, 12) in faked["calls"]
+ assert ("surges", 2024, dashboard_app._MIGRATION_RISING_LIMIT) in faked["calls"]
+ for bad in ("limit=0", "limit=151", "limit=abc", "year=x"):
+ r = client.get(f"/api/migration?{bad}")
+ assert r.status_code == 400, bad
+ assert "error" in r.json()
+
+
+async def test_wb_countries_reads_capital_coordinates() -> None:
+ """Coordinates come off the World Bank response; an empty string (West Bank
+ and Gaza, aggregates) becomes None rather than 0.0."""
+ rows = [
+ {"id": "SDN", "iso2Code": "SD", "name": "Sudan", "region": {"id": "SSF", "value": "Sub-Saharan Africa "},
+ "incomeLevel": {"value": "Low income"}, "capitalCity": "Khartoum",
+ "longitude": "32.5363", "latitude": "15.5932"},
+ {"id": "PSE", "iso2Code": "PS", "name": "West Bank and Gaza", "region": {"id": "MEA", "value": "MENA"},
+ "incomeLevel": {"value": "Lower middle income"}, "capitalCity": "", "longitude": "", "latitude": ""},
+ ]
+
+ class Stub:
+ async def get_json(self, **kwargs):
+ return [{"page": 1}, rows]
+
+ out = await migration.wb_countries(Stub())
+ assert (out["SDN"]["latitude"], out["SDN"]["longitude"], out["SDN"]["capital"]) == (15.5932, 32.5363, "Khartoum")
+ assert out["PSE"]["latitude"] is None and out["PSE"]["longitude"] is None and out["PSE"]["capital"] is None