@rcpch/imd-map 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -8,6 +8,28 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-04-28
+
+### Added
+
+- Optional tile API key support via `tilesApiKey` and `tilesApiKeyParam` options in `CreateImdMapOptions`.
+- Tile API key query parameters are appended to all choropleth and boundary overlay tile requests.
+- Customizable query parameter name for tile auth (defaults to `api_key`).
+- Unit test coverage for tile URL builder with optional auth and auth propagation across overlays.
+
+### Documentation
+
+- Updated README runtime tile configuration section with tile auth options and example usage.
+- Added note that browser-delivered keys are non-secret and primarily useful for operational traffic control (rate limiting, revocation, origin restrictions).
+
+## [0.3.0] — 2026-04-27
+
+### Changed
+
+- Updated all-UK era resolution so `initialNation: 'all'` honours the requested era instead of always forcing `2011`.
+- Documented the mixed-vintage `uk_master_2021_*` UK tiles, where England uses 2021 LSOA boundaries with 2025 IMD data while Wales, Scotland, and Northern Ireland remain on their current older datasets.
+- Clarified in the public docs that `era` refers to the LSOA boundary year, not the IMD publication year, and documented the England pairings of `2011` → 2011 LSOAs + 2019 IMD and `2021` → 2021 LSOAs + 2025 IMD.
+
 ## [0.2.0] — 2026-04-26
 
 ### Changed

package/README.md

