# MSHA Mining Safety & Health Data (`ryanclinton/msha-mining-safety`) Actor Comprehensive mining safety intelligence from the **Mine Safety and Health Administration (MSHA)**. Searches 86,000+ mines across the US and joins data from **5 DOL API datasets** — mines, violations, inspections, accidents, and assessments — with automated **risk scoring** based on fatalities, S... - **URL**: https://apify.com/ryanclinton/msha-mining-safety.md - **Developed by:** [ryan clinton](https://apify.com/ryanclinton) (community) - **Categories:** Other, AI - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $30.00 / 1,000 result returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 Mining Safety & Health Data Comprehensive mining safety intelligence from the **Mine Safety and Health Administration (MSHA)**. Searches 86,000+ mines across the US and joins data from **5 DOL API datasets** — mines, violations, inspections, accidents, and assessments — with automated **risk scoring** based on fatalities, S&S violations, withdrawal orders, and penalty history. ### What It Does This actor queries the DOL Open Data Portal API to build rich mine safety profiles: 1. **Searches mines** by name, operator, controller, state, type (Coal/Metal), status, or commodity 2. **Joins violations** — citations, orders, safeguards with S&S flags, negligence levels, and penalties 3. **Joins inspections** — regular, spot, complaint, impact inspections with violations found and on-site hours 4. **Joins accidents** — fatalities, injuries, lost workdays with narratives and classifications 5. **Calculates risk scores** — weighted algorithm considering fatalities (40pts), orders (10pts each), S&S violations (3pts each), high negligence (8pts each), large penalties, and violation-to-employee ratios ### Key Features - **Multi-dataset joining** — Automatically correlates data across 5 MSHA datasets by mine_id - **Risk scoring** — Four-tier risk assessment (Critical/High/Medium/Low) with detailed risk factor breakdown - **Comprehensive summaries** — Violation, inspection, and accident summaries with breakdowns by type - **Flexible filtering** — Search by any combination of mine name, operator, state, type, commodity, date range - **Rate limit handling** — Exponential backoff with staggered parallel requests to respect DOL API limits - **Dry run mode** — Returns realistic sample data without API calls (default behavior) ### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `apiKey` | string | — | DOL API key ([register free](https://dataportal.dol.gov/registration)) | | `dryRun` | boolean | true | Return sample data without API calls | | `mineName` | string | — | Search by mine name (partial match) | | `operatorName` | string | — | Search by operator name (partial match) | | `controllerName` | string | — | Search by controller/parent company | | `mineId` | string | — | Exact MSHA mine ID (7 digits) | | `state` | string | — | Two-letter state code (WV, WY, PA, etc.) | | `mineType` | string | — | `C` = Coal, `M` = Metal/Non-Metal | | `mineStatus` | string | — | Active, Abandoned, NonProducing, etc. | | `commodity` | string | — | Primary commodity (Bituminous, Gold, Limestone, etc.) | | `dateFrom` | string | — | Filter related data from date (YYYY-MM-DD) | | `dateTo` | string | — | Filter related data to date (YYYY-MM-DD) | | `includeViolations` | boolean | true | Join violation records | | `includeInspections` | boolean | true | Join inspection records | | `includeAccidents` | boolean | true | Join accident records | | `maxResults` | integer | 100 | Max mines to return (1-5000) | | `maxViolationsPerMine` | integer | 100 | Max violations per mine (1-1000) | | `maxInspectionsPerMine` | integer | 50 | Max inspections per mine (1-500) | | `maxAccidentsPerMine` | integer | 50 | Max accidents per mine (1-500) | ### Output Format Each mine record includes: ```json { "mineId": "4601432", "mineName": "EAGLE BUTTE MINE", "mineType": "Coal", "mineClassification": "Surface", "operatorName": "EAGLE SPECIALTY MATERIALS LLC", "controllerName": "EAGLE SPECIALTY MATERIALS LLC", "state": "WY", "county": "CAMPBELL", "latitude": 44.21, "longitude": -105.38, "status": "Active", "employeeCount": 320, "hoursPerYear": 640000, "sicDescription": "Bituminous Coal and Lignite Surface Mining", "primaryCommodity": "Bituminous", "violations": [ { "violationNumber": "8765432", "section": "77.1607(b)", "sectionTitle": "Loading and haulage - moving equipment", "citationOrderSafeguard": "Citation", "significantAndSubstantial": true, "negligence": "Moderate", "proposedPenalty": 4416 } ], "violationSummary": { "total": 2, "citations": 1, "orders": 1, "significantAndSubstantial": 2, "totalProposedPenalties": 27872, "byNegligence": { "Moderate": 1, "High": 1 } }, "inspections": [ { "eventNumber": "E001234", "beginDate": "2024-11-10", "inspectionTypeDescription": "Regular Safety/Health", "violationsFound": 2, "onSiteHours": 48 } ], "accidents": [ { "accidentDate": "2024-06-12", "degreeOfInjuryDescription": "Days Away From Work (DAFW)", "classification": "Powered Haulage", "daysLost": 45, "narrative": "Employee was struck by a loaded haul truck..." } ], "riskScore": 37, "riskLevel": "Medium", "riskFactors": [ "1 withdrawal order(s) (+10)", "2 S&S violation(s) (+6)", "1 high negligence violation(s) (+8)" ] } ```` ### Risk Scoring Algorithm | Factor | Points | Cap | |--------|--------|-----| | Fatality | +40 each | None | | Permanent disability | +20 each | None | | Withdrawal order | +10 each | 80 | | S\&S violation | +3 each | 60 | | High negligence / Reckless disregard | +8 each | 40 | | Penalties > $100K | +25 | — | | Penalties > $50K | +15 | — | | High violation volume (>50) | +15 | — | | Contested violations > 10 | +10 | — | | Days lost > 100 | +15 | — | | Violation/employee ratio > 2 | +20 | — | | Violation/employee ratio > 1 | +10 | — | **Risk levels:** Critical (≥100) · High (≥60) · Medium (≥30) · Low (<30) ### Example Searches **Find all active coal mines in West Virginia:** ```json { "apiKey": "YOUR_KEY", "dryRun": false, "state": "WV", "mineType": "C", "mineStatus": "Active", "maxResults": 200 } ``` **Look up a specific mine with full history:** ```json { "apiKey": "YOUR_KEY", "dryRun": false, "mineId": "4601432", "maxViolationsPerMine": 500, "maxInspectionsPerMine": 200, "maxAccidentsPerMine": 200 } ``` **Search gold mines with recent violations only:** ```json { "apiKey": "YOUR_KEY", "dryRun": false, "commodity": "Gold", "mineType": "M", "dateFrom": "2024-01-01", "maxResults": 50 } ``` **Find mines by operator:** ```json { "apiKey": "YOUR_KEY", "dryRun": false, "operatorName": "PEABODY", "includeAccidents": true, "maxResults": 100 } ``` ### Data Sources This actor queries 5 datasets from the [DOL Open Data Portal](https://dataportal.dol.gov/): | Dataset | Records | Updated | Description | |---------|---------|---------|-------------| | Mines | 86,000+ | Weekly | All coal and metal/non-metal mines since 1970 | | Violations | Millions | Weekly | Citations, orders, safeguards from inspections | | Inspections | Millions | Weekly | Every MSHA inspection since 1983 | | Accidents | 300,000+ | Weekly | Injuries, illnesses, fatalities since 1983 | | Assessed Violations | Millions | Weekly | Penalty assessments for violations since 1995 | Additional supporting datasets available: contractor/operator employment, controller history, commodity lookup. ### API Key Register for a **free** DOL API key at [dataportal.dol.gov/registration](https://dataportal.dol.gov/registration). The key provides access to all DOL Open Data Portal datasets (MSHA, OSHA, WHD, etc.). ### Use Cases - **Mining company due diligence** — Assess safety records before acquisition or investment - **Insurance underwriting** — Evaluate mining operations for workers' comp and liability policies - **Regulatory compliance** — Monitor violation trends and inspection frequency - **Investigative journalism** — Research mine safety records and fatality patterns - **Legal research** — Find citation and penalty history for mining litigation - **ESG analysis** — Environmental, Social, Governance scoring for mining companies - **Government oversight** — Track enforcement patterns across mining districts ### Technical Notes - The DOL API has aggressive rate limits. The actor uses 500ms delays between requests and exponential backoff on 429 responses. - Violation, inspection, and accident fetches are staggered (1s apart) to avoid concurrent rate limiting. - Mines are sorted by employee count descending (largest mines first) when no specific search criteria is provided. - Results are sorted by risk score descending after processing. - The `mine_id` field is the primary join key across all datasets. # Actor input Schema ## `apiKey` (type: `string`): Your DOL Open Data Portal API key. Register free at https://dataportal.dol.gov/registration ## `dryRun` (type: `boolean`): Return sample data without calling the API. Default: true (unless apiKey provided) ## `mineName` (type: `string`): Search by mine name (partial match). e.g., 'EAGLE BUTTE' or 'NORTH ANTELOPE' ## `operatorName` (type: `string`): Search by current mine operator (partial match). e.g., 'PEABODY' or 'ARCH' ## `controllerName` (type: `string`): Search by current mine controller/parent company (partial match) ## `mineId` (type: `string`): Exact MSHA mine identification number (7 digits). e.g., '4601432' ## `state` (type: `string`): Two-letter state abbreviation. e.g., 'WV', 'WY', 'PA', 'KY' ## `mineType` (type: `string`): Coal or Metal/Non-Metal ## `mineStatus` (type: `string`): Filter by mine operational status ## `commodity` (type: `string`): Search by primary commodity/SIC description. e.g., 'Bituminous', 'Gold', 'Limestone', 'Sand and Gravel' ## `dateFrom` (type: `string`): Filter violations/inspections/accidents from this date (YYYY-MM-DD) ## `dateTo` (type: `string`): Filter violations/inspections/accidents up to this date (YYYY-MM-DD) ## `includeViolations` (type: `boolean`): Join violation records for each mine ## `includeInspections` (type: `boolean`): Join inspection records for each mine ## `includeAccidents` (type: `boolean`): Join accident/injury records for each mine ## `maxResults` (type: `integer`): Maximum number of mines to return (1-5000) ## `maxViolationsPerMine` (type: `integer`): Maximum violations to fetch per mine (1-1000) ## `maxInspectionsPerMine` (type: `integer`): Maximum inspections to fetch per mine (1-500) ## `maxAccidentsPerMine` (type: `integer`): Maximum accident records to fetch per mine (1-500) ## Actor input object example ```json { "dryRun": true, "includeViolations": true, "includeInspections": true, "includeAccidents": true, "maxResults": 100, "maxViolationsPerMine": 100, "maxInspectionsPerMine": 50, "maxAccidentsPerMine": 50 } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("ryanclinton/msha-mining-safety").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 = {} # Run the Actor and wait for it to finish run = client.actor("ryanclinton/msha-mining-safety").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 '{}' | apify call ryanclinton/msha-mining-safety --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ryanclinton/msha-mining-safety", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MSHA Mining Safety & Health Data", "description": "Comprehensive mining safety intelligence from the **Mine Safety and Health Administration (MSHA)**. Searches 86,000+ mines across the US and joins data from **5 DOL API datasets** — mines, violations, inspections, accidents, and assessments — with automated **risk scoring** based on fatalities, S...", "version": "0.1", "x-build-id": "TA0RmNiPvwqDAPUq4" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~msha-mining-safety/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-msha-mining-safety", "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/ryanclinton~msha-mining-safety/runs": { "post": { "operationId": "runs-sync-ryanclinton-msha-mining-safety", "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/ryanclinton~msha-mining-safety/run-sync": { "post": { "operationId": "run-sync-ryanclinton-msha-mining-safety", "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", "properties": { "apiKey": { "title": "DOL API Key", "type": "string", "description": "Your DOL Open Data Portal API key. Register free at https://dataportal.dol.gov/registration" }, "dryRun": { "title": "Dry Run", "type": "boolean", "description": "Return sample data without calling the API. Default: true (unless apiKey provided)", "default": true }, "mineName": { "title": "Mine Name", "type": "string", "description": "Search by mine name (partial match). e.g., 'EAGLE BUTTE' or 'NORTH ANTELOPE'" }, "operatorName": { "title": "Operator Name", "type": "string", "description": "Search by current mine operator (partial match). e.g., 'PEABODY' or 'ARCH'" }, "controllerName": { "title": "Controller Name", "type": "string", "description": "Search by current mine controller/parent company (partial match)" }, "mineId": { "title": "Mine ID", "type": "string", "description": "Exact MSHA mine identification number (7 digits). e.g., '4601432'" }, "state": { "title": "State", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "type": "string", "description": "Two-letter state abbreviation. e.g., 'WV', 'WY', 'PA', 'KY'" }, "mineType": { "title": "Mine Type", "enum": [ "C", "M" ], "type": "string", "description": "Coal or Metal/Non-Metal" }, "mineStatus": { "title": "Mine Status", "enum": [ "Active", "Abandoned", "Abandoned and Sealed", "Intermittent", "NonProducing", "New Mine", "Temporarily Idled" ], "type": "string", "description": "Filter by mine operational status" }, "commodity": { "title": "Commodity", "type": "string", "description": "Search by primary commodity/SIC description. e.g., 'Bituminous', 'Gold', 'Limestone', 'Sand and Gravel'" }, "dateFrom": { "title": "Date From", "type": "string", "description": "Filter violations/inspections/accidents from this date (YYYY-MM-DD)" }, "dateTo": { "title": "Date To", "type": "string", "description": "Filter violations/inspections/accidents up to this date (YYYY-MM-DD)" }, "includeViolations": { "title": "Include Violations", "type": "boolean", "description": "Join violation records for each mine", "default": true }, "includeInspections": { "title": "Include Inspections", "type": "boolean", "description": "Join inspection records for each mine", "default": true }, "includeAccidents": { "title": "Include Accidents", "type": "boolean", "description": "Join accident/injury records for each mine", "default": true }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of mines to return (1-5000)", "default": 100 }, "maxViolationsPerMine": { "title": "Max Violations Per Mine", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum violations to fetch per mine (1-1000)", "default": 100 }, "maxInspectionsPerMine": { "title": "Max Inspections Per Mine", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum inspections to fetch per mine (1-500)", "default": 50 }, "maxAccidentsPerMine": { "title": "Max Accidents Per Mine", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum accident records to fetch per mine (1-500)", "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 } } } } } } } } } } ```