Geospatial Map Exploration

Status

Working prototype contract for the geospatial branch. The implementation is browser-only, deterministic and additive to existing OKF bundle formats.

Use the Map personas and user stories for role-based needs and acceptance traceability, and the illustrated Map manual for a practical walkthrough.

Aim

The Map canvas turns spatial metadata into another way to reduce and inspect an OKF context. It must be useful for both explicit geospatial services such as ArcGIS REST, WMS, WFS and GeoJSON and ordinary statistics or reports that name the areas they describe.

The Map does not make Explorer an online GIS. It keeps the existing operating model:

static bundle metadata loads first;
local classification, search and filtering require no AI or server;
remote resource bodies are fetched only after an explicit user action;
failed or unsupported previews retain a route back to the source;
generated packs may add richer spatial metadata without making it mandatory.

User Flow

Open Map from the canvas tabs. Large corpora hydrate their existing dataset and resource indexes; small bundles reuse their in-memory nodes.
Explorer classifies the current search/facet reduction and reports how many records have spatial evidence.
Select a place or evidence class to reduce the Map. The reduction is stored in the public URL so it can be copied and restored with Back/Forward.
Select a marker or list row to inspect the ordinary Explorer record card.
Open an external source directly, or request a bounded preview where the resource is recognisably GeoJSON or an ArcGIS feature service.
If preview discovery, CORS, response size or geometry support fails, retain the local metadata and offer the original source as the recovery path.

Evidence Levels

Classification is deliberately explainable. A record can carry more than one signal, ordered from strongest to weakest:

Geometry: explicit WGS84 coordinates, a GeoJSON geometry or a declared bounding box supplied by the pack.
Coverage: explicit fields such as area_served, areaServed, spatial, spatial_coverage, coverage or jurisdiction.
Service or file: a resource URL, format or protocol identifies ArcGIS REST, OGC API Features, WMS, WFS, WMTS, WCS, GeoJSON, KML, GML, Shapefile or GeoPackage.
Text: title, description, topics or tags contain a bounded spatial term or a recognised UK nation/region.

Evidence is a discovery aid, not an assertion that a dataset is current, authoritative or geometrically complete. Place matches without geometry appear at labelled representative centroids and never as inferred boundaries.

Deterministic Geography Vocabulary

The prototype recognises the UK, Great Britain, the four UK nations, the nine English regions and a small set of common aliases. Matching uses token boundaries and pack-supplied fields before prose. The implementation keeps the matched source value and rule so the UI can explain every classification.

Pack builders should prefer stable identifiers and explicit metadata over place-name guessing:

{
  "spatial": {
    "geographies": [
      {
        "code": "E12000007",
        "name": "London",
        "level": "region",
        "source": "ONS",
        "vintage": "2025"
      }
    ],
    "bbox": [-0.5103, 51.2868, 0.334, 51.6919],
    "crs": "EPSG:4326",
    "derivation": "source-declared"
  }
}

When builders publish boundaries or postcode/UPRN lookups they should preserve the source, release or epoch, geography-code family, exact/best-fit derivation, boundary variant and CRS. For UK web-map output, WGS84 (EPSG:4326) is the display CRS; a pack may retain British National Grid (EPSG:27700) as its analysis CRS.

Progressive Recovery

The preview ladder is intentionally narrow:

render geometry already present in the pack;
fetch a direct JSON/GeoJSON resource with a response-size limit;
for an ArcGIS FeatureServer or MapServer, inspect service metadata, pick the first declared feature layer and request a capped GeoJSON query;
if a browser cannot fetch or understand the response, explain the reason and keep an Open source link;
never insert credentials, probe private services or silently retry through an unrelated proxy.

WMS, WFS, WMTS, WCS, KML, GML, Shapefile and GeoPackage remain discoverable and filterable in this prototype. Their external source is linked on demand, but their bodies are not parsed in-browser yet.

Performance And Safety Boundaries

No map library, tile service or geocoder is needed for initial display.
Classification is linear in the records already hydrated for the current view and is cached by Svelte's derived state.
The locator map groups coincident representative points and caps visible labels/rows.
Remote previews are user-triggered, JSON-only, bounded to 10 MiB by the existing source fetcher and capped to 100 ArcGIS features.
External links open in a new tab and never replace Explorer state.
No API keys, access tokens or secret values belong in the bundle or URL.

Prototype Acceptance Criteria

Map is a first-class view for both small and large bundles.
Large-corpus Map starts from the same search and facet reduction as every other view.
Selecting a geography or evidence class reduces the mapped set and survives copied URLs and browser navigation.
ArcGIS/OGC/file signals are detected from both records and resources.
Every marker/list row selects the corresponding ordinary Explorer record.
Direct GeoJSON and ArcGIS feature services have a bounded, explicit preview path with visible provenance and failure recovery.
Unit tests cover signal classification, place matching, coordinate handling, URL reduction state and preview URL generation.

Later Pack-Builder Work

This branch keeps the Explorer backward-compatible. A follow-on builder change can add a small okf-geospatial-index.v1 sidecar with record routes, GSS codes, coverage labels, coordinate/bbox summaries, evidence class, CRS, vintage and resource references. That would let very large packs show a useful Map overview without hydrating every dataset/resource chunk, while retaining the same UI and evidence rules prototyped here.