# Realm Mining Intelligence

Public U.S. mining data: mines, production, employment, inspections, violations, health samples and case records.

## Citation documents and guides
- GET /api/v1/cases/similar?cfr=75.400 and MCP search_msha_cases: historical MSHA classification matches, unique issuance counts, separate proposed/current assessments, S&S known/unknown denominators, distributions and source rows. CFR and Mine Act filters combine with AND. Optional standardMatch=section|exact, kind, vacated=exclude|include|only, from/to ISO dates, page/pageSize (max 200). Default dates are January 1 four years before the snapshot year through the snapshot. No guessed similarity or penalty forecasts. Seven-day source revalidation required. CSV exports all matching rows up to 10,000; larger exports return 413. UI: /cases.
- GET /api/v1/compliance-guides?standards=75.400,75.1502: MSHA guide and policy-manual PDFs mentioning those sections; omit standards for the catalog.
- GET /api/v1/compliance-guides/{guide_id}/pdf: source PDF verified against the indexed SHA-256. Returns 409 if the source changed, 503 if its index is stale, and 404 for an unknown ID.
- MCP get_compliance_guides accepts an optional standards array. Publication statements are separate from the source-check date. A literal mention is not a finding of applicability. Stale indexes are not served as current.

## Silica and quartz
- GET /api/v1/mines/:mineId/silica: dated records, units, sample status, quarterly means and coverage.
- Parameters: year (snapshot year by default, or all), dataset (all/coal/personal/area), status (all/not_voided/voided/not_reported), page, pageSize (20 default, 200 maximum), format (json/csv). CSV exports all matching rows.
- MCP tool: get_silica_samples with mineId and the same filters.
- Coal quartz concentration is µg/m³, separate from quartz %. Voided/control samples do not enter coal trends. Personal C/E uses the published ratio; no coal compliance threshold is inferred.
- Personal/area concentration units and void status are not specified by the source dictionaries. Do not combine them with coal concentrations. Missing records are not evidence of safe conditions.
- coverage.scope distinguishes full_mine_history from retained_samples_only fallback; fallback trend/count coverage is incomplete.

## Representations
- Home: mine and controller leaderboard at /
- Leaderboard JSON: /api/v1/leaderboard?group=mines&period=latest-4&sort=production
- Leaderboard CSV: /api/v1/leaderboard?format=csv
- Leaderboard MCP tool: get_mining_leaderboard
- Human HTML: /mines/{name-slug}-{mine_id} (legacy ID URLs redirect)
- Markdown: /mines/{mine_id}.md
- JSON: /api/v1/mines/{name-slug}-{mine_id} (legacy ID URLs redirect)
- Quarterly mine trends: /api/v1/mines/{mine_id}/trends?period=latest-8
- Quarterly controller trends: /api/v1/controllers/{controller_id}/trends?period=latest-8
- Quarterly operator trends: /api/v1/operators/{operator_id}/trends?period=latest-8
- Safety reports: /api/v1/{mines|operators|controllers}/{id}/safety?period=2025
- Safety MCP tool: get_safety_report (kind, id, period, activity, page)
- Trends CSV: add &format=csv to either trends endpoint
- Trends MCP tool: get_production_trends (kind: mine/operator/controller, id, optional period)
- Valid-time mine relationships: /api/v1/mines/{mine_id}/relationships
- Controller portfolio: /controllers/{name-slug}-{controller_id} and /api/v1/controllers/{controller_id}
- Operator portfolio: /operators/{name-slug}-{operator_id} and /api/v1/operators/{operator_id}
- Search JSON: /api/v1/search?q={query}
- Grouped search JSON: /api/v1/search?scope=all&q={query} (mines, operators and controllers; inspect meta.sources)
- MCP: POST /mcp
- Stateless citation-text analysis: POST /api/v1/citations/analyze
- Public-identifier citation context: /api/v1/citations/context?mineId={mine_id}&standards={sections}
- Exact MDRS citation lifecycle: /api/v1/citations/{action_number}/lifecycle
- FMSHRC precedent search: /api/v1/precedents?standard={section}
- Title 30 index: /regulations (q searches section numbers and headings; chapter and part filter results)
- Title 30 HTML: /regulations/{section}
- Title 30 Markdown: /regulations/{section}.md
- Title 30 JSON: /api/v1/regulations/{section}
- Complete Title 30 corpus: /data/title30-sections.json

## Featured records
- /mines/oak-grove-mine-0100851 — Oak Grove Mine
- /mines/shoal-creek-mine-0102901 — Shoal Creek Mine
- /mines/north-antelope-rochelle-mine-4801353 — North Antelope Rochelle Mine

