# CMS Hospital Price Transparency Scraper (`jungle_synthesizer/cms-hospital-price-transparency-scraper`) Actor Extract hospital standard charges from CMS-mandated machine-readable files (MRF). Parses CMS v1/v2/v3 JSON schemas into rows by billing code (CPT, HCPCS, MS-DRG, NDC) and payer/plan. Fetches hospital identity from the CMS enrollment dataset. Filter by state, CCN, code type, billing code, or payer. - **URL**: https://apify.com/jungle\_synthesizer/cms-hospital-price-transparency-scraper.md - **Developed by:** [BowTiedRaccoon](https://apify.com/jungle_synthesizer) (community) - **Categories:** Business, Other, Developer tools - **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — 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 ## CMS Hospital Price Transparency Scraper Parse hospital standard-charge files mandated by the [CMS Hospital Price Transparency rule](https://www.cms.gov/priorities/key-initiatives/hospital-price-transparency). Returns structured rows by billing code (CPT, HCPCS, MS-DRG, APR-DRG, RC, NDC) and payer/plan, with gross charges, cash-discount prices, negotiated dollar amounts, negotiated percentages, and de-identified min/max rates. Also fetches hospital identity records (CCN, NPI, address) for ~6,000 US hospitals from the CMS enrollment API. *** ### CMS Hospital Price Transparency Scraper Features - Parses CMS JSON MRF schemas v1, v2, and v3. Auto-detects the version, so you don't have to. - Returns negotiated rates by payer and plan — dollar, percentage, and algorithm-based methodologies - Includes gross charge, cash-discount, estimated allowed amount, and de-identified min/max in every row - Three modes — `mrf_parse` for a single file, `hospital_list` for CMS enrollment, `discover_and_parse` for the combined pipeline - Filter by state, CCN, billing-code system, specific code, or payer name substring - No proxy required — CMS APIs and most hospital MRFs are publicly reachable *** ### Who Uses Hospital Price Transparency Data? - **Price-comparison startups** — Build patient-facing tools on actual negotiated rates instead of survey data - **Self-funded employers** — Pull payer-specific rates by code to benchmark before contract renegotiation - **Benefits consultants** — Analyze plan-by-plan variation across hospital networks for client RFPs - **Healthcare journalists** — Investigate pricing disparities. The data is public — somebody just has to parse it. - **Healthcare data vendors** — Join MRF charge data to the CMS enrollment registry to enrich existing hospital intelligence products *** ### How the CMS Hospital Price Transparency Scraper Works 1. **Pick a mode** — `mrf_parse` takes a single MRF URL. `hospital_list` walks the CMS enrollment dataset. `discover_and_parse` runs both. 2. **Schema detection** — The parser inspects the JSON shape and routes to the v3 nested handler (`standard_charges[]` with `payers_information[]`) or the v1/v2 flat handler. No configuration. 3. **Filtering** — Code-type, billing-code, payer-substring, and state filters apply during parsing, so only matching rows reach output. Cheaper than post-filtering. 4. **Export** — One record per payer/plan/billing-code/setting combination. That's the granularity the CMS rule requires, and it's what makes the data joinable downstream. *** ### Input #### Parse a single MRF ```json { "mode": "mrf_parse", "mrfUrl": "https://example-hospital.com/standard-charges.json", "billingCodeType": "CPT", "maxItems": 1000, "sp_intended_usage": "Rate comparison for employer plan negotiation", "sp_improvement_suggestions": "None" } ``` #### Pull hospital enrollment records ```json { "mode": "hospital_list", "stateFilter": "TX", "maxItems": 500, "sp_intended_usage": "Build a TX hospital registry", "sp_improvement_suggestions": "None" } ``` #### Filter to one billing code across payers ```json { "mode": "mrf_parse", "mrfUrl": "https://example-hospital.com/standard-charges.json", "billingCodeType": "CPT", "billingCode": "70551", "maxItems": 0 } ``` | Field | Type | Default | Description | |-------|------|---------|-------------| | mode | string | `mrf_parse` | `mrf_parse`, `hospital_list`, or `discover_and_parse`. | | mrfUrl | string | CMS example | MRF JSON URL. Required for `mrf_parse` and `discover_and_parse`. | | stateFilter | string | — | Two-letter state code. Filters `hospital_list` results. | | hospitalCcn | string | — | CMS Certification Number for a single hospital. | | billingCodeType | string | — | `CPT`, `HCPCS`, `MS-DRG`, `APR-DRG`, `RC`, `NDC`, or `Internal`. Empty = all. | | billingCode | string | — | Specific code to filter (e.g. `70551`). | | payerFilter | string | — | Case-insensitive payer-name substring. | | maxItems | integer | 15 | Cap on records. `0` = unlimited. | | proxyConfiguration | object | none | Proxy settings. Off by default. | *** ### CMS Hospital Price Transparency Scraper Output Fields The output schema is shared between modes. Charge fields are populated for `charge_row` records and `null`/empty for `hospital_info` records. Use `record_type` to distinguish. #### MRF parse — one row per payer/plan/code ```json { "hospital_name": "EXAMPLE REGIONAL MEDICAL CENTER", "mrf_url": "https://example-hospital.com/standard-charges.json", "mrf_version": "3.0.0", "mrf_last_updated": "2025-01-15", "billing_code": "70551", "billing_code_type": "CPT", "description": "MRI Brain without contrast", "payer_name": "Aetna", "plan_name": "Aetna PPO Standard", "setting": "outpatient", "methodology": "fee schedule", "standard_charge_gross": 4200, "standard_charge_discounted_cash": 1890, "standard_charge_negotiated_dollar": 1240, "standard_charge_negotiated_percentage": null, "standard_charge_negotiated_algorithm": "", "standard_charge_min": 980, "standard_charge_max": 1600, "estimated_amount": 1240, "additional_payer_notes": "", "record_type": "charge_row" } ``` #### Hospital list — one row per hospital ```json { "hospital_name": "MEMORIAL HOSPITAL OF LARAMIE COUNTY", "hospital_ccn": "530012", "hospital_npi": "1568469223", "hospital_address": "214 E 23RD ST", "hospital_city": "CHEYENNE", "hospital_state": "WY", "hospital_zip": "82001", "record_type": "hospital_info" } ``` | Field | Type | Description | |-------|------|-------------| | hospital\_name | string | Hospital name | | hospital\_ccn | string | CMS Certification Number | | hospital\_npi | string | National Provider Identifier | | hospital\_address | string | Street address | | hospital\_city | string | City | | hospital\_state | string | Two-letter state code | | hospital\_zip | string | ZIP code | | mrf\_url | string | Source machine-readable file URL | | mrf\_version | string | CMS schema version (e.g. `3.0.0`) | | mrf\_last\_updated | string | Date the MRF was last updated (from file header) | | billing\_code | string | Billing code (e.g. `70551`) | | billing\_code\_type | string | Code system: CPT, HCPCS, MS-DRG, APR-DRG, RC, NDC, Internal | | description | string | Service or item description | | payer\_name | string | Payer name | | plan\_name | string | Plan name | | setting | string | inpatient, outpatient, or both | | methodology | string | Rate methodology (fee schedule, percent of total billed charges, etc.) | | standard\_charge\_gross | number | Gross / chargemaster price | | standard\_charge\_discounted\_cash | number | Cash / self-pay discount price | | standard\_charge\_negotiated\_dollar | number | Negotiated dollar amount | | standard\_charge\_negotiated\_percentage | number | Negotiated percentage of gross | | standard\_charge\_negotiated\_algorithm | string | Algorithm description when rate is formula-based | | standard\_charge\_min | number | De-identified minimum negotiated charge | | standard\_charge\_max | number | De-identified maximum negotiated charge | | estimated\_amount | number | Estimated allowed amount | | additional\_payer\_notes | string | Additional payer or plan notes | | record\_type | string | `charge_row` for MRF data, `hospital_info` for enrollment data | *** ### FAQ #### How do I scrape hospital prices from CMS machine-readable files? CMS Hospital Price Transparency Scraper handles it in `mrf_parse` mode. Supply the MRF URL in `mrfUrl`, set optional filters, and run. The parser auto-detects v1/v2/v3 schema and outputs one row per payer/plan/billing-code combination. #### Where do I find hospital MRF URLs? CMS does not publish a single index of every hospital's file. Most hospitals link to their MRF from a "price transparency" or "standard charges" page on their own site. The [CMS Hospital Price Transparency enforcement dataset](https://data.cms.gov/hospital-price-transparency) tracks compliance but doesn't reliably include direct file links. Aggregators like Dolthub's hospital-price-transparency project and Turquoise Health publish compiled URL lists. #### What billing code types does this scraper support? CMS Hospital Price Transparency Scraper supports every code system in the CMS standard: CPT, HCPCS, MS-DRG, APR-DRG, Revenue Code (RC), NDC, and Internal. Filter via `billingCodeType`, or leave it blank to get everything. #### How much does this actor cost to run? CMS Hospital Price Transparency Scraper uses pay-per-event pricing on the `default_2603_basic` profile at a 1.0x coefficient. No proxy fees. Parsing a typical hospital MRF (a few thousand rows) costs cents in platform fees. #### Does this actor need proxies? CMS Hospital Price Transparency Scraper runs proxy-free by default. CMS data APIs and most hospital MRF hosts accept public traffic without rate-limiting. The `proxyConfiguration` field is exposed if a specific hospital's host turns out to be sensitive — most don't. #### Can I filter to a single hospital? CMS Hospital Price Transparency Scraper accepts `hospitalCcn` to filter `hospital_list` mode to one CMS Certification Number. For MRF parsing, point `mrfUrl` directly at that hospital's published file. *** ### Need More Features? Need CSV MRF support, streaming parse for very large files, or auto-discovery of MRF URLs from a hospital domain? [Open an issue](https://console.apify.com/actors/issues) or get in touch. ### Why Use CMS Hospital Price Transparency Scraper? - **Handles every CMS schema** — v1, v2, and v3 are all parsed by the same actor with no config. Most one-off scripts pick one and break on the rest. - **Joinable output** — Charge rows and hospital enrollment records share the same schema and overlap on `hospital_ccn`, so you can join them in SQL without an intermediate ETL step. - **Filter at parse time** — Code-type, billing-code, and payer filters apply while the file is being read, which keeps datasets small when you only care about one procedure. *** **Further reading:** [NPI Database Download: How to Get Healthcare Provider Data in Bulk](https://orbtop.com/articles/npi-database-download-provider-data/) # Actor input Schema ## `sp_intended_usage` (type: `string`): Please describe how you plan to use the data extracted by this crawler. ## `sp_improvement_suggestions` (type: `string`): Provide any feedback or suggestions for improvements. ## `sp_contact` (type: `string`): Provide your email address so we can get in touch with you. ## `mode` (type: `string`): hospital\_list returns hospital enrollment data from CMS. mrf\_parse fetches and parses a single MRF URL you supply. discover\_and\_parse combines hospital list with MRF parsing. ## `mrfUrl` (type: `string`): Machine-readable file URL to fetch and parse. Required for mrf\_parse mode. Supports JSON CMS v1/v2/v3 schema. ## `stateFilter` (type: `string`): Two-letter state code (e.g. CA, TX). Filters hospital list results. Leave blank for all states. ## `hospitalCcn` (type: `string`): CMS Certification Number to filter to a single hospital. Leave blank for all. ## `billingCodeType` (type: `string`): Filter charge rows by billing code system. Leave blank for all. ## `billingCode` (type: `string`): Specific billing code to filter (e.g. 70551 for CPT Brain MRI). Leave blank for all. ## `payerFilter` (type: `string`): Filter charge rows by payer name substring (case-insensitive). Leave blank for all. ## `maxItems` (type: `integer`): Maximum charge rows or hospital records to return. 0 = unlimited. ## Actor input object example ```json { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "mode": "mrf_parse", "mrfUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json", "maxItems": 15 } ``` # 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 = { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "mode": "mrf_parse", "mrfUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json", "stateFilter": "", "hospitalCcn": "", "billingCodeType": "", "billingCode": "", "payerFilter": "", "maxItems": 15 }; // Run the Actor and wait for it to finish const run = await client.actor("jungle_synthesizer/cms-hospital-price-transparency-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 = { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "mode": "mrf_parse", "mrfUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json", "stateFilter": "", "hospitalCcn": "", "billingCodeType": "", "billingCode": "", "payerFilter": "", "maxItems": 15, } # Run the Actor and wait for it to finish run = client.actor("jungle_synthesizer/cms-hospital-price-transparency-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 '{ "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "mode": "mrf_parse", "mrfUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json", "stateFilter": "", "hospitalCcn": "", "billingCodeType": "", "billingCode": "", "payerFilter": "", "maxItems": 15 }' | apify call jungle_synthesizer/cms-hospital-price-transparency-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jungle_synthesizer/cms-hospital-price-transparency-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/9CDfe4XXm9uboo5y1/builds/oy2T7uPAhaDIYIIES/openapi.json