VEN — DATA SOURCE & API INVENTORY

Every stream, snapshot, and endpoint feeding the TLALOCORBIS water-energy map for British Columbia

This document enumerates the full data surface behind tlalocorbis.ca: every upstream provider whose data is ingested, the live telemetry stream polled by scheduled job, the derived PostgreSQL tables, the internal FastAPI surface consumed by the frontend, and the runtime external dependencies. Last verified: 2026-04-22.

Upstream sources

Live stream (hourly)

Internal API routers

Postgres / PostGIS tables

15,821

Candidate sites mapped

~1.0 M

Realtime readings

Tier 1 · Upstream authoritative sources (13)

Federal government — Canada

#	Source	Endpoint / fetch mode	Feeds
1	HYDAT — Water Survey of Canada (historical)	local SQLite `data/Hydat.sqlite3` from government quarterly release	2,324 BC river stations
2	WSC Real-time Hydrometric API	`api.weather.gc.ca/collections/hydrometric-realtime/items` · live · hourly cron	996,384 readings · 449 gauges
3	HRDEM / GEO.CA elevation	`datacube.services.geo.ca/ows/elevation` (WCS)	Head inference · 1,001 cached points
4	NRCAN Hydrospatial CHN / RHC	FTP zip `ftp.maps.canada.ca/pub/nrcan_rncan/.../chn_rhc_01BC000.zip`	172,013 BC flowline segments
5	NPRI — Water Releases 2023	CSV snapshot	~5,800 industrial dischargers
6	Open-Elevation (fallback)	`api.open-elevation.com/api/v1/lookup`	Elevation fallback when HRDEM unavailable

Provincial — British Columbia

#	Source	Endpoint / fetch mode	Feeds
7	BC Freshwater Atlas (streams + falls)	WFS `openmaps.gov.bc.ca/geo/ows`	172K streams · FWA falls layer
8	BC WRIS Dams	GeoJSON snapshot	2,467 licensed dams
9	BCER — short-term water use	GeoJSON snapshot	~237 oil/gas water permits
10	BC Geographic Names	Waterfalls enrichment layer	Name enrichment for 4,874 falls

Municipal — six utilities via ArcGIS FeatureServer REST

#	Utility	Endpoint	Layer
11a	Vancouver Open Data	`opendata.vancouver.ca`	Pressure zones · water mains · PRV proxy
11b	Surrey Open Data	`gisservices.surrey.ca/arcgis/…/OpenData/MapServer`	Layer 52 (PRVs)
11c	Coquitlam	`geodata.coquitlam.ca/arcgis/…/DynamicServices/Water/MapServer`	Layer 0
11d	District of North Vancouver	`geoweb.dnv.org/data/` shapefile	PRV features
11e	Port Coquitlam	`maps.portcoquitlam.ca/server/rest/…/UtilityNetworks/MapServer`	Layer 36
11f	Township of Langley	`mapsvr.tol.ca/arcgisext02/…/DynamicServices/MapServer`	Layer 188 (parcel-aggregated)

Community / open web

#	Source	Endpoint	Feeds
12	OpenStreetMap Overpass	`overpass-api.de/api/interpreter`	869 water infra features · OSM waterfalls
13	Wikipedia (waterfalls page parsing)	MediaWiki	~180 high-quality named falls

Curated snapshots (not live APIs, but upstream authoritative)

Metro Vancouver public reports — hand-curated from published annual reports. 5 WWTP outfall sites (Iona, Annacis, Lions Gate, Lulu, Northwest Langley).

Canadian Hydrographic Service — tide & current tabulated atlases. 6 narrows hand-encoded from published tables (Seymour Narrows, Skookumchuck, and others).

Tier 2 · Live telemetry — the only hot stream

A single scheduled job keeps the platform's live signal fresh:

0 * * * *  /home/sudo-claude/aquaorbis/scripts/cron_realtime.sh
           → fetch_realtime.py
           → api.weather.gc.ca (WSC Real-time)
           → upserts into realtime_readings

