EPA Envirofacts & ECHO Skill

Never hardcode or log any key. If needed, pass as query parameter ?api_key=<KEY>.

Reading the credentials file (bash):

KEY=$(grep '^api_key=' ~/.config/epa/credentials 2>/dev/null | cut -d= -f2)
[ -z "$KEY" ] && KEY="${EPA_API_KEY}"

API Structure

Envirofacts REST API

Base URL: https://data.epa.gov/efservice/

The legacy enviro.epa.gov/enviro/efservice/ domain now 301-redirects here. Always use data.epa.gov.

URL pattern:

GET https://data.epa.gov/efservice/{TABLE}/{COL1}/{VAL1}/{COL2}/{VAL2}/.../rows/{START}:{END}/{FORMAT}

Comparison operators (placed after column name):

ECHO REST API

Base URL: https://echodata.epa.gov/echo/

ECHO uses a two-step query pattern:

1. Search — POST search parameters, receive a QueryID and row count
2. Retrieve — Use QueryID to page through actual records

Service families:

Common ECHO search parameters:

Key Tables and Endpoints

See references/table_reference.md for complete column listings.

Envirofacts Tables (verified available)

Envirofacts Tables (unavailable — use ECHO instead)

ECHO Endpoints

Workflow

Step 1 — Resolve Intent

Map the user's question to the right data source:

Step 2 — Fetch Data (Envirofacts)

Build the URL with appropriate filters:

# TRI facilities in Monongalia County, WV
curl -sL "https://data.epa.gov/efservice/TRI_FACILITY/STATE_ABBR/WV/COUNTY_NAME/MONONGALIA/rows/0:50/JSON"

# All EPA program links for a specific facility (by registry ID)
curl -sL "https://data.epa.gov/efservice/FRS_PROGRAM_FACILITY/REGISTRY_ID/110000344896/rows/0:20/JSON"

# TRI reports for WV in 2022
curl -sL "https://data.epa.gov/efservice/TRI_REPORTING_FORM/STATE_ABBR/WV/REPORTING_YEAR/2022/rows/0:50/JSON"

Default behavior:

• Request up to 100 rows per query (rows/0:99)
• If result set is large, paginate by incrementing the row range
• Parse JSON response — returns a flat array of row objects

Step 3 — Fetch Data (ECHO)

Use the two-step pattern:

# Step 1: Search
RESULT=$(curl -sL "https://echodata.epa.gov/echo/cwa_rest_services.get_facilities?output=JSON&p_st=WV&p_co=MONONGALIA")
QID=$(echo "$RESULT" | jq -r '.Results.QueryID')
TOTAL=$(echo "$RESULT" | jq -r '.Results.QueryRows')
echo "QueryID: $QID, Total: $TOTAL"

# Step 2: Retrieve records
curl -sL "https://echodata.epa.gov/echo/cwa_rest_services.get_qid?output=JSON&qid=$QID&pageno=1&pagesize=20"

For ECHO, always:

• Check .Results.Message for "Success" or "Working" (both indicate valid results)
• Check .Results.Error.ErrorMessage if present
• Use pageno and pagesize to page through large result sets
• Note summary statistics in step 1 (SVRows, CVRows = significant/current violators)

Step 4 — Parse Response

Envirofacts response: JSON array of row objects at root level.

[
  {"tri_facility_id": "26504PTRTM1090C", "facility_name": "PATRIOT MINING CO INC OSAGE MINE", ...},
  {"tri_facility_id": "26504PTRTM12MIA", "facility_name": "PATRIOT MINING CO INC DENTS RUN MINE", ...}
]

ECHO response: Nested JSON with Results wrapper.

{
  "Results": {
    "Message": "Working",
    "QueryRows": "2153",
    "QueryID": "357",
    "PageNo": "1",
    "Facilities": [
      {"CWPName": "FACILITY NAME", "SourceID": "WV0045233", ...}
    ]
  }
}

Step 5 — Produce Output

Format: Facility Table + Narrative Summary

Present a markdown table of the most relevant records (cap at ~20 rows), then a narrative summary covering:

1. Result count — how many facilities/systems matched
2. Key findings — notable compliance issues, major dischargers, violators
3. Geographic context — county, region, proximity to areas of interest
4. Compliance summary — violation counts, enforcement actions, SNC status
5. Cross-reference note — other EPA programs the facility appears in
6. Caveats — data currency, self-reported vs measured, legacy PCS vs ICIS

Example output structure:

## TRI Facilities — Monongalia County, WV

| Facility Name | TRI ID | City | Status | Parent Company |
|---------------|--------|------|--------|----------------|
| PATRIOT MINING CO INC OSAGE MINE | 26504PTRTM1090C | Star City | Active | ANKER GROUP INC |
| PATRIOT MINING CO INC DENTS RUN MINE | 26504PTRTM12MIA | Star City | Active | ANKER GROUP INC |
| ... | ... | ... | ... | ... |

