Docs index
Data Layer Reference

Asset / Operator History Snapshot

Status: Planned Issue: #151Bundle: Energy Bundle (gated behind metadata.energy_bundle = true on Business plans).

Asset / Operator History Snapshot

Status: Planned Issue: #151Bundle: Energy Bundle (gated behind metadata.energy_bundle = true on Business plans).

Goal

Surface the operator chain-of-custody for any AER-licensed well or facility: who originally licensed it, who holds it now, what transfers happened in between, and when. Lets surface-rights owners, due-diligence teams, and field operators see the history of an asset without cross-referencing the AER's well-transfer notices manually.

What ships

A snapshot view, not a continuous timeline. For a given UWI:

  • Current licensee (operator name, BA code, status)
  • Most recent transfer date and counterparty
  • Total transfer count over the well's lifetime
  • Original licensee at spud
  • Most recent change of well status (e.g., issued → suspension)

Pushed deeper history (full ownership ledger) requires the paid Petrinex feed and is out of scope for this snapshot. The free-data path is the AER's public well-transfer notices archive plus the ST37 dataset already in app.aer_wells.

Data sources

SourceCoverageFormat
AER ST37 (existing app.aer_wells table)Current licensee, current statusalready ingested
AER Well Transfer Notices (public archive)Per-transfer event log by UWIweekly PDF / scrape
AER Business Associate (BA) lookupOperator name + BA code resolutionopen data

The transfer notices archive is the gap to fill — it requires a parser for the weekly PDF or a scrape of the BA tools. Once landed in app.aer_well_transfers, the snapshot view is straightforward.

API surface

A single endpoint that takes a UWI and returns the snapshot:

GET /api/wells/:uwi/history
→ {
    current_licensee: { name, ba_code, since },
    original_licensee: { name, ba_code, spud_date },
    transfer_count: 4,
    most_recent_transfer: { from, to, date, transfer_number },
    most_recent_status_change: { from_status, to_status, effective_date }
  }

The existing GET /api/wells/[uwi] endpoint already serves the current well row; the history endpoint extends that with the transfer chain.

UI

A new panel on the well-detail surface (alongside the existing UWI + LSD + status block) that renders the snapshot. The Vue component lives in app/components/wells/AssetHistory.vue (TBD) and is rendered only when the user's subscription includes the Energy Bundle entitlement.

Acceptance criteria progress

  • app.aer_well_transfers schema (migration in server/database/migrations/)
  • Weekly transfer-notices ingestion cron (server/api/cron/aer-transfers-refresh.js)
  • BA lookup join table (or live API call against AER BA endpoint)
  • GET /api/wells/[uwi]/history endpoint behind requireEnergyBundle(event)
  • UI panel in well-detail view (Energy Bundle subscribers only)
  • Operator-level rollup query (used by the Territory & Prospecting tool downstream)

Related layers