## Policies
Mine status: leaderboards and controller/operator portfolios, trends, safety, shipments, prices and GEM default to status=Active. Use status=all for all listed records, or a published MSHA status. Counts and aggregates use the same selected members. Status is current-snapshot status, not historical status; exact mine lookups are not filtered. Closed records can retain their last reported controller/operator.
GEM enrichment: GET /api/v1/{mines|operators|controllers}/{id}/gem or MCP get_gem_enrichment (kind, id, page). Exact published MSHA IDs only; no name/coordinate matching. Records retain GEM project scope, including multi-mine projects, observation years, raw cells and source hashes. Missing values remain null; no inferred mix or dominant grade. Both workbook download and release check must be fresh within seven days; unavailable or stale source returns 503. CSV exports every coal member/project. Material/method filters apply before controller ranking; classifications are independent of the MSHA period.

Coal receipts: GET /api/v1/{mines|operators|controllers}/{id}/shipments or MCP get_coal_shipments. period=latest-12 (default), all or an imported year; page selects 25 rows, format=csv exports all. Receipt periods follow EIA publication, independently of MSHA periods. Release URLs, SHA-256, workbook/sheet and row numbers preserve provenance. Quality is ton-weighted; cost calculations use only disclosed prices with positive tons and heat. Delivered USD/ton is cents/MMBtu / 100 * MMBtu/ton and includes transport; it is NOT mine revenue. No broad state/national price substitution. Only exact normalized MSHA mine-ID matches are assigned. Portfolio ownership is current. Records do not cover all sales or exports; missing rows do not prove zero shipments. Source checks older than seven days return unavailable until refreshed.

Annual coal prices: GET /api/v1/{mines|operators|controllers}/{id}/prices?year=latest or MCP get_coal_price_estimates. year is latest or an imported full calendar year; page selects 25 rows, CSV exports all. The model allocates reported county sales by eligible same-year mine production share, then multiplies by published county FOB price. It assumes proportional sales and county-average realized prices; this is not reported mine/company revenue. County mine counts must match; withheld prices and unmatched cohorts stay unavailable. No delivered-cost substitution, met premium, state fallback, quarterly apportionment or price carry-forward. Source checks must be within seven days. Portfolio ownership is current; coverage and missing annual records are explicit. Leaderboard sort=estimatedRevenue or benchmarkPrice requires a supported annual period; covered-mine sums are not whole-company revenue.

Production and safety reports share quarter-aligned periods: latest-8 (default), latest-4, 3y, 4y, 5y, 10y, all, or a calendar year. Exact bounds end at the snapshot and are in window; options are returned. Production gaps are null, not zero. Portfolio membership is current, not historical. Packaged fallback has only retained production quarters; full safety reports require PostgreSQL. Safety uses violation issue, accident and inspection start dates; counts include contractor records. Accident counts are records, not distinct incidents. Proposed penalties are USD, not final assessments. Missing hours/amounts are omitted. Zero means no imported records, not proof of no events; historical coverage varies by source. Safety JSON includes top CFR sections, per-mine totals and 25 activity rows/page; filter activity=all|violation|accident|inspection and page. Safety CSV exports quarterly metrics. Command+K searches all three entity groups in PostgreSQL. Mine and portfolio responses include usable coordinates where published.

The database leaderboard covers nationwide MSHA reporting mines. Filters apply before ranking and pagination. Controller totals include every matching reporting mine, attributed to its current controller. Scope is nationwide for database rankings, current_controller_portfolio for database controller trends, and profiled_mines_only for the limited 40-profile packaged fallback. JSON and MCP accept page (default 1) and pageSize (default 50, maximum 200); meta.totalRows and meta.totalPages describe all matches. CSV exports every matching row regardless of page. Read meta.quarters, meta.units, meta.scope and meta.snapshotAt. Missing quarters are omitted from sums, and average employees is null for incomplete periods. Leaderboard filters: group (mines/controllers), period (latest-4/year/quarter), sort (production/hours/productivity/employees/violations/accidents/inspectionHours/name), direction (asc/desc), q, state, type, material and method. Available periods and filters are returned in options.

Public pages and APIs may be crawled. Mine, entity, relationship, search, citation-lifecycle, overview, and MCP contracts query the nationwide PostgreSQL MDRS snapshot first. JSON responses expose the active path as meta.dataSource and X-Realm-Data-Source; packaged means the explicit resilience fallback. Cite source IDs and preserve valid-time, lifecycle-boundary, and authority caveats. Exact citation lifecycle joins use normalized citation/order number only, without fuzzy fallback. This service is not an official MSHA system and does not provide legal advice.