docs/cross-border-movements.md

Rama main · réplica de lectura del repositorio original.

---
noindex: true
---

# Cross-border movement sources

Issue #9023 extends the ODP situation view with independently published route reports. Counts keep their source, date and measure. Stocks, arrivals, returnees, deaths and enforcement encounters must not be added together. Countries and situations can overlap.

| Source | Automatic retrieval | Normal cadence | Maximum report age | Licence and access evidence, 2026-10-20 |
| --- | --- | --- | --- | --- |
| UNHCR Operational Data Portal | Existing situation JSON | Daily worker | 45 days per country report | [ODP](https://data.unhcr.org/) footer states datasets are CC BY 4.0. Credit UNHCR and the situation; identify WorldMonitor transformations. |
| UK Home Office | GOV.UK Content API, daily table and linked SB_01 ODS sheet | Daily worker | 3 days | [OGL v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). Contains public sector information licensed under the Open Government Licence v3.0. |
| US CBP | Official Nationwide Encounters AOR CSV, southwest land border only | Daily discovery of monthly releases | 75 days | [CBP copyright notice](https://www.cbp.gov/site-policy-notices/copyright-notice). US government work unless otherwise noted. Encounters count enforcement events, not unique people or new arrivals. |
| Frontex | Official monthly XLSX, discovered from the migratory map | Daily discovery of monthly releases | 75 days | Repository owner confirmed reuse permission on 2026-10-20. Credit Frontex; label counts as detections, not unique people. [Source](https://www.frontex.europa.eu/what-we-do/monitoring-and-risk-analysis/migratory-map/) and [legal disclaimer](https://www.frontex.europa.eu/legal-disclaimer/). |
| IOM Missing Migrants / HDX | Inactive | Weekly | Not configured | Package metadata identifies CC BY IGO. HDX automated retrieval returned an explicit bot-activity block and a direction to contact HDX. A separately readable CSV does not establish worker access. No bypass or automated feed is enabled. |
| Panama Darien | Official Darién statistics PDF, discovered by report year | Daily discovery of monthly releases | 75 days | Repository owner confirmed reuse permission on 2026-10-20. Credit Servicio Nacional de Migración, Panamá. Figures are preliminary and subject to revision. [Source](https://www.migracion.gob.pa/estadisticas/). |
| IDMC | Separate internal-displacement worker via HDX (#9444); not in this cross-border view | Daily worker | Separate source contract | Main added IDU internal-displacement events from public HDX CSVs. The Helix API still requires a client ID; this route view does not read the IDU cache. |

The UK series returns rolling 7- and 30-day totals only when every day in that window is present. A missing observation is unknown; an explicitly reported zero remains zero. Thirty-day change compares two disjoint 30-day windows. Revisions in the daily table replace the same date in the ODS history. A weekly surge requires more than 10,000 arrivals, or at least 1,000 arrivals and twice the median of prior complete weekly windows over 90 days, with at least three complete baseline windows. Cross-source signals use the source report clock. CII v14 adds five points once per explicitly named country for fresh arrival surges, including the existing ODP monthly arrival acceleration. Stocks and CBP encounters cannot trigger it.

Frontex nationality and border-type rows are summed once per route and month. Multi-country routes have no single country attribution. Frontex detections use the encounter measure and cannot trigger an arrival surge. Panama uses the first regional table's monthly totals, not its year-to-date total. A partial current month is omitted. Missing published observations reject the report; future month placeholders do not become zeros. A monthly arrival surge requires at least 1,000 arrivals and twice the median of three preceding complete months. Existing cross-source signals retain their weekly UK-only criterion.

`GetCrossBorderMovements` reads only Redis and supports a two-letter `country_code` and exact `route` ID. Country input is case-insensitive; assigned ISO codes are not checked, so an unmatched value returns no rows. The projection retains at most 1,000 valid movements per source, in report order, and marks a truncated source partial. One large source cannot consume another source's allowance. The generated response schema caps movements at 5,000 and source statuses at 5. The unfiltered shared request is public; filtered requests use the existing authenticated API path. MCP `get_displacement_data` retains its annual default. Set `view=movements` for operational reports, `countries` and `route` for filters, and `limit=0` for all projected rows. The default movement limit is 30, so it is not a global coverage inventory. Licence, credit and transformation notice survive projections. Stock changes retain their observation interval and remain distinct from arrival totals.

Each new source has its own key, original fetch clock, report clock, seed metadata, activation marker and last-good policy. Health stays activation-gated before the first successful publication. A failing source cannot suppress another source in the movement API. CII instead rejects builds on Redis read errors and retains last-good scores; genuine missing source keys remain unavailable inputs. The API keeps stale reports labeled as stale; the map excludes them and draws deaths separately. ODP country points without a complete monthly observation are omitted rather than mislabeled with a year-to-date total.

## Acceptance limits

### Scheduled publication observed on 2026-10-20

Read-only observation confirmed the first natural publication from the scheduled `data-seeder-health` worker. Deployment `23754c92-89ee-4788-9dea-e4457beb87b2` ran the merged #9438 code and finished at 09:03:45 UTC. Its source sections verified Redis writes for UK (1 record), CBP (1), Frontex (9) and Panama (1), all `OK`. At 09:08 UTC, all four canonical keys, seed metadata and activation markers were present. The public movement RPC and MCP `get_displacement_data` with `view=movements, limit=0` returned the same 120 rows and source statuses: four `ok`, ODP `partial`. No manual seed, activation, deployment or cache invalidation was used for this check.

Frontex reports nine route totals through 2026-08-31, including explicit zeros for Black Sea and Other routes. Panama reports 71 September arrivals, ending 2026-09-30, against a year-to-date total of 539. UK ends 2026-10-18; CBP ends 2026-08-31. Source report clocks remain separate from the worker fetch time.

The fixed coverage inventory now contains 15 fresh routes/situations across Africa, Asia, Europe and North America. Eleven are population stocks, three are arrival series (Europe and North America), and one is a CBP encounter series. This meets the inventory threshold but does not establish global operational arrival coverage or independent, non-overlapping counts. The newest ODP Americas report is 2025-12-31, DRC 2026-04-30 and Central Asia 2026-06-30; these old reports remain stale. IOM Missing Migrants/HDX remains inactive. IDMC's separate internal-displacement worker does not supply this route view. A second natural daily publication and the remaining issue acceptance checks are still required; this follow-up must not close #9023.

For the second daily run, inspect `seed-meta:displacement:border-uk`, `seed-meta:displacement:border-cbp`, `seed-meta:displacement:border-frontex`, `seed-meta:displacement:border-panama`, their canonical keys and `/api/health`. Require source-specific fetch/content clocks and valid rows. Railway workers must use Node.js 24 as required by this repository. Check that a failure preserves the original clock and another source remains readable. Stop the affected worker on parser or licence failures. Do not convert unavailable or missing periods into zero.

### UNHCR Routes Monitor export research

The [UNHCR Routes Monitor working-group page](https://data.unhcr.org/en/working-group/496) embeds a public Power BI report. Its About page describes monthly consolidation of government and UNHCR reports, with source links on country pages and differing national reporting cycles. The report inspected on 2026-10-20 says “Updated: Oct 2026”, while its route overview includes August observations. The publication date cannot replace the observation period.

No supported CSV/XLSX download or documented dataset endpoint was found on that landing page or the report's About and Routes in Focus pages. [Microsoft's Publish to web limitations](https://learn.microsoft.com/en-us/power-bi/collaborate-share/service-publish-to-web#considerations-and-limitations) explicitly exclude exporting visual data. A readable chart is not an established worker export. The report directs questions to `ams-dips@unhcr.org`; no message has been sent.

The next external dependency is a publisher-provided CSV/XLSX or documented endpoint, with route/country, indicator, observation period, count, source, revisions, cadence and reuse terms. Confirm monthly versus quarterly reporting per route before choosing freshness budgets. Keep stocks, arrivals, departures, encounters and deaths separate. Until that export is supplied and tested, do not infer missing periods as zero or enable a new feed by scraping chart labels.

### Renderer verification

SVG and globe maps receive the same already filtered movement projection as deck.gl. The displacement layer controls these points, alongside annual displacement markers on globe and deck.gl. Deaths use separate red cross markers. Other movement markers retain their kind and observation measure. Click or keyboard activation opens source links, dates and period details. SVG points participate in its viewport budget. Globe points participate in its shared marker budget. Controlled browser fixtures verify the UI independently from the live-source observations above. Mobile keeps its existing fixed-layer controls.