Stats Explorer — browse and map SaanSeoi statistics

[tijptjik]

Summary

Create Stats Explorer, a dedicated public application at stats.saanseoi.hk for discovering SaanSeoi statistics and previewing selected results on a map.

It would turn the Statistics API from a powerful query interface into an approachable exploration surface: someone should be able to start with a fuzzy search such as “district population”, narrow the result by measure, dimensions, reference period and geography, then immediately see the selected field on the appropriate geography.

Why a dedicated app

The registry and Statistics API already separate catalogue discovery from data retrieval:

• The public Registry catalogue exposes API families, releases, fields, endpoints, sources, source versions and publishers (/v0.1/api/families, /releases, /fields, /endpoints, /sources, /sourceVersions, /sourcePublishers).
• The Statistics API exposes observations at /stats/v0 (and /stats/v0.1), including dataset, reference period, geography, analytical dimensions and field-keyed values.
• include=fields supplies localised field definitions; include=divisions,areas supplies the selected division and map geometry.
• /stats/v0/geographies returns one unambiguous, complete geography map for a selected field and filters; /stats/v0/series returns the comparable multi-period series.

Stats Explorer would consume these contracts directly, rather than copying a catalogue or creating an app-specific statistics store. This keeps discovery, provenance, localisation and publication state aligned with the registry.

Proposed experience

1. Search — fuzzy-match a natural-language query against curated measure/field names, definitions, dataset names and available dimension labels. Show the matching field, dataset, reference-period coverage and source/publisher context.
2. Refine — expose only meaningful filters for the candidate: measure/field, dataset, reference period, geography type and the field’s analytical dimensions (for example age band, sex or occupancy status). Treat dimensions as categorical slices, not as parts of a hidden series code.
3. Preview on map — request /stats/v0/geographies for the fully selected field and render a choropleth or proportional-symbol preview against the returned geography. Keep the selected period and dimensions visible.
4. Explain the result — show unit, definition, source/release, reference period, geography coverage, comparability notes and a copyable API URL. Link back to the Registry release, field and source records.
5. Compare over time — when the selection is comparable, offer /stats/v0/series as a small trend view and let the user change the period without silently mixing periods.

API and UX rules

• Use the Registry as the canonical discovery index; cache only as an implementation detail and invalidate from registry/catalogue revision metadata.
• Resolve a map only after the filters identify one field and one complete geography dimension. Surface the API’s 409 ambiguity response as a prompt to choose a missing dimension rather than choosing arbitrarily.
• Preserve the canonical API URL when copying or sharing a selection.
• Request fields and geometry only when needed (include=fields for labels and definitions; include=divisions,areas for a record preview).
• Respect requested locales and present provenance for every result.
• Start with published official statistics and the currently supported geography variants; do not imply that a map is available where the selected field lacks a complete, compatible geography.

Initial milestone

A useful first release could cover:

• Registry-backed search and faceted selection for published Statistics fields;
• one-map preview for an unambiguous selection;
• bilingual/trilingual field labels and source provenance;
• reference-period selector plus a basic comparable series preview;
• shareable URLs and a direct “open in API” escape hatch.

Open questions

• What should fuzzy matching prioritise: field labels, definitions, dataset names or source terminology?
• Should the default view begin with a search box, a thematic collection, or an interactive map?
• Which initial geography and statistic families best demonstrate the experience?
• Should a saved/shareable selection live entirely in the URL for the first release?

Feedback on the discovery model, first-release scope and the name stats.saanseoi.hk is welcome.