API documentation

Endpoints

Leaderboard parameters

Open example: 2025 mine production

group

mines (default) or controllers

period

latest-4 (default), a full reporting year such as 2025, or a quarter such as 2026-Q2. Available values are returned in options.periods.

sort / direction

production (default), hours, productivity, employees, violations, accidents, inspectionHours or name. Direction: desc (default) or asc.

q / state / type

Search text, a state abbreviation, or mine type. Filters apply to mines before controller totals are calculated.

page / pageSize

Page starts at 1. JSON and MCP return 50 rows by default, up to 200. CSV includes every matching row.

format

json (default) or csv

material / method

Exact values from options.materials and options.methods. Material uses GEM grade where reported, otherwise MSHA commodity; method also accepts unreported. GEM filters require a fresh full source. Filters apply to mines before controller aggregation. Classifications describe the GEM release independently of the MSHA period.

The database leaderboard covers nationwide MSHA mines with reports in the selected period. Filters apply before ranking and pagination. Controller totals use current ownership and include every matching reporting mine. The response includes units, reporting quarters and the snapshot date. Missing quarters are omitted from totals; average employees is null when reporting is incomplete.

Production and safety periods

Mine, operator and controller /trends and /safety endpoints share period: latest-8 (default), latest-4, 3y, 4y, 5y, 10y, all or a calendar year. These are quarter-aligned windows, ending no later than the snapshot date. The response includes exact bounds and available options. The current quarter is partial. Packaged production fallback has only retained quarters; full safety reports require PostgreSQL.

Production gaps are null; reported zeroes stay zero. Productivity divides production by employee hours for the same reported quarters. Portfolio membership is current, not historical. Trend metadata identifies included/reporting mines. JSON includes per-mine production metrics; format=csv downloads the quarterly series.

Safety uses violation issue dates, accident dates and inspection begin dates. Counts include contractor records. Accident counts are published rows, not distinct incidents or numbers injured. Fatality records use injury degree 01; S&S uses SIG_SUB=Y. Penalties are proposed USD, not final assessments. Inspection hours are reported on-site hours, without supervisor/trainee hours; missing values are omitted.

Safety JSON includes quarterly totals, per-mine metrics, the ten most cited CFR sections and 25 activity rows per page. Filter activity with activity=all|violation|accident|inspection and page. These filters change only the activity list. format=csv exports quarterly data. Zero means no matching imported records; source coverage and reporting delays still matter.

MCP tools get_production_trends and get_safety_report accept kind (mine/operator/controller), id and period. The safety tool also accepts activity and page. Structured responses match the JSON endpoints. Mine and portfolio JSON expose available coordinates for maps.

Silica and quartz samples

/api/v1/mines/:mineId/silica accepts year (snapshot year by default, an available year, or all), dataset (all, coal, personal, area), status (all, not_voided, voided, not_reported), page and pageSize (20 by default, maximum 200). CSV exports every matching row. The MCP tool get_silica_samples takes the same parameters plus mineId.

Coal quartz concentrations are in µg/m³; quartz percentages are separate. Trends exclude voided, unknown-status, control/invalid and undated or post-snapshot coal samples. Missing measurements are null. Personal C/E is the ratio published by MSHA, not a newly calculated compliance result. Personal/area concentration units and void status are not specified in their data dictionaries; raw values remain available. Area results include bulk-dust samples and are not combined with personal exposure results.

Quarterly means cover the selected year, or the latest 12 quarters when year=all; counts cover all matching records. The current quarter is partial. Check coverage.scope: full_mine_history means PostgreSQL; retained_samples_only means the incomplete packaged fallback. Missing records do not establish safe conditions.

Data coverage

Check meta.dataSource and the X-Realm-Data-Source response header. postgres means a database query; packaged means the bundled snapshot. Database leaderboards use nationwide scope; controller trends use current_controller_portfolio. The packaged fallback is explicitly marked profiled_mines_only and covers 40 profiles. Search and record endpoints use the database when configured, with packaged data as a fallback.

A record missing from the packaged snapshot may still exist in MSHA. Source IDs, dates and row counts accompany the records. Historical ownership uses the dates published by MSHA; citation records are matched by exact citation/order number.

MCP tools

Send JSON-RPC requests to POST /mcp. Supported methods include initialize, tools/list, tools/call, resources/list and resources/read.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"get_mining_leaderboard",
  "arguments":{"group":"controllers","period":"2025","sort":"production"}
}}

The leaderboard tool returns the same data and coverage metadata as the JSON endpoint. Other tools cover mine search, mine records, ownership, citation analysis, citation history, Title 30 and FMSHRC cases.

Mine status

Leaderboards and controller/operator portfolios default to status=Active. Use status=all to include closed and other inactive records, or a published MSHA status. The same selection applies to portfolio trends, safety, shipments, prices and GEM reports, including exports and MCP tools. Exact mine lookups remain available regardless of status. Status comes from the current snapshot, not the selected historical reporting period.

Discovery and downloads

llms.txt · Sitemap · Full Title 30 corpus (JSON)

The citation page reads PDFs in the browser and sends only public identifiers for lookups. The text-analysis endpoint accepts citation text in its request body and does not store it.