What is ClearPHMSA

ClearPHMSA provides a single-pane set of dashboards, exports, and APIs over PHMSA incidents, annual reports, and enforcement actions. It’s designed for utility operators, regulators, and consultancies to analyze trends, benchmark peers, and generate compliance-ready insights.

  • Ten years of PHMSA data in one place with role-based dashboards
  • Peer benchmarking by size and region with uncertainty-aware comparisons
  • CSV/Parquet exports and REST APIs for downstream systems
  • Operational governance: user/session tracking, notifications, and refresh SLAs

API specification

Use the ClearPHMSA APIs to programmatically access incidents, annual reports, and enforcement data. Endpoints are versioned, secured with bearer tokens, and support filtering, pagination, and bulk exports. The examples below are illustrative.

Authentication & versioning
  • Auth: Bearer tokens via Authorization: Bearer <token>
  • Base URL: /api/v1 (semantic versioned)
  • Content: JSON by default; CSV/Parquet for downloads

Example:

GET /api/v1/incidents?program=gd&start=2015-01-01&end=2024-12-31
Authorization: Bearer YOUR_TOKEN
Accept: application/json
Pagination, sorting, and rate limits
  • Pagination: page (1-based), per_page (default 50, max 1000)
  • Sorting: sort=field, order=asc|desc (comma for multi)
  • Rate limits: Headers X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
GET /api/v1/incidents?program=gd&page=2&per_page=100&sort=incident_date,damage_usd&order=desc,desc
Endpoints
  • GET /api/v1/incidents — query incidents (GD, GT&G, HL)
  • GET /api/v1/annuals — query annual exposure and program metrics
  • GET /api/v1/enforcement — query enforcement actions and penalties
  • POST /api/v1/exports — start bulk export job (CSV/Parquet)
  • GET /api/v1/exports/{job_id} — check export job status/result
  • POST /api/v1/webhooks — manage webhook subscriptions (create/list/delete)
Incidents parameters
  • program: gd | gtg | hl (required)
  • start, end: ISO dates
  • state_fips: 2-digit; geoid (optional)
  • operator: string match; operator_id exact
  • cause, severity: enums
  • fields: comma list to project
  • format: json | csv (streamed)
Annuals parameters
  • program: gd | gtg | hl (required)
  • year: 4-digit; or years: 2015:2024
  • metrics: miles, services, materials, ili_coverage, etc.
  • aggregate: none | state | operator
  • format: json | csv
Enforcement parameters
  • operator | operator_id
  • case_type: cao | nopv | noa | other
  • issued_start, issued_end: dates
  • penalty_min, penalty_max: USD
  • status: open | closed | appealed
  • format: json | csv
Errors & headers
  • Standard error body: { code, message, details, request_id }
  • Trace headers: X-Request-Id, X-Trace
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": "invalid_parameter",
  "message": "Unknown program 'gdd'",
  "details": { "program": "gdd" },
  "request_id": "req_01hxyz..."
}
Webhooks
  • Events: incidents.refreshed, annuals.refreshed, enforcement.refreshed, exports.completed
  • Security: X-Webhook-Signature (HMAC)
POST https://your-app/webhooks/clearphmsa
{
  "id": "evt_01h...",
  "type": "incidents.refreshed",
  "created": "2025-09-23T12:00:00Z",
  "data": { "program": "gd", "asof": "2025-09-23" }
}
Responses (examples)

Incidents (truncated fields):

{
  "page": 1,
  "per_page": 50,
  "total": 1234,
  "results": [
    {
      "incident_id": "gd-2020-12345",
      "program": "gd",
      "incident_date": "2020-07-12",
      "state_fips": "06",
      "operator": "Example LDC",
      "cause": "corrosion",
      "injuries": 0,
      "fatalities": 0,
      "damage_usd": 125000
    }
  ]
}

Export job (CSV):

POST /api/v1/exports { "kind": "incidents", "program": "gd", "years": "2015:2024", "format": "csv" }
HTTP/1.1 202 Accepted
{ "job_id": "exp_01h...", "status": "queued" }

GET /api/v1/exports/exp_01h...
{ "status": "completed", "url": "https://.../gd_incidents_2015_2024.csv" }
Dashboards (in-app)
Downloads & data dictionary

CSV downloads per program:

External integration options
  • Exports: Schedule CSV/Parquet drops by program and time window
  • APIs: REST endpoints for incidents, annuals, and enforcement
  • Webhooks: Notify downstream systems on new records/refreshes
  • Embedding: Link to role-based dashboards for exec, safety, engineering

Example CLI (illustrative):

clearphmsa export incidents --program gd --years 2015:2024 --format csv
clearphmsa export annuals --program gtg --format parquet
clearphmsa export enforcement --asof 2025-09-23

Example API (illustrative):

GET /api/v1/incidents?program=gd&start=2015-01-01&end=2024-12-31
GET /api/v1/annuals?program=hl&year=2023
GET /api/v1/enforcement?operator=PGE
Operations, security, and SLAs
  • Auth & roles: User groups, subscription states, and email status
  • Session governance: UserSession for active session tracking
  • Notifications: in-app and email via Notification and templates
  • Data freshness: monthly incidents/enforcement, annuals yearly; versioned snapshots
  • Quality: schema and row-count checks; data dictionaries linked in-app
Onboarding checklist for external teams
  1. Connect authentication and assign user groups
  2. Select programs (GD, GT&G, HL) and define your peer set
  3. Run initial ingest and validation on a snapshot
  4. Schedule refresh and exports to your data lake
  5. Wire up APIs/webhooks for downstream workflows
  6. Configure notifications and monitors for SLAs

Example CLI (illustrative):

clearphmsa configure --auth sso --org YOUR_ORG
clearphmsa ingest incidents --program gd --asof 2025-09-23 --validate
clearphmsa schedule export --target s3://your-bucket/phmsa/ --cadence monthly
ClearPHMSA
PHMSA pipeline safety insights.
Product
Features
Services
Company

All rights reserved. Copyright © by ClearPHMSA