Madrid Urban Evidence Lens

A place-first, source-disciplined geospatial workspace for reading what official sources document about urban development in Madrid — and what that evidence does not permit you to conclude. The next architecture (Gate K / #64) formalizes scope, freshness and interpretation ceiling as explicit, uniform properties of every evidence object; today they are documented per source rather than guaranteed on every value.

Open the live Madrid lens · Current scope and limits

See Lens in action

• Place: search an official barrio and read its registered residents and licensed VUT units, each with its scope and reference date. Barrio figures are never presented as Lens-circle figures.
• Compare: place two Lens windows side by side. Densities are compared where that is valid; the mobility comparison above is withheld because the window sizes differ.
• Evidence: ask a question the evidence cannot support and Lens refuses it, then open Evidence & limits for the source, dates and interpretation ceiling.

See the full evidence demonstration, with screenshots, limits and capture provenance →

1. What question does it answer?

It starts from a place and a question about it, not from a dataset. For a point on the map it is built to answer, in plain terms:

• Which official area am I looking at, and who lives there?
• What do official sources document about this place?
• How does this place compare with another, at a spatial window I control?
• Which source supports each statement, and what can it not be used to claim?

The reading is designed for two audiences over the same evidence: a Madrid resident or local stakeholder as the primary reader, and a planner, researcher or assessor who verifies it. A citizen reading may omit detail; it never makes a different claim. The vocabulary that keeps those two readings honest is defined in docs/PRODUCT_SEMANTICS.md.

2. What is shipped today, and what is the authorized next direction?

Currently shipped is the tourism-and-context evidence the sections below describe in full: a draggable spatial lens over central Madrid that recalculates local counts of museums, tourist information, accommodation and mobility nodes; optional observed pedestrian-counter activity and bounded HATI thermal research; the whole-barrio Area Profile, licensed-VUT and city hotel-demand context; and the comparison, halo and sensitivity machinery. None of that changes with this reframing.

The authorized next direction, set by Gate K, is to make urban-development evidence the organising frame, with tourism retained as one documented domain rather than the headline. That is a change of emphasis and vocabulary, not of data in itself. K6 (#68) reads the current official edition for the planning ámbito that contains a Lens centre, and K7 (#69) adds a two-edition comparison for the named 2025-07 and 2026-01 publications. K9 (#71) adds the opt-in granted urban-licence layer — an administrative address-point register read inside the Lens by licence family and grant date, where a grant is not construction. See Planning-ámbito evidence V1 and Official edition change detection V1. The spatial lens itself solves a real problem the next direction keeps: static maps force you to look at a whole city at once, or at one predefined zone, while the lens lets you ask a local, comparative question — "what is represented within this exact spatial window, given the evidence currently loaded?" — and move it around the map, including comparing two places at once.

3. What can the user explore?

• Move Lens A (always on) by dragging it or clicking the map.

• Enable Lens B to compare two locations side by side.

• Read the Radial Halo V3 quantitative perimeter bars around each circle: Tourism POIs at 12, Hotels & stays at 2, Mobility nodes at 6, and mean HATI UTCI at 9 o'clock. Each bar points outward and prints its own raw value, and for the three count metrics its length is that lens's density (count per km²) relative to a fixed Madrid reference, so the map shows which lens is denser — comparably even when the two lenses have different radii, in single-lens and Compare mode. Bar lengths compare within a metric only, never across metrics. The panel Focusing a metric highlights that same slot on both lenses and its comparison row. The panel stays authoritative for exact values, provenance and interpretation; Pedestrian activity is panel-only. See docs/radial-halo-v3.md.

• Use the Comparison Bridge in the Lens A ↔ Lens B panel: focus (hover / keyboard) or lock (click / Enter) one of the four canonical metrics — from a halo mark or from the metric name in the table — to read Lens A, Lens B and the observed B − A in one place, with both radii shown. Unequal windows compare by represented-record density or are explicitly withheld (e.g. mobility under different window sizes); zero, N/A and OFF stay distinct and never become a delta. It is a focused reading, not a score or ranking. See docs/COMPARISON_BRIDGE_V1.md.

• Check spatial sensitivity of that reading: freeze the current comparison as a baseline window, then change the Lens radii to make the live configuration a scenario window. Each canonical metric reports whether its relationship stayed the same, changed B − A direction, changed comparison basis (raw counts → represented-record density, where the numeric change is withheld because the two are not comparable), became withheld (mobility under different window sizes) or became available. Changing a radius changes which geography each Lens includes — it is not a forecast and not a causal effect, and there is no score or ranking. Moving a Lens centre or changing the evidence configuration invalidates the baseline rather than posing as radius sensitivity. See .

4. Which datasets are used?

• Museums and tourist information — Madrid Open Data
• Accommodation — Madrid Destino / esmadrid.com accommodation catalogue (tourism listings, not an administrative register), including its published accommodation type/category fields when present
• BiciMAD — EMT Madrid open data
• Metro & Cercanías stations — CRTM open data (M4 and M5 station layers)
• Permanent pedestrian counters — Madrid Open Data, observed activity evidence
• Principal municipal parks and gardens — Madrid Open Data, context only
• HATI-Madrid outdoor UTCI samples — a bounded research evidence layer (see below)
• Administrative geography (21 districts, 131 barrios) — Ayuntamiento de Madrid / IDEAM, the canonical join target for administrative context
• Registered residents per barrio — Ayuntamiento de Madrid, Subdirección General de Estadística (Padrón Municipal), reference date 1 January 2026
• Hospitality & Commercial Context — Ayuntamiento de Madrid, Censo de Locales, pinned Locales and Actividades snapshots for September 2026. The production sidecar contains only municipality/district/barrio aggregates for the four Gate F production candidates and the one conditional per-resident candidate. These are administratively documented premises, not verified operating businesses; the conditional indicator keeps the separate 1 January 2026 Padrón date visible and is not a tourism-pressure measure. Full contract: docs/HOSPITALITY_COMMERCIAL_METHOD_GATE.md.
• Licensed tourist-dwelling (VUT) activity licences per barrio — Ayuntamiento de Madrid, Agencia de Actividades (dataset 300694). A committed administrative snapshot of granted licences: 1,025 licences covering 1,483 tourist-dwelling units across the 131 barrios. The source declares no reference date, so the interface reports the resource file's observed state (September 2026) and never calls it a reference date
• Official planning ámbitos (724 polygons with their exact official codes) — Ayuntamiento de Madrid, DG de Planeamiento, through the Geoportal-catalogued planning WFS, under the municipality's general reuse conditions with attribution. Geometry and identifier only: no quantity is taken from it, and the publisher declares no date for it
• Published ámbito development state and available buildability — Ayuntamiento de Madrid, DG de Planificación Estratégica, datasets and (CC BY 4.0). K6 reads each current edition by its source-stated date. K7 compares only the named 2025-07 and 2026-01 editions within their current schema eras. The row-preserving method and reconciliation are documented in . No dwelling count or overall stage is derived

On GitHub Pages, operational POI layers are deployment-snapshot first so the map renders immediately and does not wait on cross-origin APIs. The latest successful public-source snapshot is generated during the Pages build. A small curated repository sample is the final packaged fallback where a deployment source is unavailable. Direct live requests are only attempted when no packaged data exists. No coordinates are invented. See docs/DATA_PROVENANCE.md.

5. What is HATI's role?

HATI-Madrid is a separate, independent research repository studying heat exposure at 28 tourism-relevant assets in central Madrid. This project reads 14 of its outdoor assets' UTCI values (one modelled pilot day, three times of day) in a read-only, provenance-labelled way — it never modifies HATI, never extrapolates its values beyond the sampled points, and never carries forward HATI's own feasibility/recommendation labels. Full extraction details, including the exact source commit, are in data/hati_provenance.json.

6. What does the project NOT claim?

It does not establish tourist pressure, overtourism, carrying capacity, tourist behaviour, tourist-specific footfall, safety outcomes, tourism quality, economic impact, causal heat effects, real-time conditions, city-wide HATI coverage, or a complete inventory of Madrid green space. The hotel-demand series is not total tourism demand, not all accommodation and not a count of unique visitors, and nothing explains why a figure moved. Full list in docs/CLAIMS_AND_LIMITATIONS.md.

The Radial Halo V3 makes the Lens itself a compact quantitative display. Its screen-space bars attach just outside, but do not enlarge, the analytical Lens boundary, and follow it through pan, zoom, radius and Compare-mode changes. The printed number is always the raw count inside the Lens (12, 1,284, or 31.6°C for UTCI). For the three count metrics the bar length is a density — clamp((rawCount / circleAreaKm2(radius)) / referenceDensity, 0..1) — against a deterministic Madrid reference density (the p95 of per-feature local density in a fixed 900 m window); UTCI's bar is the mean's position in a model-derived Celsius band and is never area-normalized. Encoding density (not a raw count) keeps unequal A/B radii comparable: a bigger window no longer buys a longer bar, and counts that scale with area give equal bars. The same reference density drives Lens A and Lens B, and the identical rule applies in single-lens, equal-radius and unequal-radius modes. Bar lengths are comparable within a metric only, never across metrics. The circle boundary is quieter than the bars; A and B differ by hue and structure (B's fill is dashed). Densities above the reference saturate the bar while the raw number keeps its real magnitude. Exact values stay panel-authoritative; the scale is not a Madrid benchmark, percentage, score, or ranking. Unavailable data reads N/A, off reads OFF, both distinct from a genuine observed 0. Full contract: docs/radial-halo-v3.md.

7. How do I run it locally?

No build step, no dependencies. Any static file server works:

python3 -m http.server 8000
# then open http://localhost:8000

8. How do I deploy it?

A GitHub Actions workflow (.github/workflows/deploy-pages.yml) deploys the static site to GitHub Pages on every push to main. GitHub Pages must first be enabled in the repository settings (Settings → Pages → Source: GitHub Actions) — this is an admin action the repository owner needs to take once; it is not done automatically by this PR.

The CARTO basemap key is injected at deploy time from the repository secret CARTO_BASEMAP_KEY; the key is not committed to git. Because this is a browser-side static app, the deployed key is still visible to visitors, so restrict it in the CARTO Basemaps dashboard to the GitHub Pages host soroushkarahrodi79-oss.github.io.

A local checkout (or fork, or PR preview) has no CARTO key, so it renders OpenStreetMap tiles instead of CARTO Positron/Dark Matter; the base-map selector says so, logs one console warning, and exposes data-effective-provider on #basemapSelect. Account for this when measuring marker contrast, which depends on the basemap.

9. What is the evidence status?

• Museums, tourist information, BiciMAD, Metro/Cercanías and accommodation: live public data where the browser can reach it; otherwise a labelled deployment snapshot generated during the latest GitHub Pages build. The small curated sample is only the last-resort fallback.
• Observed pedestrian activity: off by default and explicitly opt-in. It is a deployment snapshot aggregated from Madrid's latest published permanent pedestrian-counter CSV (2024 published period); it is not real-time and is not tourism-specific. No interpolation is performed between counters.
• HATI thermal layer: off by default and explicitly opt-in. When enabled, it shows locked, model-derived evidence from a single historical pilot day. Lenses with zero HATI samples inside them show "No evidence", never a fabricated value.
• Destination Context (monthly hotel demand): a committed statistical snapshot verified at the deployment gate. Each observation carries the publisher's own definitive/provisional status, and months the publisher withheld stay withheld — shown as unavailable, never as zero, and never interpolated across. The browser never calls the publisher's API at runtime. This surface fails independently: if it is unavailable, the Area Profile, the Lens metrics, licensed VUT and HATI are untouched.
• Administrative geography, registered residents and licensed VUT: committed artifacts, not rebuilt when the site deploys, each verified at the deployment gate. Each keeps its own period or state and they are never shown as one: the geography publishes only a dataset version, the residents a real 1 January 2026 reference date, and the licensed-VUT source no reference date at all — for which the interface reports the resource file's observed state rather than inventing one. The hotel-demand series is the only temporal evidence, and it owns its own period: there is still no global time control, and no other surface became time-aware.

10. Decision utility

Gate G formalizes what the current product can and cannot support as a management aid. Today Lens can support three bounded descriptive questions: same-radius local comparison, whole-barrio administrative context, and municipality-wide hotel-demand monitoring. It cannot rank barrios, measure tourism pressure, infer causality, allocate citywide demand to local areas, or recommend investment/restriction/promotion from the current evidence.

See Gate G — Decision utility and next evidence increment.

11. What is next?

Gate K has closed and set the next product direction. Gates H, I and J are closed and shipped (Destination Origin Context, the spatial comparison contract and the independent-radius contract). Gate K — Madrid Urban Decision Workspace decided the product boundary: this becomes an urban development evidence lens for Madrid, with tourism retained as one documented domain rather than the organising frame. The first authorized production increment is an ámbito evidence layer at ámbito scope — official geometry, the four published development phases (Planeamiento / Gestión / Urbanización / Edificación) and remaining buildability in m² by use class — and it is gated behind Gate L (official urban-planning source contract) plus the spatial-scope and source-freshness contracts that precede it. K6 and K7 ship the bounded tabular evidence and two-edition comparison, and add no geometry history; K9 (#71) ships the opt-in granted urban-licence address-point layer, read inside the Lens by licence family and grant date (granted ≠ built; see Granted urban licences V1). The panel's reading architecture (PLACE / COMPARE / CITY modes, the scope-and-freshness rail and the evidence drawer) is described in Information architecture V2; it reorganizes existing evidence and does not add planning evidence.

• Continue hardening reproducible AOI snapshots for operational POI layers and verify exact BiciMAD coordinates against the official EMT Madrid source before any BiciMAD fallback is reintroduced.
• Add automated visual regression checks for the map UI.
• Decide, explicitly and separately, whether the Madrid Destino accommodation catalogue can ever carry a per-resident measure. It still cannot: Gate A ruled NO-GO on it, and the licensed-VUT figure that now exists uses a different, separately qualified administrative source. A catalogue-based ratio remains deliberately absent.
• Decide, as its own design and methodology question, whether the licensed-VUT figure should ever be mapped. It is deliberately a panel figure today: a choropleth would import normalisation choices, class breaks, legends and ranking implications that need their own explicit decision.
• Extend the temporal axis beyond hotels, only where a source can preserve the same discipline. The Destination Context now answers "how is hotel demand changing", which is deliberately narrower than "how is tourism changing"; closing that gap needs the tourist-apartment survey, the INE experimental VUT series or an origin/destination source, each with its own gate.

12. Project structure

index.html            entry point
css/app.css            styling
js/lens.js             pure lens geometry + POI statistics (tested)
js/radial-halo.js      pure Radial Halo V3 model: within-metric references, bar magnitudes, glyph specs (tested)
js/evidence.js          pure HATI evidence statistics (tested)
js/evidence-scope.js    pure scope & freshness contract: analytical scopes, five-field freshness (tested)
js/modes.js             pure PLACE / COMPARE / CITY mode state and transition plans (tested)
js/scope-rail.js        pure scope-and-freshness rail model, evidence-drawer records, citizen/analyst projections (tested)
js/shell-copy.js        ES/EN dictionaries for the shell, rail and drawer (tested)
js/legacy-copy.js       product-copy catalogue (ES) for surfaces built before the shared i18n layer (tested)
js/geography.js         pure administrative containment / point-in-polygon (tested)
js/area-profile.js      pure Area Profile model: place, residents, licensed VUT, states (tested)
js/destination-context.js  pure citywide hotel-demand model: period, YoY, trend, states (tested)
js/domestic-origin-context.js pure municipality-level domestic-origin model (tested)
js/extraction-bounds.js  CRTM rail extraction rectangle (single definition) + pure whole-circle Lens eligibility for the combined Mobility count (tested)
js/data.js              deployment-snapshot-first + bounded live fallback loading
js/app.js               Leaflet map + UI wiring
data/                   HATI evidence extract + POI snapshot + provenance
scripts/                source builders (geography, population, VUT, destination) + deployment validator
docs/                   methodology, data provenance, claims & limitations
tests/                  Node built-in test runner, no framework

13. License

The MIT license in LICENSE covers this repository's original code and documentation only. It does not relicense any third-party data or software this project reads or bundles:

• Leaflet (vendored in assets/leaflet/) keeps its own upstream license — see assets/leaflet/LICENSE.
• OpenStreetMap-derived references cited in HATI's own asset records remain subject to the ODbL and its attribution requirement.
• Madrid Open Data (museums, tourist information, administrative geography, registered residents, licensed VUT activity licences), Madrid Destino / esmadrid.com (accommodation), EMT Madrid open data (BiciMAD), CRTM open data (Metro/Cercanías), and Instituto Nacional de Estadística (Encuesta de Ocupación Hotelera — monthly hotel demand) remain subject to the reuse terms published by their respective portals — see datos.madrid.es, esmadrid.com, datos.emtmadrid.es, and datos.crtm.es directly; this project does not restate or assume a specific license text for them.
• HATI-Madrid evidence (data/hati_assets.json, data/hati_provenance.json) remains subject to the source repository's own terms and governance (RELEASE_LOCKED / RESEARCH_FROZEN layers) — see DATA_PROVENANCE.md.