@@ -69,7 +69,7 @@ The UMD bundle includes MapLibre GL. No separate script tag required.
 ```html
 <div id="map" style="height: 600px"></div>
 
-<script src="https://cdn.jsdelivr.net/npm/@rcpch/imd-map@0.1.0/dist/umd/rcpch-imd-map.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@rcpch/imd-map@0.3.0/dist/umd/rcpch-imd-map.min.js"></script>
 <script>
   const map = RcpchImdMap.createImdMap({
     container: 'map',
@@ -201,6 +201,24 @@ Tile URL resolution precedence:
 
 The library source contains **no hardcoded tile URLs**.
 
+Optional tile auth query options:
+
+- `tilesApiKey`: appends a query value to all choropleth and overlay tile requests
+- `tilesApiKeyParam`: query parameter name for `tilesApiKey` (default: `api_key`)
+
+Example:
+
+```js
+createImdMap({
+  container: 'map',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  tilesApiKey: 'switchable-browser-token',
+  tilesApiKeyParam: 'key',
+});
+```
+
+This is useful for revoking abusive traffic quickly, but browser-delivered keys must still be treated as non-secret.
+
 ### Overlay boundary tile contract
 
 Boundary overlays (local authority, NHSER, ICB, LHB) are requested from schema-qualified table ids and rendered with the same schema-qualified `source-layer` name. Example:
@@ -216,9 +234,16 @@ Bring your own overlay configuration (custom overlay table/layer names via libra
 
 ## Nation and era rules
 
+The `era` option refers to the boundary year used for the LSOA geography, not the IMD publication year.
+
+For England, the supported pairings are:
+
+- `2011` era = 2011 LSOA boundaries + 2019 IMD data
+- `2021` era = 2021 LSOA boundaries + 2025 IMD data
+
 | Nation | Requested era | Effective era |
 |---|---|---|
-| `all` | any | always `2011` |
+| `all` | `2011` or `2021` | as requested |
 | `england` | `2011` or `2021` | as requested |
 | `wales` | any | always `2011` |
 | `scotland` | any | always `2011` |
@@ -226,6 +251,31 @@ Bring your own overlay configuration (custom overlay table/layer names via libra
 
 When the effective era differs from the requested era, `onWarning` is called with code `ERA_OVERRIDE`.
 
+For all-UK maps, `initialEra: '2021'` now uses the mixed-vintage `uk_master_2021_*` tables: England renders with 2021 LSOA boundaries and 2025 IMD data, while Wales, Scotland, and Northern Ireland continue to render from their existing older datasets within the same UK tile family. Use `initialEra: '2011'` when you want the older England 2011 LSOA + 2019 IMD view alongside the existing Welsh and other nation data.
+
+This means you can instantiate two separate UK maps in the same application, choosing the England boundary/IMD pairing by era:
+
+```js
+const historicalMap = createImdMap({
+  container: 'map-2011',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  initialNation: 'all',
+  initialEra: '2011',
+});
+
+const currentMap = createImdMap({
+  container: 'map-2021',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  initialNation: 'all',
+  initialEra: '2021',
+});
+```
+
+In a patient-facing application, a common pattern would be:
+
+- patients before 2025 or 2026 cutoff: `initialEra: '2011'`
+- patients in the newer cohort: `initialEra: '2021'`
+
 ---
 
 ## Styling
@@ -375,6 +425,8 @@ map.setStyle({ tooltip: { areaLabel: 'Local area' } });
 |---|---|---|---|
 | `container` | `string \| HTMLElement` | — | DOM element ID or element reference |
 | `tilesBaseUrl` | `string` | — | Base URL of the tile server |
+| `tilesApiKey` | `string` | — | Optional API key appended to tile URLs as a query parameter |
+| `tilesApiKeyParam` | `string` | `'api_key'` | Query parameter name used for `tilesApiKey` |
 | `initialNation` | `Nation` | `'all'` | Starting nation filter |
 | `initialEra` | `Era` | `'2021'` | Requested era (may be overridden) |
 | `enableLocalAuthorityOverlay` | `boolean` | `false` | Show local authority boundary overlay at startup |

package/dist/index.d.ts

@@ -183,6 +183,10 @@ interface CreateImdMapOptions {
     container: string | HTMLElement;
     /** Base URL of the tile server. Required for choropleth rendering. */
     tilesBaseUrl?: string;
+    /** Optional API key appended to tile URLs as a query string parameter. */
+    tilesApiKey?: string;
+    /** Query parameter name used for tilesApiKey. Default: api_key. */
+    tilesApiKeyParam?: string;
     initialNation?: Nation;
     initialEra?: Era;
     showDefaultControls?: boolean;

package/dist/index.esm.js

@@ -6,7 +6,7 @@ import { Map, AttributionControl, Popup, VectorTileSource, GeoJSONSource } from
 function resolveEffectiveEra(nation, requestedEra) {
   switch (nation) {
     case "all":
-      return "2011";
+      return requestedEra;
     case "england":
       return requestedEra;
     case "wales":
@@ -29,9 +29,13 @@ var ZOOM_TIERS = [
 function resolveFullTableName(effectiveEra, tier) {
   return `public.uk_master_${effectiveEra}_${tier}`;
 }
-function buildTileUrl(tilesBaseUrl, fullTableName) {
+function buildTileUrl(tilesBaseUrl, fullTableName, auth) {
   const base = tilesBaseUrl.replace(/\/$/, "");
-  return `${base}/${fullTableName}/{z}/{x}/{y}.pbf`;
+  const tileUrl = `${base}/${fullTableName}/{z}/{x}/{y}.pbf`;
+  if (!auth?.apiKey) return tileUrl;
+  const paramName = auth.apiKeyParam?.trim() || "api_key";
+  const separator = tileUrl.includes("?") ? "&" : "?";
+  return `${tileUrl}${separator}${encodeURIComponent(paramName)}=${encodeURIComponent(auth.apiKey)}`;
 }
 function resolveNationFilter(nation) {
   if (nation === "all") return null;
@@ -60,11 +64,11 @@ function choroplethSourceId(tier) {
 ZOOM_TIERS.map((t) => choroplethSourceId(t.tier));
 var PATIENTS_SOURCE_ID = "rcpch-imd-patients";
 var LEAD_CENTRE_SOURCE_ID = "rcpch-imd-lead-centre";
-function addOrUpdateChoroplethSources(map, tilesBaseUrl, effectiveEra) {
+function addOrUpdateChoroplethSources(map, tilesBaseUrl, effectiveEra, tileAuth) {
   for (const { tier } of ZOOM_TIERS) {
     const sourceId = choroplethSourceId(tier);
     const fullTableName = resolveFullTableName(effectiveEra, tier);
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -899,13 +903,13 @@ function localAuthoritySourceId(tier) {
 function localAuthorityLayerId(tier) {
   return `${LOCAL_AUTHORITY_LAYER_ID}-${tier}`;
 }
-function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style) {
+function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style, tileAuth) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = localAuthoritySourceId(tier);
     const layerId = localAuthorityLayerId(tier);
     const fullTableName = buildMvtLayerName(LOCAL_AUTHORITY_TABLE_PREFIX, tier);
     const sourceLayer = fullTableName;
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -972,13 +976,13 @@ function overlaySourceId(baseSourceId, tier) {
 function overlayLayerId(baseLayerId, tier) {
   return `${baseLayerId}-${tier}`;
 }
-function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
+function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, input) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = overlaySourceId(input.sourceId, tier);
     const layerId = overlayLayerId(input.layerId, tier);
     const fullTableName = buildMvtLayerName(input.tablePrefix, tier);
     const sourceLayer = fullTableName;
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -1014,8 +1018,8 @@ function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
     });
   }
 }
-function addOrUpdateNhserOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateNhserOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: NHSER_SOURCE_ID,
     layerId: NHSER_LAYER_ID,
     tablePrefix: NHSER_TABLE_PREFIX,
@@ -1023,8 +1027,8 @@ function addOrUpdateNhserOverlay(map, tilesBaseUrl, style) {
     lineWidth: style.boundaries.nhserWidth ?? 1.5
   });
 }
-function addOrUpdateIcbOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateIcbOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: ICB_SOURCE_ID,
     layerId: ICB_LAYER_ID,
     tablePrefix: ICB_TABLE_PREFIX,
@@ -1032,8 +1036,8 @@ function addOrUpdateIcbOverlay(map, tilesBaseUrl, style) {
     lineWidth: style.boundaries.icbWidth ?? 1
   });
 }
-function addOrUpdateLhbOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateLhbOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: LHB_SOURCE_ID,
     layerId: LHB_LAYER_ID,
     tablePrefix: LHB_TABLE_PREFIX,
@@ -1377,6 +1381,10 @@ function createImdMap(options) {
   if (!tilesBaseUrl) {
     logger.warn("No tilesBaseUrl provided. Choropleth tiles will not load.");
   }
+  const tileAuth = {
+    apiKey: options.tilesApiKey,
+    apiKeyParam: options.tilesApiKeyParam
+  };
   let resolvedStyle = mergeStyle(DEFAULT_STYLE, options.style);
   let state = createInitialState(options.initialNation ?? "all", options.initialEra ?? "2021");
   if (options.enableLocalAuthorityOverlay) {
@@ -1473,22 +1481,22 @@ function createImdMap(options) {
     const canShowIcb = nation === "all" || nation === "england";
     const canShowLhb = nation === "all" || nation === "wales";
     if (state.overlays.localAuthority) {
-      addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideLocalAuthorityOverlay(map);
     }
     if (state.overlays.nhser && canShowNhser) {
-      addOrUpdateNhserOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateNhserOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideNhserOverlay(map);
     }
     if (state.overlays.icb && canShowIcb) {
-      addOrUpdateIcbOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateIcbOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideIcbOverlay(map);
     }
     if (state.overlays.lhb && canShowLhb) {
-      addOrUpdateLhbOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateLhbOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideLhbOverlay(map);
     }
@@ -1522,10 +1530,13 @@ function createImdMap(options) {
     });
   }
   logger.debug(`tilesBaseUrl resolved to: "${tilesBaseUrl}"`);
+  if (tileAuth.apiKey) {
+    logger.debug("Tile API key is configured for tile URL requests.");
+  }
   map.on("load", () => {
     mapLoaded = true;
     if (tilesBaseUrl) {
-      addOrUpdateChoroplethSources(map, tilesBaseUrl, state.effectiveEra);
+      addOrUpdateChoroplethSources(map, tilesBaseUrl, state.effectiveEra, tileAuth);
       addChoroplethLayers(map, state.nation, state.effectiveEra, resolvedStyle);
     }
     applyOverlayVisibility();
@@ -1576,7 +1587,7 @@ function createImdMap(options) {
     if (mapLoaded && tilesBaseUrl) {
       if (eraChanged) {
         removeChoroplethLayers(map);
-        addOrUpdateChoroplethSources(map, tilesBaseUrl, newEffectiveEra);
+        addOrUpdateChoroplethSources(map, tilesBaseUrl, newEffectiveEra, tileAuth);
         addChoroplethLayers(map, newNation, newEffectiveEra, resolvedStyle);
       } else if (nationChanged) {
         updateChoroplethNationFilter(map, newNation);