Energy Pack API Guide

The Energy Pack is an add-on ($150/mo on top of Pro+ or Business, or bundled with Enterprise) that layers federal-land energy data on top of Township America's PLSS + TXSS conversion engine. Eight endpoints under /api/energy/* answer the workflows landmen, ALTA surveyors, solar developers, and mineral-rights investors run every day.

Auth and Gating

All Energy Pack endpoints require:

Authenticated user (any Pro+ or higher), and
Active Energy Pack add-on subscription, OR Enterprise tier (auto-included).

Unauthenticated callers get 401 Unauthorized. Pro+ users without the add-on get 402 Payment Required with a /pricing?addon=energy_pack upgrade pointer.

A GET /api/billing/energy-pack-status endpoint lets your UI check entitlement before showing energy-related UI:

curl -H "Authorization: Bearer $TA_API_KEY" \
  "https://townshipamerica.com/api/billing/energy-pack-status"

Returns { "plan": "pro_plus", "eligible": true, "bundled": false, "entitled": true, "source": "addon", "pricing": {...} }.

Section Input

Every spatial endpoint accepts a section query parameter that can be:

A PLSS legal description: ?section=T2N+R3W+Sec+14+Huntsville+Meridian
A Texas abstract: ?section=A-123+Reeves+County,+TX
A numeric lookup row id (internal): ?section=42

The resolver runs the input through the unified parser (PLSS detection → TXSS fallback → lookup) and returns 404 if it can't resolve.

Endpoints

`GET /api/energy/wells?section={ref}&buffer={miles}`

Multi-state federal-land wells from state O&G commissions (CO/ND/OK/WY/NM) plus TX RRC surface wells. Default buffer=0; max buffer=5. Returns up to 200 wells per state ordered by distance to section centroid.

curl -H "Authorization: Bearer $TA_API_KEY" \
  "https://townshipamerica.com/api/energy/wells?section=T2N+R3W+Sec+14+Wyoming&buffer=1"

`GET /api/energy/leases?section={ref}`

BLM MLRS federal O&G leases intersecting a section. Returns case id, status, holder, effective / expiration dates, acreage, commodity, and the polygon.

curl -H "Authorization: Bearer $TA_API_KEY" \
  "https://townshipamerica.com/api/energy/leases?section=T2N+R3W+Sec+14+Wyoming"

`GET /api/energy/split-estate?section={ref}`

Surface vs subsurface ownership flag.

{
  "section": { "input": "..." },
  "is_split_estate": true,
  "surface": { "type": "private", "agency": null, "coverage_pct": 1.0 },
  "subsurface": { "type": "federal", "agency": "BLM", "coverage_pct": 0.98 }
}

`GET /api/energy/offset-operators?section={ref}&buffer={miles}`

Distinct operators ranked by well count within a buffer. Defaults to buffer=1 (landman convention for offset analysis).

`GET /api/energy/orphaned-wells?section={ref}&buffer={miles}`

USGS Defunct/Orphaned Wells inside a section + buffer. Liability screen for unplugged or improperly abandoned wells that surface during federal-leasing diligence or acquisition underwriting.

`GET /api/energy/sage-grouse?section={ref}`

BLM Sage-Grouse Habitat Management Area overlay. Returns in_habitat boolean plus per-designation overlap acres.

`GET /api/energy/renewable-siting?section={ref}`

Combined NREL Land of Opportunity score + BLM Western Solar Plan zone overlap + USGS Wind Turbine proximity (2 mi).

`GET /api/energy/royalties?lease={lease_no}&years={n}`

ONRR (Office of Natural Resources Revenue) royalty history per BLM lease. Defaults to years=10; max 30. Note this endpoint keys on lease (a BLM lease number), not section.

curl -H "Authorization: Bearer $TA_API_KEY" \
  "https://townshipamerica.com/api/energy/royalties?lease=WYW-0190123&years=10"

Latency Targets

The p95 latency target across all endpoints is <800 ms. The spatial queries are GIST-indexed and the per-state union queries short-circuit if any state table is missing.

Stripe Checkout

To add the Energy Pack from your application, hit the checkout endpoint:

curl -X POST -H "Authorization: Bearer $TA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"billingCycle": "monthly"}' \
  "https://townshipamerica.com/api/billing/energy-pack-checkout"

Response: { "url": "https://checkout.stripe.com/...", "session_id": "cs_..." }. Redirect the user to url to complete checkout. The webhook handler upserts the app.subscription_addons row on checkout.session.completed.

Pricing

$150/mo when added to Pro+ (or higher)
$1,440/yr annual prepay (20% off)
Bundled at no additional cost with Enterprise (custom pricing)

API Integration — general patterns
Texas API — the TXSS engine that backs Texas section input

Need help with an Energy Pack integration? Contact us.