# MSHA Compliance Action (Assessed Violations) Data Scraper (`crawlerbros/msha-compliance-action-scraper`) Actor Scrape the U.S. Mine Safety and Health Administration's (MSHA) full case-level Assessed Violations enforcement dataset - 3M+ citations and orders since 2000, joined with mine details (state, commodity, operator). Filter by mine, violator, state, commodity, penalty amount, date range, and more. - **URL**: https://apify.com/crawlerbros/msha-compliance-action-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Integrations, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## MSHA Compliance Action (Assessed Violations) Data Scraper Scrape the U.S. Mine Safety and Health Administration's (MSHA) full case-level enforcement data — **3M+ citations and orders, 1.1M+ inspections, and 270K+ accidents since 2000** — joined with each mine's state, commodity, operator, district, and status. Search assessed penalties, raw citations (with negligence/gravity/likelihood detail), accidents & injuries, or inspection activity; filter by name, state, commodity, date range, and dozens more axes; or look up every record for specific mine IDs. Sourced directly from MSHA's public Open Government Data bulk files. No auth, no API key, no cookies, no proxy. ### What this actor does - **Five modes:** - `search` — filtered scan of MSHA's Assessed Violations dataset (penalty-focused) - `byMineId` — exact lookup of assessed violations for one or more mine IDs - `violations` — MSHA's broader raw Violations dataset: every citation issued (including cases still in process), with negligence level, likelihood of injury, injury/illness potential, and contest/docket status the Assessed Violations dataset doesn't carry - `accidents` — MSHA's Accidents/Injuries/Illness dataset: degree of injury, classification, accident type, body part, narrative - `inspections` — MSHA's Inspections dataset: every inspection event, by activity code, date range, and office - **30+ filters** across the five modes: violator/mine name, state, commodity type, coal vs. metal/nonmetal, MSHA district, mine status (active/abandoned/etc.), violator type, violation type (legal basis), citation type, case status, negligence level, likelihood, injury/illness potential, contested/special-assessment flags, penalty amount range, date ranges, mine type, degree of injury, accident classification/type, immediate-notification type, inspection activity code, inspecting office code - **Mine enrichment:** every record is joined against MSHA's Mines dataset for state, commodity, operator/controller name, district, mine type/status, employee count, and coordinates - **Penalty-scoring detail:** exposes the gravity/negligence/history points MSHA's formula uses to calculate each penalty, not just the final dollar amount - **Empty fields are omitted** — every field on every record is real, populated data ### Data source This actor scrapes MSHA's **Open Government Data** bulk files at `arlweb.msha.gov` — no login, no API key, no registration required: - `AssessedViolations.zip` — the case-level "Assessed Violations" dataset: every citation/order that reached a penalty assessment since January 2000, ~3M rows (mode=search, byMineId) - `Violations.zip` — MSHA's broader raw citation dataset: every violation issued since 2000 (assessed or not), ~3.08M rows, with negligence/likelihood/gravity detail (mode=violations) - `Accidents.zip` — every accident, injury, and illness reported since 2000, ~274K rows (mode=accidents) - `Inspections.zip` — every MSHA inspection event since 2000, ~1.15M rows (mode=inspections) - `Mines.zip` — the mine lookup table (~92K mines): name, state, commodity classification, operator, district, mine type/status All are official MSHA data exports, refreshed regularly by the agency, and are joined against `Mines.zip` at scrape time by `MINE_ID`. #### Feature surface: what was checked and why it's/isn't included MSHA's Open Government Data portal (`arlweb.msha.gov/opengovernmentdata/ogimsha.asp`) lists 20 public bulk datasets. Beyond the four scraped above, these were checked and intentionally excluded: - **Employment/Production (quarterly & yearly)** — aggregate hours/production by mine, not a compliance-action or per-case record; out of scope for an enforcement-data actor. - **Coal Dust / Quartz / Noise / Area / Personal Health Samples** — industrial-hygiene sampling data, not enforcement actions; a different research domain. - **Conferences, Civil Penalty Dockets & Decisions, Contested Violations, 107(a) Orders Issued** — narrower subsets of data already covered by `mode=violations` (which includes `contested`, `docketNumber`, `docketStatus`, and every citation type including 107(a) imminent-danger orders). - **Controller/Operator History, Address of Record** — ownership-history and mailing-address lookups, not violation/accident/inspection activity — a reasonable future addition but out of scope for this pass. - **Per-inspector search** — MSHA's bulk exports report only the inspecting office code (`inspectOfficeCode`) and an inspector head-count (`inspectorCount`); no individual inspector name is published, so "search by inspector" is not reliably supportable without a different (non-bulk) data source. #### Why MSHA instead of DOL Wage & Hour Division (WHD) This actor was originally scoped as a DOL Wage & Hour Division "Workers Owed Wages" / compliance-action case-level scraper. During implementation, `enforcedata.dol.gov` (the WHD public data UI) and `webapps.dol.gov` (the consumer-facing search tool) were confirmed — via curl_cffi with Chrome TLS impersonation, a real headless-Chromium browser, Python's stdlib `urllib`, and an independent fetch from a completely different network — to return an **identical, byte-for-byte 403 Forbidden** on every path tested, including the bare domain root. The consistent AWS load-balancer error page across four unrelated HTTP client implementations rules out a TLS-fingerprint or headless-browser detection block; it indicates a blanket WAF rule against automated/cloud traffic, which would equally block Apify's datacenter proxy ranges. The only alternative case-level path, `apiprod.dol.gov/v4/...`, requires a registered API key (`dataportal.dol.gov`) — a hard violation of this project's zero-cost policy, since the actor must return real data with no user-supplied credentials. DOL's own aggregate CSV (`dol.gov/.../all-acts.csv`) is reachable but is year/state-level summary data only, with no employer names, case IDs, or per-case penalty amounts. MSHA is itself a U.S. Department of Labor agency — a different sub-agency than WHD, but still core "DOL enforcement/compliance action data." Its Open Government Data bulk files are freely downloadable with no auth of any kind, confirmed reachable via a plain, unimpersonated HTTP client. This actor was built against MSHA's Assessed Violations dataset as a genuinely zero-cost-compliant replacement within the same DOL enforcement-data scope. #### A note on industry classification (no NAICS) MSHA classifies mines using its own **SIC-based** taxonomy (`PRIMARY_SIC` / `PRIMARY_CANVASS`), not NAICS. Rather than fabricate NAICS codes that MSHA's data doesn't contain, this actor exposes `commodityType` (Coal / Metal / Nonmetal / Sand & Gravel / Stone) and `primarySicDescription` — the real classification MSHA actually reports. ### Output Output shape depends on `mode` (`recordType`: `mshaViolation` / `mshaViolationDetail` / `mshaAccident` / `mshaInspection`). All four share the same mine-enrichment fields (`state`, `county`, `district`, `commodityType`, `mineType`, `mineStatus`, `latitude`, `longitude`, etc.) joined from MSHA's Mines dataset. #### mode=search / byMineId (`mshaViolation`) **Identity & parties** - `eventNumber`, `violationNumber`, `assessCaseNumber` — MSHA's case identifiers - `mineId`, `mineName` — the cited mine - `violatorId`, `violatorName`, `violatorType` (`Operator` / `Contractor`) - `officeCode` — MSHA field office that issued the citation **Violation details** - `primaryActionCode` — legal basis (e.g. `104(a)`, `104(d)(1)`, `107(a)`) - `citationType` (`Citation` / `Order` / `Safeguard` / `Notice`), `assessType` (`Regular` / `Single` / `Special`) - `coalMetalIndicator` (`C` / `M`), `coalMetalDescription` - `significantAndSubstantial`, `goodFaith`, `excessiveHistory` — inspector-flagged booleans - `cfrStandardCode`, `mineActSectionCode` — the specific federal standard cited - `caseStatus` (`Closed` / `Received` / `Printed` / `Invalid`) **Dates** (ISO `YYYY-MM-DD`) - `occurrenceDate`, `issueDate`, `finalOrderDate`, `caseStatusDate`, `billPrintDate`, `delinquentDate`, `historyStartDate`, `historyEndDate`, `violatorStartDate`, `violatorEndDate` **Money** - `proposedPenaltyAmount`, `currentAssessmentAmount`, `paidAmount` - `mineActInterestAmount`, `exLateInterestAmount`, `paidMineActInterestAmount`, `paidExLateInterestAmount` **Penalty-scoring detail** (MSHA's point-based formula — populated for `Regular` assessments) - `penaltyPoints`, `gravityPersonsPoints`, `gravityInjuryPoints`, `gravityLikelihoodPoints`, `negligencePoints`, `goodFaithPoints`, `contractorSizePoints`, `mineSizePoints`, `controllerSizePoints` - `violatorViolationCount`, `violatorInspectionDayCount`, `violatorRepeatedViolationCount`, `violatorRepeatedViolationPoints`, `violationPerInspectionDayPoints` - `violationsPerInspectionDayRatio`, `repeatedViolationRatio` — the raw ratios behind the points above - `violatorMineHours`, `violatorProductionAmount`, `sizeOfMine`, `controllerHours`, `controllerProductionAmount`, `sizeOfControllingEntity` **Mine details** (joined from MSHA's Mines dataset) - `state`, `county`, `district`, `latitude`, `longitude` - `commodityType` (`Coal` / `Metal` / `Nonmetal` / `SandAndGravel` / `Stone`), `primarySicCode`, `primarySicDescription` - `operatorName`, `controllerName`, `mineType` (`Surface` / `Underground` / `Facility`), `mineStatus`, `numberOfEmployees` #### mode=violations (`mshaViolationDetail`) Every violation MSHA has issued since 2000 — including citations still in process — with the negligence/gravity detail the Assessed Violations dataset doesn't carry: - Identity: `eventNumber`, `violationNumber`, `mineId`, `mineName`, `mineType`, `controllerId`/`controllerName`, `violatorId`/`violatorName`/`violatorType`, `contractorId` - Legal basis: `primaryActionCode`, `secondaryActionCode`, `sectionOfAct`, `cfrStandardCode`, `citationType` (adds `Written Notice` to the values above) - Gravity/negligence: `negligenceLevel` + `negligenceLevelDescription`, `likelihood` + `likelihoodDescription`, `injuryIllnessPotential` + `injuryIllnessPotentialDescription`, `personsAffectedCount`, `significantAndSubstantial` - Process: `contested`, `contestedDate`, `docketNumber`, `docketStatus`, `specialAssessment`, `writtenNotice`, `enforcementArea`, `primaryOrMill`, `assessmentGeneratedBy` - Dates/times: `issueDate`/`issueTime`, `occurrenceDate`, `inspectionBeginDate`/`inspectionEndDate`, `originalAbateDueDate`/Time, `latestAbateDueDate`/Time, `terminationDate`/Time/`terminationType`, `vacateDate`/Time, `rightToConferenceDate`, `finalOrderIssueDate`, `billPrintDate`, `lastActionCode`/`lastActionDate` - Money: `proposedPenaltyAmount`, `currentAssessmentAmount`, `paidAmount` - Counts: `violatorViolationCount`, `violatorInspectionDayCount`, `initialViolationNumber`, `replacedByOrderNumber` - Mine enrichment: `state`, `county`, `district`, `commodityType`, `primarySicCode`/Description, `currentOperatorName`, `currentControllerName`, `mineStatus`, `numberOfEmployees`, `latitude`/`longitude` #### mode=accidents (`mshaAccident`) - Identity: `documentNumber`, `mineId`, `mineName`, `operatorId`/`operatorName`, `controllerId`/`controllerName`, `contractorId`, `subunitCode`/`subunit` - When/where: `accidentDate`, `accidentTime`, `shiftBeginTime`, `calendarYear`/`calendarQuarter`, `fiscalYear`/`fiscalQuarter` - Severity/classification: `degreeOfInjuryCode`/`degreeOfInjury`, `classificationCode`/`classification`, `accidentTypeCode`/`accidentType`, `immediateNotificationCode`/`immediateNotificationType` - Injury detail: `injuryCount`, `natureOfInjury`, `injuredBodyPart`, `injurySource`, `scheduleChargeDays`, `restrictedDutyDays`, `daysLost`, `permanentTransferOrTermination`, `returnToWorkDate` - Person/equipment: `occupation`, `activity`, `totalMiningExperienceYears`, `mineExperienceYears`, `jobExperienceYears`, `undergroundLocation`, `undergroundMiningMethod`, `miningEquipment`, `equipmentManufacturer`, `equipmentModelNumber` - Narrative: `narrative`, `investigationBeginDate`, `closedDocumentNumber` - Mine enrichment: `state`, `county`, `district`, `commodityType`, `mineType`, `mineStatus`, `latitude`/`longitude` #### mode=inspections (`mshaInspection`) - Identity: `eventNumber`, `mineId`, `mineName`, `controllerId`/`controllerName`, `operatorId`/`operatorName` - Activity: `activityCode`, `activity`, `programArea`, `inspectOfficeCode`, `inspectorCount` - Dates: `inspectionBeginDate`, `inspectionEndDate`, `calendarYear`/`calendarQuarter`, `fiscalYear`/`fiscalQuarter` - Scope inspected (booleans): `companyRecordsInspected`, `surfaceUndergroundMineInspected`, `surfaceFacilityInspected`, `refusePilesInspected`, `explosiveStorageInspected`, `outbyAreasInspected`, `majorConstructionInspected`, `shaftsSlopesInspected`, `impoundmentsInspected`, `miscellaneousAreaInspected` - Scope inspected (counts): `activeSectionsInspected`, `idleSectionsInspected`, `shaftSlopeSinkingInspected`, `impoundmentConstructionInspected`, `buildingConstructionSitesInspected`, `draglineOperationsInspected`, `unclassifiedConstructionInspected` - Sampling & hours: `airSampleCount`, `dustSpotSampleCount`, `dustSurveySampleCount`, `respirableDustSampleCount`, `noiseSampleCount`, `otherSampleCount`, `totalInspectionHours`, `totalOnSiteHours`, `totalInspectionSupervisorTraineeHours`, `totalOnSiteSupervisorTraineeHours` - Mine enrichment: `state`, `county`, `district`, `commodityType`, `mineType`, `mineStatus`, `latitude`/`longitude` **Always present on every mode** - `sourceUrl`, `scrapedAt`, `recordType` ### Input | Field | Type | Default | Applies to | Description | |---|---|---|---|---| | `mode` | string | `search` | all | `search` / `byMineId` / `violations` / `accidents` / `inspections` | | `violatorName` | string | – | search, byMineId, violations | Substring match on operator/contractor name | | `mineId` | array | – | byMineId (required), violations, accidents, inspections (optional) | MSHA Mine IDs, e.g. `0800823` | | `mineName` | string | – | all except byMineId | Substring match on mine name | | `state` | string | – | all | US state/territory (2-letter code) | | `commodityType` | string | – | all | `Coal` / `Metal` / `Nonmetal` / `SandAndGravel` / `Stone` | | `coalMetalInd` | string | – | all | `C` (Coal) / `M` (Metal/Nonmetal) | | `district` | string | – | all | MSHA district code, e.g. `C04`, `M3` (13 values) | | `mineStatus` | string | – | all | `Active` / `Abandoned` / `Abandoned and Sealed` / `Intermittent` / `Temporarily Idled` / `NonProducing` / `New Mine` | | `violatorType` | string | – | search, byMineId, violations | `Operator` / `Contractor` | | `violationType` | string | – | search, byMineId, violations | Legal basis, e.g. `104(a)`, `104(d)(1)`, `107(a)` (10 values) | | `citationType` | string | – | search, byMineId, violations | `Citation` / `Order` / `Safeguard` / `Notice` / `Written Notice` | | `caseStatus` | string | – | search, byMineId | `Received` / `Closed` / `Printed` / `Invalid` | | `significantAndSubstantialOnly` | bool | `false` | search, byMineId, violations | Only inspector-flagged S&S violations | | `negligenceLevel` | string | – | violations | `NoNegligence` / `LowNegligence` / `ModNegligence` / `HighNegligence` / `Reckless` | | `likelihood` | string | – | violations | `NoLikelihood` / `Unlikely` / `Reasonably` / `Highly` / `Occurred` | | `injuryIllnessPotential` | string | – | violations | `NoLostDays` / `LostDays` / `Permanent` / `Fatal` | | `contestedOnly` | bool | `false` | violations | Only violations formally contested with FMSHRC | | `specialAssessmentOnly` | bool | `false` | violations | Only violations designated for Special Assessment | | `penaltyAmountMin` / `penaltyAmountMax` | int | – | search, byMineId, violations | Assessed penalty range (USD) | | `issueDateFrom` / `issueDateTo` | string | – | search, byMineId, violations | Issue-date range, `YYYY-MM-DD` | | `mineType` | string | – | all | `Surface` / `Underground` / `Facility` | | `accidentDateFrom` / `accidentDateTo` | string | – | accidents | Accident-date range, `YYYY-MM-DD` | | `degreeOfInjury` | string | – | accidents | 2-digit severity code, e.g. `01` (Fatality) (11 values) | | `accidentClassification` | string | – | accidents | 2-digit hazard-category code, e.g. `07` (Fall of Roof or Back) (28 values) | | `accidentType` | string | – | accidents | 2-digit event code, e.g. `04` (Struck by falling object) (44 values) | | `immediateNotificationType` | string | – | accidents | 2-digit emergency-notification code, e.g. `01` (Death) (13 values) | | `inspectionDateFrom` / `inspectionDateTo` | string | – | inspections | Inspection end-date range, `YYYY-MM-DD` | | `activityCode` | string | – | inspections | Inspection activity code, e.g. `E01` (86 values) | | `inspectOfficeCode` | string | – | inspections | Exact match on the inspecting office code, e.g. `M5852` | | `maxItems` | int | `50` | all | Records to return (1–5000) | The source files are sorted oldest-first and have 270K-3M+ rows depending on mode. Restrictive filters (especially a recent date-from filter) may require scanning most or all of the file, which can take a few minutes — this is expected, not a malfunction. #### Example: Coal violations in West Virginia ```json { "mode": "search", "state": "WV", "commodityType": "Coal", "maxItems": 50 } ```` #### Example: high-penalty significant & substantial violations ```json { "mode": "search", "significantAndSubstantialOnly": true, "penaltyAmountMin": 5000, "maxItems": 50 } ``` #### Example: full violation history for specific mines ```json { "mode": "byMineId", "mineId": ["0800823", "4603341"], "maxItems": 200 } ``` #### Example: recent citations by a specific operator ```json { "mode": "search", "violatorName": "Coal", "issueDateFrom": "2024-01-01", "maxItems": 100 } ``` #### Example: high-negligence, contested citations (mode=violations) ```json { "mode": "violations", "negligenceLevel": "HighNegligence", "contestedOnly": true, "maxItems": 50 } ``` #### Example: fatal accidents in coal mines (mode=accidents) ```json { "mode": "accidents", "coalMetalInd": "C", "degreeOfInjury": "01", "maxItems": 50 } ``` #### Example: regular safety inspections in a district (mode=inspections) ```json { "mode": "inspections", "district": "C04", "activityCode": "E01", "maxItems": 50 } ``` ### Use cases - **Mine safety compliance research** — track an operator's citation and penalty history - **ESG / investor due diligence** — screen mining companies for safety violation patterns before investment - **Journalism & advocacy** — investigate patterns of significant & substantial violations by state or commodity - **Legal & insurance** — pull case-level enforcement history for a specific mine or operator - **Academic research** — analyze mine safety enforcement trends across commodities, states, and time - **Competitive/industry benchmarking** — compare violation rates across operators in the same commodity sector ### FAQ **What is MSHA?** The Mine Safety and Health Administration, a U.S. Department of Labor agency responsible for enforcing safety and health standards at the nation's mines. See [msha.gov](https://www.msha.gov). **How far back does the data go?** From January 1, 2000 to the most recent MSHA data refresh. **How fresh is the data?** MSHA republishes its Open Government Data bulk files on its own schedule (typically at least monthly); each run downloads the latest available file. **Why do some records have penalty-scoring fields (points/ratios) and others don't?** MSHA's point-based penalty formula only applies to `Regular` assessments. `Single` and `Special` assessments (roughly 20% of records) are penalized under a different process and don't carry gravity/negligence points — those fields are simply omitted rather than set to a fake zero. **Is `violatorEndDate` usually missing?** Yes — MSHA's source file marks an ongoing violator relationship with a placeholder end date (`09/09/9999`); this actor treats that as "no end date yet" and omits the field, since the underlying data has no real information there. The same applies to a small number of `violatorStartDate` values using an obviously placeholder date (`07/06/1776`). **Why is there no NAICS code?** MSHA's own taxonomy is SIC-based (`primarySicCode` / `primarySicDescription` / `commodityType`), not NAICS. Rather than invent NAICS mappings MSHA doesn't provide, the actor surfaces MSHA's real classification. **What does `assessCaseNumber` mean vs. `eventNumber`/`violationNumber`?** `eventNumber` identifies the inspection event; `violationNumber` is the unique citation/order number; `assessCaseNumber` is MSHA's penalty-assessment case identifier, which can bundle multiple violations from the same inspection. **Is this affiliated with MSHA or the Department of Labor?** No — this is an independent, third-party actor built on MSHA's public Open Government Data bulk files. **What's the difference between `mode=search`/`byMineId` and `mode=violations`?** `search`/`byMineId` use MSHA's Assessed Violations dataset — the penalty-focused subset of violations that have completed MSHA's assessment process, with the full points-based penalty-scoring breakdown. `mode=violations` uses MSHA's broader Violations dataset — every citation issued, including ones still being processed, with negligence level, likelihood of injury, and injury/illness potential that Assessed Violations doesn't carry. Use `violations` for gravity/negligence analysis; use `search`/`byMineId` for penalty-scoring detail. **Does `mode=inspections` tell me which inspector conducted an inspection?** No — MSHA's public bulk export reports only the inspecting field office code (`inspectOfficeCode`) and a headcount (`inspectorCount`), not individual inspector names. This is a genuine limitation of the source data, not a scraping gap. **Why do some accident records have missing equipment/location fields?** MSHA's Accidents dataset uses literal placeholder text (`"NO VALUE FOUND"`, `"?"`, `"Not Reported"`) when a field doesn't apply — e.g. `undergroundLocation` doesn't apply to a surface-mine accident. This actor omits those placeholders rather than surfacing them as fake data. # Actor input Schema ## `mode` (type: `string`): What to fetch. `search`/`byMineId` use MSHA's Assessed Violations dataset (penalty-focused). `violations` uses MSHA's broader raw Violations dataset (adds negligence/likelihood/gravity detail, including violations still in process). `accidents` and `inspections` are separate MSHA datasets. ## `violatorName` (type: `string`): Case-insensitive substring match on the operator/contractor name cited (mode=search, byMineId, violations). ## `mineId` (type: `array`): MSHA Mine ID numbers (e.g. `0800823`). Required for mode=byMineId. Optional exact-match filter for mode=violations/accidents/inspections. Ignored by mode=search. ## `mineName` (type: `string`): Case-insensitive substring match on the mine name (joined from MSHA's Mines dataset, or direct on mode=violations). Applies to all modes except byMineId. ## `state` (type: `string`): US state/territory where the mine is located (joined from the Mines dataset). All modes. ## `commodityType` (type: `string`): Mine commodity classification (joined from the Mines dataset's PRIMARY\_CANVASS field). This is MSHA's own taxonomy, not NAICS. All modes. ## `coalMetalInd` (type: `string`): Top-level MSHA sector split on the record itself. All modes. ## `district` (type: `string`): MSHA field district code that oversees the mine (joined from the Mines dataset). `C`-prefixed = Coal district, `M`-prefixed = Metal/Nonmetal district. All modes. ## `mineStatus` (type: `string`): Current operating status of the mine (joined from the Mines dataset). All modes. ## `violatorType` (type: `string`): Whether the violation was cited against the mine operator or an independent contractor (mode=search, byMineId, violations). ## `violationType` (type: `string`): Section of the Mine Act under which the citation/order was issued (mode=search, byMineId, violations). ## `citationType` (type: `string`): Whether the issuance is a Citation, Order, Safeguard, Notice, or Written Notice (mode=search, byMineId, violations). ## `caseStatus` (type: `string`): Status of MSHA's penalty assessment case (mode=search, byMineId). ## `significantAndSubstantialOnly` (type: `boolean`): Only include violations flagged by the inspector as reasonably likely to result in a serious injury (mode=search, byMineId, violations). ## `negligenceLevel` (type: `string`): Degree of negligence the inspector assigned to the violator (mode=violations). ## `likelihood` (type: `string`): Inspector's assessment of how likely the cited condition was to result in an injury (mode=violations). ## `injuryIllnessPotential` (type: `string`): Gravity of the injury the inspector determined the violation could cause (mode=violations). ## `contestedOnly` (type: `boolean`): Only include violations the violator formally contested with FMSHRC (mode=violations). ## `specialAssessmentOnly` (type: `boolean`): Only include violations MSHA designated for Special Assessment (a heightened-scrutiny penalty process, bypassing the standard point formula) (mode=violations). ## `penaltyAmountMin` (type: `integer`): Only include violations with a current assessed penalty at or above this amount (mode=search, byMineId, violations). ## `penaltyAmountMax` (type: `integer`): Only include violations with a current assessed penalty at or below this amount (mode=search, byMineId, violations). ## `issueDateFrom` (type: `string`): Only include violations issued on or after this date (mode=search, byMineId, violations). ## `issueDateTo` (type: `string`): Only include violations issued on or before this date (mode=search, byMineId, violations). ## `mineType` (type: `string`): Physical mine type (joined from the Mines dataset, or direct on mode=violations). All modes. ## `accidentDateFrom` (type: `string`): Only include accidents that occurred on or after this date (mode=accidents). ## `accidentDateTo` (type: `string`): Only include accidents that occurred on or before this date (mode=accidents). ## `degreeOfInjury` (type: `string`): Severity classification MSHA assigned to the accident (mode=accidents). ## `accidentClassification` (type: `string`): Circumstance/hazard category MSHA assigned to the accident (mode=accidents). ## `accidentType` (type: `string`): The specific event that directly caused the injury (mode=accidents). ## `immediateNotificationType` (type: `string`): Category of MSHA's immediate/emergency notification requirement the accident triggered (mode=accidents). ## `inspectionDateFrom` (type: `string`): Only include inspections that concluded on or after this date (mode=inspections). ## `inspectionDateTo` (type: `string`): Only include inspections that concluded on or before this date (mode=inspections). ## `activityCode` (type: `string`): MSHA's code for the type of enforcement activity performed (mode=inspections). ## `inspectOfficeCode` (type: `string`): Exact match on the MSHA field office code that conducted the inspection (e.g. `M5852`). MSHA's bulk export does not include individual inspector names, only the office code and inspector count (mode=inspections). ## `maxItems` (type: `integer`): Maximum number of records to return. The source files have millions of rows sorted oldest-first; restrictive/date-recent filters may require scanning most or all of the file, which can take several minutes. ## Actor input object example ```json { "mode": "search", "mineId": [], "significantAndSubstantialOnly": false, "contestedOnly": false, "specialAssessmentOnly": false, "maxItems": 20 } ``` # Actor output Schema ## `violations` (type: `string`): Dataset containing all scraped MSHA records for the selected mode. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "search", "mineId": [], "significantAndSubstantialOnly": false, "contestedOnly": false, "specialAssessmentOnly": false, "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/msha-compliance-action-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "search", "mineId": [], "significantAndSubstantialOnly": False, "contestedOnly": False, "specialAssessmentOnly": False, "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/msha-compliance-action-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "search", "mineId": [], "significantAndSubstantialOnly": false, "contestedOnly": false, "specialAssessmentOnly": false, "maxItems": 20 }' | apify call crawlerbros/msha-compliance-action-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/msha-compliance-action-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MSHA Compliance Action (Assessed Violations) Data Scraper", "description": "Scrape the U.S. Mine Safety and Health Administration's (MSHA) full case-level Assessed Violations enforcement dataset - 3M+ citations and orders since 2000, joined with mine details (state, commodity, operator). Filter by mine, violator, state, commodity, penalty amount, date range, and more.", "version": "1.0", "x-build-id": "jtdLblz7Trtor7O7m" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~msha-compliance-action-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-msha-compliance-action-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~msha-compliance-action-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-msha-compliance-action-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~msha-compliance-action-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-msha-compliance-action-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "byMineId", "violations", "accidents", "inspections" ], "type": "string", "description": "What to fetch. `search`/`byMineId` use MSHA's Assessed Violations dataset (penalty-focused). `violations` uses MSHA's broader raw Violations dataset (adds negligence/likelihood/gravity detail, including violations still in process). `accidents` and `inspections` are separate MSHA datasets.", "default": "search" }, "violatorName": { "title": "Violator / operator name contains", "type": "string", "description": "Case-insensitive substring match on the operator/contractor name cited (mode=search, byMineId, violations)." }, "mineId": { "title": "Mine IDs", "type": "array", "description": "MSHA Mine ID numbers (e.g. `0800823`). Required for mode=byMineId. Optional exact-match filter for mode=violations/accidents/inspections. Ignored by mode=search.", "default": [], "items": { "type": "string" } }, "mineName": { "title": "Mine name contains", "type": "string", "description": "Case-insensitive substring match on the mine name (joined from MSHA's Mines dataset, or direct on mode=violations). Applies to all modes except byMineId." }, "state": { "title": "State", "enum": [ "AK", "AL", "AR", "AS", "AZ", "CA", "CO", "CT", "DE", "FL", "GA", "GU", "HI", "IA", "ID", "IL", "IN", "KS", "KY", "LA", "MA", "MD", "ME", "MI", "MN", "MO", "MP", "MS", "MT", "NC", "ND", "NE", "NH", "NJ", "NM", "NV", "NY", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VA", "VI", "VT", "WA", "WI", "WV", "WY" ], "type": "string", "description": "US state/territory where the mine is located (joined from the Mines dataset). All modes." }, "commodityType": { "title": "Commodity type", "enum": [ "Coal", "Metal", "Nonmetal", "SandAndGravel", "Stone" ], "type": "string", "description": "Mine commodity classification (joined from the Mines dataset's PRIMARY_CANVASS field). This is MSHA's own taxonomy, not NAICS. All modes." }, "coalMetalInd": { "title": "Coal vs. Metal/Nonmetal", "enum": [ "C", "M" ], "type": "string", "description": "Top-level MSHA sector split on the record itself. All modes." }, "district": { "title": "MSHA district", "enum": [ "C03", "C04", "C05", "C07", "C08", "C09", "C10", "M2", "M3", "M4", "M5", "M6", "M7" ], "type": "string", "description": "MSHA field district code that oversees the mine (joined from the Mines dataset). `C`-prefixed = Coal district, `M`-prefixed = Metal/Nonmetal district. All modes." }, "mineStatus": { "title": "Mine status", "enum": [ "Active", "Abandoned", "Abandoned and Sealed", "Intermittent", "Temporarily Idled", "NonProducing", "New Mine" ], "type": "string", "description": "Current operating status of the mine (joined from the Mines dataset). All modes." }, "violatorType": { "title": "Violator type", "enum": [ "Operator", "Contractor" ], "type": "string", "description": "Whether the violation was cited against the mine operator or an independent contractor (mode=search, byMineId, violations)." }, "violationType": { "title": "Violation type (legal basis)", "enum": [ "104(a)", "104(b)", "104(c)", "103(k)", "104(d)(1)", "104(d)(2)", "104(e)(1)", "104(e)(2)", "104(g)(1)", "107(a)" ], "type": "string", "description": "Section of the Mine Act under which the citation/order was issued (mode=search, byMineId, violations)." }, "citationType": { "title": "Citation type", "enum": [ "Citation", "Order", "Safeguard", "Notice", "Written Notice" ], "type": "string", "description": "Whether the issuance is a Citation, Order, Safeguard, Notice, or Written Notice (mode=search, byMineId, violations)." }, "caseStatus": { "title": "Assessment case status", "enum": [ "Received", "Closed", "Printed", "Invalid" ], "type": "string", "description": "Status of MSHA's penalty assessment case (mode=search, byMineId)." }, "significantAndSubstantialOnly": { "title": "Significant & Substantial (S&S) only", "type": "boolean", "description": "Only include violations flagged by the inspector as reasonably likely to result in a serious injury (mode=search, byMineId, violations).", "default": false }, "negligenceLevel": { "title": "Negligence level", "enum": [ "NoNegligence", "LowNegligence", "ModNegligence", "HighNegligence", "Reckless" ], "type": "string", "description": "Degree of negligence the inspector assigned to the violator (mode=violations)." }, "likelihood": { "title": "Likelihood of injury", "enum": [ "NoLikelihood", "Unlikely", "Reasonably", "Highly", "Occurred" ], "type": "string", "description": "Inspector's assessment of how likely the cited condition was to result in an injury (mode=violations)." }, "injuryIllnessPotential": { "title": "Injury/illness potential", "enum": [ "NoLostDays", "LostDays", "Permanent", "Fatal" ], "type": "string", "description": "Gravity of the injury the inspector determined the violation could cause (mode=violations)." }, "contestedOnly": { "title": "Contested only", "type": "boolean", "description": "Only include violations the violator formally contested with FMSHRC (mode=violations).", "default": false }, "specialAssessmentOnly": { "title": "Special assessment only", "type": "boolean", "description": "Only include violations MSHA designated for Special Assessment (a heightened-scrutiny penalty process, bypassing the standard point formula) (mode=violations).", "default": false }, "penaltyAmountMin": { "title": "Minimum penalty amount (USD)", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Only include violations with a current assessed penalty at or above this amount (mode=search, byMineId, violations)." }, "penaltyAmountMax": { "title": "Maximum penalty amount (USD)", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Only include violations with a current assessed penalty at or below this amount (mode=search, byMineId, violations)." }, "issueDateFrom": { "title": "Issued after (YYYY-MM-DD)", "type": "string", "description": "Only include violations issued on or after this date (mode=search, byMineId, violations)." }, "issueDateTo": { "title": "Issued before (YYYY-MM-DD)", "type": "string", "description": "Only include violations issued on or before this date (mode=search, byMineId, violations)." }, "mineType": { "title": "Mine type", "enum": [ "Surface", "Underground", "Facility" ], "type": "string", "description": "Physical mine type (joined from the Mines dataset, or direct on mode=violations). All modes." }, "accidentDateFrom": { "title": "Accident date after (YYYY-MM-DD)", "type": "string", "description": "Only include accidents that occurred on or after this date (mode=accidents)." }, "accidentDateTo": { "title": "Accident date before (YYYY-MM-DD)", "type": "string", "description": "Only include accidents that occurred on or before this date (mode=accidents)." }, "degreeOfInjury": { "title": "Degree of injury", "enum": [ "00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10" ], "type": "string", "description": "Severity classification MSHA assigned to the accident (mode=accidents)." }, "accidentClassification": { "title": "Accident classification", "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "26", "27", "28", "29", "30", "31", "32" ], "type": "string", "description": "Circumstance/hazard category MSHA assigned to the accident (mode=accidents)." }, "accidentType": { "title": "Accident type (event)", "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44" ], "type": "string", "description": "The specific event that directly caused the injury (mode=accidents)." }, "immediateNotificationType": { "title": "Immediate notification type", "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13" ], "type": "string", "description": "Category of MSHA's immediate/emergency notification requirement the accident triggered (mode=accidents)." }, "inspectionDateFrom": { "title": "Inspection end date after (YYYY-MM-DD)", "type": "string", "description": "Only include inspections that concluded on or after this date (mode=inspections)." }, "inspectionDateTo": { "title": "Inspection end date before (YYYY-MM-DD)", "type": "string", "description": "Only include inspections that concluded on or before this date (mode=inspections)." }, "activityCode": { "title": "Inspection activity code", "enum": [ "01", "02", "07", "09", "10", "12", "13", "16", "30", "37", "40", "42", "44", "46", "82", "AAA", "AAB", "ABA", "ABB", "ABC", "ABD", "ABE", "ADA", "ADB", "AEA", "AFA", "AFB", "AFC", "BAA", "BAB", "BAC", "BAD", "BAE", "BAF", "BBA", "BBB", "BBC", "BBD", "BBE", "BBF", "CAA", "CAB", "CBA", "CBB", "CBC", "CBD", "CBE", "CCA", "CCB", "CCC", "CCD", "CCE", "CCF", "CDA", "CDB", "CEA", "CEB", "CEC", "CED", "CEE", "CEF", "CFA", "CFB", "CFC", "E01", "E02", "E03", "E04", "E05", "E06", "E07", "E08", "E15", "E16", "E17", "E18", "E19", "E20", "E21", "E22", "E23", "E24", "E25", "E27", "E28", "E33" ], "type": "string", "description": "MSHA's code for the type of enforcement activity performed (mode=inspections)." }, "inspectOfficeCode": { "title": "Inspecting office code", "type": "string", "description": "Exact match on the MSHA field office code that conducted the inspection (e.g. `M5852`). MSHA's bulk export does not include individual inspector names, only the office code and inspector count (mode=inspections)." }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of records to return. The source files have millions of rows sorted oldest-first; restrictive/date-recent filters may require scanning most or all of the file, which can take several minutes.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```