**Summary:** 4 TRI-reporting facilities were found in Monongalia County, WV
(EPA Region 03). Two are coal mining operations (PATRIOT MINING) that report
zinc compounds and other releases. All facilities are currently active.
Cross-reference via FRS to check CWA discharge permits and RCRA status.

**Caveats:** TRI data is industry self-reported annually. Release quantities
may be estimated (code E), measured (M), or calculated (C). Reporting
thresholds apply — small-quantity releases may not appear.

Pagination

Envirofacts

If results might exceed your row range, paginate by incrementing the range:

all_rows = []
start = 0
page_size = 100
while True:
    rows = fetch_envirofacts(table, filters, start, start + page_size - 1)
    all_rows.extend(rows)
    if len(rows) < page_size:
        break  # last page
    start += page_size

Warn the user if the result set is very large (over 1000 rows) and suggest adding filters (county, year, SIC code) to narrow results.

ECHO

Use pageno and pagesize parameters on the get_qid endpoint:

page = 1
while page * pagesize <= total:
    records = echo_retrieve(program, qid, page=page, pagesize=20)
    # process records
    page += 1

Error Handling

Cross-Reference Strategy

EPA maintains facility IDs across multiple regulatory programs. The FRS Registry ID is the master cross-reference key:

FRS Registry ID (e.g., 110000344896)
  |-- TRI:   tri_facility_id  (via epa_registry_id in TRI_FACILITY)
  |-- NPDES: permit ID         (via FRS_PROGRAM_FACILITY, pgm_sys_acrnm=ICIS)
  |-- RCRA:  handler ID        (via FRS_PROGRAM_FACILITY, pgm_sys_acrnm=RCRAINFO)
  |-- SDWA:  PWS ID            (via FRS_PROGRAM_FACILITY, pgm_sys_acrnm=SDWIS)
  |-- ECHO:  DfrUrl            (uses registry_id as fid parameter)

Workflow to link a facility across programs:

1. Find the facility in any table and get its FRS Registry ID
2. Query FRS_PROGRAM_FACILITY with that registry ID
3. Use the returned program IDs to query specific tables or ECHO endpoints

PNGE-Relevant Query Patterns

Find Oil & Gas Facilities by SIC Code

# SIC 1311 = Crude Petroleum and Natural Gas
# SIC 1381 = Drilling Oil and Gas Wells
curl -sL "https://echodata.epa.gov/echo/cwa_rest_services.get_facilities?output=JSON&p_st=WV&p_sic=1311"

TRI Releases for Specific Chemicals

# Search TRI reporting forms for a specific chemical (by CAS name)
curl -sL "https://data.epa.gov/efservice/TRI_REPORTING_FORM/STATE_ABBR/WV/CAS_CHEM_NAME/CONTAINING/BARIUM/rows/0:20/JSON"

Drinking Water Systems Near a Site

# Community water systems in a county
curl -sL "https://echodata.epa.gov/echo/sdw_rest_services.get_systems?output=JSON&p_st=WV&p_co=MONONGALIA&p_pswsid_code_type=community"

Environmental Justice Context

ECHO search results include demographic data fields:

• PercentPeopleOfColor — percent people of color in surrounding area
• FacPopDen — population density around facility
• AcsPopulationDensity — ACS population density

These can be used to flag potential environmental justice concerns near produced water disposal sites or processing facilities.

EPA Region Reference

West Virginia is in EPA Region 03 (with DC, DE, MD, PA, VA).

Key Appalachian-basin states by region:

• Region 03: WV, PA, VA
• Region 04: KY
• Region 05: OH

SIC Codes for PNGE Research

Implementation Notes

• Prefer bash with curl + jq for API calls in Claude's environment
• Python stdlib client — see references/python_example.py for Envirofacts and ECHO client classes using only urllib and json
• Envirofacts returns flat JSON arrays — no wrapper object, no pagination metadata; rely on returned row count vs requested range to detect more pages
• ECHO returns nested JSON — always navigate to .Results and check for .Error before processing data
• TRI latitude/longitude — fac_latitude and fac_longitude are in DDMMSS integer format (e.g., 393800 = 39d 38m 00s). Use pref_latitude/pref_longitude (decimal degrees) when available
• PCS is legacy — the Permit Compliance System has been replaced by ICIS-NPDES for current data. Use ECHO CWA endpoints for current permit and compliance information
• Data currency — TRI data lags ~18 months (2024 data available mid-2025); ECHO compliance data is updated quarterly
• Self-reported data — TRI releases are industry self-reported with estimation methods; verify with ECHO inspection/enforcement data where possible