REST API v1

Energy

Query wells, pipelines, facilities, operators and tenure, and render energy map layers.

On this page

Energy Parcel Reports

Wells, pipelines, facilities, production, and Crown tenure for any LSD in AB, SK, and MB.

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/report" \
  -H "X-API-Key: $TOWNSHIP_API_KEY" \
  --data-urlencode "legal_location=7-10-13-9-W4"

Parameters

Name	Type	Required	Description
legal_location	string	Required	Legal Subdivision (LSD) `7-10-13-9-W4`
include	string	Optional	Comma-separated sections to return (omit for the full report). Only the requested sections are queried. geometry attaches the parcel polygon `summary,productionsummary` , `production` , `tenure` , `wells` , `pipelines` , `facilities` , `alternative_energy` , `geometry`

Example Response

response.json

{
  "legal_location": "7-10-13-9-W4",
  "province": "AB",
  "parcel": { "area_ha": 16.19, "centroid": { "lat": 50.06, "lng": -111.12 }, "geometry": null },
  "summary": {
    "wells": {
      "total": 3, "active": 1, "suspended": 0, "abandoned": 2, "orphan": 0,
      "reclamation_certified": 0, "primary_source": "regulator", "by_source": { "...": "..." }
    },
    "pipelines": { "segment_count": 2, "length_m_on_parcel": 1400 },
    "facilities": { "count": 1, "categories": ["Battery"] },
    "operators": { "dominant": { "name": "EXAMPLE ENERGY LTD", "ba_code": "0AB1", "slug": "example-energy-ltd" } },
    "last_activity_date": "2025-11-01"
  },
  "production": {
    "window_months": 12,
    "last_producing_month": "2026-06",
    "volumes": { "oil_m3": 1250.5, "gas_e3m3": 0, "condensate_m3": 0, "water_m3": 3100.0 },
    "has_oil": true, "has_gas": false, "has_condensate": false, "has_water": true,
    "dominant_product": "oil",
    "producing_well_count": 1
  },
  "tenure": { "total": 1, "returned": 1, "truncated": false, "more": "/energy/tenure?legal_location=7-10-13-9-W4", "rows": [{ "...": "..." }] },
  "wells": { "total": 3, "returned": 3, "truncated": false, "more": "/energy/wells?legal_location=7-10-13-9-W4", "rows": [{ "...": "..." }] },
  "pipelines": { "total": 2, "returned": 2, "truncated": false, "more": "/energy/pipelines?legal_location=7-10-13-9-W4", "rows": [{ "...": "..." }] },
  "facilities": { "total": 1, "returned": 1, "truncated": false, "more": "/energy/facilities?legal_location=7-10-13-9-W4", "rows": [{ "...": "..." }] },
  "alternative_energy": null,
  "units": { "length": "m", "area": "ha", "depth": "m", "pressure": "kPa", "oil": "m3", "gas": "e3m3" },
  "meta": { "unavailable": [], "sources": { "...": "..." } }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/wells" \
  -H "X-API-Key: $TOWNSHIP_API_KEY" \
  --data-urlencode "legal_location=7-10-13-9-W4"

Parameters

Name	Type	Required	Description
legal_location	string	Required	Legal Subdivision (LSD) `7-10-13-9-W4`
status	string	Optional	Derived well state `active` , `abandoned` , `suspended` , `orphan`
operator	string	Optional	Operator name substring (case-insensitive)
sort	string	Optional	Sort key (default: status) `id` , `status` , `operator` , `depth`
dir	string	Optional	Sort direction `asc` , `desc`
page	integer	Optional	1-based page number (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "legal_location": "7-10-13-9-W4",
  "province": "AB",
  "rows": [
    {
      "id": "100071013009W400",
      "uwi": "100071013009W400",
      "well_name": "EXAMPLE 7-10",
      "licence_number": "0400001",
      "status": "active",
      "licence_status_raw": "Issued",
      "operator": { "name": "EXAMPLE ENERGY LTD", "ba_code": "0AB1", "slug": "example-energy-ltd" },
      "fluid": "crude_oil",
      "mode": "pumping",
      "type": "development",
      "total_depth_m": 1650,
      "is_orphan": false, "is_abandoned": false, "is_suspended": false,
      "location": { "lat": 50.06, "lng": -111.12 }
    }
  ],
  "meta": { "total": 214, "page": 1, "per_page": 50, "sort": "status", "dir": "asc", "status": null, "operator": null }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/pipelines" \
  -H "X-API-Key: $TOWNSHIP_API_KEY" \
  --data-urlencode "legal_location=7-10-13-9-W4"

Parameters

Name	Type	Required	Description
legal_location	string	Required	Legal Subdivision (LSD) `7-10-13-9-W4`
substance	string	Optional	Substance substring (case-insensitive)
status	string	Optional	Segment status (exact, case-insensitive)
operator	string	Optional	Operator company name substring (case-insensitive)
sort	string	Optional	Sort key (default: h2s descending, the safety-first ordering) `id` , `length` , `h2s`
dir	string	Optional	Sort direction `asc` , `desc`
page	integer	Optional	1-based page number (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "legal_location": "7-10-13-9-W4",
  "province": "AB",
  "rows": [
    {
      "id": "12345-1",
      "href": "/energy/pipelines/12345",
      "licence_number": "12345",
      "segment_id": "12345-1",
      "operator": { "name": "EXAMPLE ENERGY LTD", "ba_code": "0AB1", "slug": "example-energy-ltd" },
      "status": "operating",
      "segment_status_raw": "Operating",
      "substance": "natural_gas",
      "outside_diameter_mm": 114.3,
      "max_operating_pressure_kpa": 9930,
      "h2s_pct": 0, "h2s_release_level": null,
      "length_m_on_parcel": 412.7,
      "segment_length_km": 2.4,
      "overlap_point": { "lat": 50.06, "lng": -111.12 }
    }
  ],
  "meta": { "total": 2, "page": 1, "per_page": 50, "sort": "h2s", "dir": "desc", "substance": null, "status": null, "operator": null }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/facilities" \
  -H "X-API-Key: $TOWNSHIP_API_KEY" \
  --data-urlencode "legal_location=7-10-13-9-W4"

Parameters

Name	Type	Required	Description
legal_location	string	Required	Legal Subdivision (LSD) `7-10-13-9-W4`
category	string	Optional	Facility category (exact, case-insensitive)
status	string	Optional	Facility status (exact, case-insensitive)
operator	string	Optional	Operator name substring (case-insensitive)
sort	string	Optional	Sort key (default: status) `id` , `name` , `status`
dir	string	Optional	Sort direction `asc` , `desc`
page	integer	Optional	1-based page number (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "legal_location": "7-10-13-9-W4",
  "province": "AB",
  "rows": [
    {
      "id": "ABBT0012345",
      "facility_name": "EXAMPLE BATTERY 7-10",
      "category": "Battery",
      "sub_type": "Crude Oil Multiwell Group Battery",
      "sub_code": "341",
      "status": "operating",
      "facility_status_raw": "Operational",
      "licence_number": "F40001",
      "operator": { "name": "EXAMPLE ENERGY LTD", "ba_code": "0AB1", "slug": "example-energy-ltd" },
      "licensee": { "name": "EXAMPLE ENERGY LTD", "ba_code": "0AB1", "slug": "example-energy-ltd" },
      "location": { "lat": 50.06, "lng": -111.12 }
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 50, "sort": "status", "dir": "asc", "category": null, "status": null, "operator": null }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/tenure" \
  -H "X-API-Key: $TOWNSHIP_API_KEY" \
  --data-urlencode "legal_location=7-10-13-9-W4"

Parameters

Name	Type	Required	Description
legal_location	string	Required	Legal Subdivision (LSD) `7-10-13-9-W4`
tenure_kind	string	Optional	Registry to read (default: all) `png` , `mineral` , `all`
status	string	Optional	Disposition status (exact, case-insensitive)
operator	string	Optional	Holder name substring (case-insensitive)
expires_within_days	integer	Optional	Only dispositions expiring within this many days. Perpetual dispositions never enter the window
sort	string	Optional	Sort key (default: urgency - dispositions expiring within 24 months first, then soonest-first) `expiry` , `urgency` , `area` , `id`
dir	string	Optional	Sort direction `asc` , `desc`
page	integer	Optional	1-based page number (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "legal_location": "7-10-13-9-W4",
  "province": "AB",
  "rows": [
    {
      "id": "0512345",
      "href": "/energy/dispositions/0512345",
      "tenure_kind": "png",
      "province": "AB",
      "disposition_number": "0512345",
      "mineral_category": null,
      "disposition_type": "licence",
      "disposition_type_raw": "NAT GAS LIC",
      "holder": { "name": "EXAMPLE ENERGY LTD", "ba_code": null, "slug": "example-energy-ltd" },
      "status": "active",
      "expiry_date": "2027-03-01",
      "days_to_expiry": 192,
      "expiry_state": "expiring_soon",
      "area_ha": 256,
      "lsd_coverage_pct": 100,
      "is_transfer_pending": false,
      "overlap_point": { "lat": 50.06, "lng": -111.12 }
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 50, "sort": "urgency", "dir": "asc", "tenure_kind": "all", "status": null, "operator": null, "expires_within_days": null }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/operators" \
  -H "X-API-Key: $TOWNSHIP_API_KEY"

Parameters

Name	Type	Required	Description
q	string	Optional	Licensee name or BA code substring `example`
sort	string	Optional	Sort key (default: orphan, highest liability first) `orphan` , `active` , `abandoned` , `name` , `dispositions`
dir	string	Optional	Sort direction (default: desc for every sort except name) `asc` , `desc`
page	integer	Optional	1-based page number (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "rows": [
    {
      "ba_code": "0AB1",
      "name": "EXAMPLE ENERGY LTD",
      "slug": "example-energy-ltd",
      "active_wells": 1250,
      "abandoned_wells": 320,
      "orphan_wells": 14,
      "reclamation_certified_wells": 88,
      "dispositions_count": 412,
      "refreshed_at": "2026-08-01T00:00:00.000Z"
    }
  ],
  "meta": { "total": 4871, "page": 1, "per_page": 50, "sort": "orphan", "dir": "desc", "q": null }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/operators/example-energy-ltd" \
  -H "X-API-Key: $TOWNSHIP_API_KEY"

Parameters

Name	Type	Required	Description
{name}	string	Required	Path parameter. BA code, display name, kebab slug, or alphanumeric squash `example-energy-ltd`
view	string	Optional	Response shape (default: summary). The other views are paged `summary` , `dispositions` , `wells` , `lsds`
q	string	Optional	Substring search scoped to the view: disposition number or type, UWI or licence number, or legal location
tenure_kind	string	Optional	view=dispositions only. Registry to read (default: all) `png` , `mineral` , `all`
type	string	Optional	view=dispositions only. A mineral category (metallic, coal, potash, ...) filters the mineral registry; anything else is read as a PNG disposition type
status	string	Optional	view=dispositions: a registry status, or the derived expired / expiring (within 24 months). view=wells: the well's derived state (active, abandoned, suspended, orphan)
expires_within_days	integer	Optional	view=dispositions only. Only dispositions expiring within this many days (1-3650)
sort	string	Optional	Per view. dispositions: expiry (default), days, area, id, type, status. wells: uwi (default), status, licence, lsd. lsds: total (default), lsd, active, orphan
dir	string	Optional	Sort direction `asc` , `desc`
page	integer	Optional	1-based page number, on every view except summary (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "ba_code": "0AB1",
  "name": "EXAMPLE ENERGY LTD",
  "slug": "example-energy-ltd",
  "liability": {
    "total_wells": 1570, "active_wells": 1250, "suspended_wells": 92,
    "abandoned_wells": 320, "orphan_wells": 14, "reclamation_certified_wells": 88
  },
  "transfers": { "in": 41, "out": 12 },
  "tenure": {
    "png_dispositions": 412, "mineral_dispositions": 6, "total_dispositions": 418,
    "total_area_ha": 105320.5, "transfer_pending": 3, "expiring_soon": 27,
    "top": [{ "id": "0512345", "expiry_state": "expiring_soon", "...": "..." }]
  },
  "footprint": [
    {
      "legal_location": "10-36-42-3-W5", "province": "AB",
      "total_wells": 4, "active_wells": 2, "abandoned_wells": 1, "orphan_wells": 0,
      "centroid": { "lat": 52.5, "lng": -113.7 }
    }
  ],
  "footprint_total": 1840,
  "refreshed_at": "2026-08-01T00:00:00.000Z"
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/tenure/expiring" \
  -H "X-API-Key: $TOWNSHIP_API_KEY"

Parameters

Name	Type	Required	Description
expires_within_days	integer	Optional	Window size in days (1-3650, default: 365). Perpetual dispositions never enter the window
operator	string	Optional	Holder name substring
type	string	Optional	A mineral category filters the mineral registry; anything else is read as a PNG disposition type
tenure_kind	string	Optional	Registry to read (default: all) `png` , `mineral` , `all`
q	string	Optional	Disposition number or holder name substring
sort	string	Optional	Sort key (default: expiry) `expiry` , `days` , `area` , `operator` , `id`
dir	string	Optional	Sort direction (default: asc) `asc` , `desc`
page	integer	Optional	1-based page number (default: 1)
per_page	integer	Optional	Rows per page (1-200, default: 50)

Example Response

response.json

{
  "rows": [{ "...": "uniform tenure row with centroid + issue_date, lsd_coverage_pct null" }],
  "meta": {
    "total": 8140, "page": 1, "per_page": 50, "sort": "expiry", "dir": "asc",
    "expires_within_days": 365, "operator": null, "type": null, "tenure_kind": "all", "q": null,
    "total_area_ha": 1840220.75, "area_ha_known_count": 655, "area_ha_unknown_count": 7485
  }
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/dispositions/0510010001" \
  -H "X-API-Key: $TOWNSHIP_API_KEY"

Parameters

Name	Type	Required	Description
{number}	string	Required	Path parameter. A PNG disposition number, or a mineral slug category:number with the colon percent-encoded (metallic%3A0512345678). This is the id every tenure row carries `0510010001`

Example Response

response.json

{
  "tenure_kind": "mineral",
  "province": "AB",
  "mineral_category": "metallic",
  "disposition_number": "0512345678",
  "disposition_type": "metallic_and_industrial_minerals_permit",
  "disposition_type_raw": "MIN PERMIT",
  "status": "active",
  "issue_date": "2021-04-15",
  "expiry_date": "2027-04-15",
  "days_to_expiry": 604,
  "expiry_state": "expiring_soon",
  "area_ha": 2304,
  "target_substance": null,
  "coal_category": null,
  "is_transfer_pending": false,
  "holder": { "name": "EXAMPLE MINERALS LTD", "ba_code": null, "slug": "example-minerals-ltd" },
  "centroid": { "lat": 52.5, "lng": -113.7 },
  "lsds": ["10-36-42-3-W5", "11-36-42-3-W5"]
}

Example request

cURL

curl --get "https://developer.townshipcanada.com/energy/pipelines/12345" \
  -H "X-API-Key: $TOWNSHIP_API_KEY"

Parameters

Name	Type	Required	Description
{licence}	string	Required	Path parameter. AER pipeline licence number `12345`

Example Response

response.json

{
  "licence_number": "12345",
  "operator": { "name": "EXAMPLE ENERGY LTD", "ba_code": "0AB1", "slug": "example-energy-ltd" },
  "rows": [
    {
      "id": "12345-1", "segment_id": "12345-1", "segment_line_number": "1",
      "status": "operating", "segment_status_raw": "Operating", "substance": "natural_gas",
      "outside_diameter_mm": 114.3, "max_operating_pressure_kpa": 9930,
      "h2s_pct": 0, "h2s_release_level": null, "segment_length_km": 2.4,
      "from_facility": "AB BATTERY 01", "to_facility": "AB GAS PLANT 02",
      "centroid": { "lat": 52.5, "lng": -113.7 }
    }
  ],
  "meta": { "total": 14, "returned": 14, "truncated": false }
}

Vector Tiles

The Energy bundle's 12 map layers as vector tiles: wells, pipelines, facilities, production, and Crown tenure. Served from the maps CDN, authenticated with an api_key query parameter.

Tile URL Pattern

https://maps.townshipcanada.com/energy/{archive}/{z}/{x}/{y}.mvt?api_key=... https://maps.townshipcanada.com/energy/{archive}.json?api_key=... (TileJSON)

Available Archives

The source layer is the layer name inside the tile - MapLibre needs it in source-layer, and it does not always match the archive name. Anything outside this list returns 403.

Archive	Source Layer	Zoom	Layer
`pipelines`	`pipelines`	z0-22	Pipelines (also serves the label layer)
`facilities`	`facilities`	z0-22	Facilities
`facilities_labels`	`facilities_labels`	z13+	Facilities (labels)
`og_activity_lsd`	`og_activity`	z9-22	Well Activity (LSD)
`og_activity_sec`	`og_activity_sec`	z6-9	Well Activity (section rollup)
`og_activity_twp`	`og_activity_twp`	z0-6	Well Activity (township rollup)
`lsd_production_12mo`	`lsd_production`	z9-22	Production, trailing 12 mo (LSD)
`lsd_production_12mo_sec`	`production_sec`	z6-9	Production, trailing 12 mo (section rollup)
`lsd_production_12mo_twp`	`production_twp`	z0-6	Production, trailing 12 mo (township rollup)
`petroleum_tenure`	`petroleum_tenure`	z0-22	Petroleum & Natural Gas Tenure
`mineral_tenure`	`mineral_tenure`	z0-22	Mineral Tenure
`mineral_tenure_labels`	`mineral_tenure_labels`	z8+	Mineral Tenure (labels)

Zoom-Banded Rollup Families

og_activity and lsd_production_12mo each ship as three archives covering different zoom bands - LSD-level geometry is far too dense to draw at province scale. Add all three as separate sources and let the zoom ranges hand off; a client that adds only the detail archive sees an empty map below z9.

Zoom	Archive	Granularity
z0-6	`_twp`	Township (6 x 6 miles)
z6-9	`_sec`	Section (1 x 1 mile)
z9+	`base archive (_qs / _lsd / no suffix)`	Quarter section / LSD

The _labels archives are the same footprint rendered as a label layer. pipelines is the exception - its archive carries both geometry and labels.

MapLibre Usage

const KEY = "YOUR_API_KEY";
const base = "https://maps.townshipcanada.com/energy";

// Well activity is a zoom-banded family: add all three sources.
// A client that adds only the detail archive sees an empty map below z9.
map.addSource("og-activity-twp", {
  type: "vector",
  tiles: [`${base}/og_activity_twp/{z}/{x}/{y}.mvt?api_key=${KEY}`],
  minzoom: 0,
  maxzoom: 6
});
map.addSource("og-activity-sec", {
  type: "vector",
  tiles: [`${base}/og_activity_sec/{z}/{x}/{y}.mvt?api_key=${KEY}`],
  minzoom: 6,
  maxzoom: 9
});
map.addSource("og-activity-lsd", {
  type: "vector",
  tiles: [`${base}/og_activity_lsd/{z}/{x}/{y}.mvt?api_key=${KEY}`],
  minzoom: 9,
  maxzoom: 14
});

map.addLayer({
  id: "og-activity-lsd-fill",
  type: "fill",
  source: "og-activity-lsd",
  "source-layer": "og_activity", // note: not the archive name
  minzoom: 9,
  paint: { "fill-color": "#8c6bb1", "fill-opacity": 0.6 }
});

// TileJSON works too, and carries the bounds and zoom range
map.addSource("petroleum-tenure", {
  type: "vector",
  url: `${base}/petroleum_tenure.json?api_key=${KEY}`
});