Last run: 200,000 upserts from 447 stations in 183.7 s at 2026-04-22 21:03 UTC. Table freshness spans 2026-04-14 → 2026-04-22 across 449 distinct stations. Every other ingest (scripts/ingest_*.py, fetch_*.py — nine scripts total) is a snapshot run on demand when upstream publishes.

Tier 3 · Derived / internal tables (25)

Primary node tables (7 categories · 15,821 nodes): stations, outfalls, tidal_narrows, dams, waterfalls, industrial_discharges, prv_candidates
Hydrology: hydrospatial_flowlines (172K), flowline_nodes (174K), drainage_basins
Infrastructure: osm_infrastructure (869), pressure_zones (108)
Time series: realtime_readings (~1 M, growing hourly)
Caches / derived: elevation_cache (1K HRDEM results)
Workflow: users, crews, crew_members, actions_log, surveys, work_orders, views
Housekeeping: schema_migrations, geometry_columns, geography_columns, spatial_ref_sys

Tier 4 · Internal API surface — 19 routers

Router	Primary endpoints
main.py	`/api/health`, `/api/fleet-stats`, `/api/stations`, `/api/outfalls`, `/api/tidal`, `/api/pressure-zones`, `/api/water-mains`
nodes	`/api/nodes` (unified 7-type), `/api/prvs`
dams	`/api/dams` (GeoJSON)
waterfalls	`/api/waterfalls`
industrial	`/api/industrial`
pressure_zones_v2	`/api/pressure-zones-v2` (HGL-modeled, 6 munis)
pipe_pressure	`/api/pipe-pressure` (17 water mains with per-pipe drops)
flowlines	`/api/flowlines` (BC FWA streams)
infrastructure	`/api/osm-infrastructure`
elevation	`/api/elevation` (HRDEM proxy / cache)
realtime	`/api/realtime/{station_id}` (48h window)
seasonal	`/api/seasonal/{station_id}` (12-mo climatology)
reports	`/api/reports/{node_id}` (PDF site assessment)
export	`/api/export/json`, `/api/export/geojson`
actions	`/api/actions` (lifecycle events)
auth	`/api/auth/magic-link`, `/api/auth/verify` (JWT magic-link)
views	`/api/views` (saved filter states)
aip	`/api/aip/translate`, `/api/aip/health` (NL → filter via LLM chain)
websocket	`wss://tlalocorbis.ca/api/ws/live` (real-time action broadcast)

Tier 5 · Runtime external dependencies

#	Service	Purpose	Load pattern
A	Mapbox Vector Tiles (`mapbox://styles/mapbox/dark-v10`)	Primary basemap	Every page load · client-side
B	CartoCDN Dark Matter (`basemaps.cartocdn.com`)	Fallback basemap (no Mapbox token)	Only when token missing
C	Google Fonts (`fonts.googleapis.com`)	DM Sans + JetBrains Mono	Every page load
D	Mothership LiteLLM proxy (`aquaorbis-llm.carranzas.io/v1`)	AIP natural-language filter · Qwen 3.6 `thinker-new`	Per-query · currently blocked by TLS cert SAN scope

Summary

13 upstream data sources: 6 federal, 4 provincial, 6 municipal, 2 community, plus 2 non-API curated (Metro Van WWTP + CHS tidal).
1 live telemetry stream running hourly — WSC real-time → 449 gauges → ~1 M readings.
19 backend API routers composing the unified surface consumed by the frontend.
25 PostgreSQL + PostGIS tables holding the derived intelligence.
4 external runtime dependencies: Mapbox, Carto fallback, Google Fonts, Mothership LLM proxy.

The only live-polling signal today is WSC river discharge. Everything else — dams, waterfalls, PRVs, outfalls, industrial, tidal, pressure zones, OSM pipes — is a snapshot ingestion. Additional live streams (tide gauges in-session, municipal SCADA, NPRI monthly updates) are adds, not a rewrite.