CMS Hospital Price Transparency Scraper

Parse hospital standard-charge files mandated by the CMS Hospital Price Transparency rule. 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, and the CMS CSV templates (v2 and v3, tall and wide layouts). Auto-detects the format, so you don't have to.
• CSV files are read as a stream, so a file of any size runs in a few hundred MB of memory and stops downloading as soon as maxItems is reached.
• 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

---

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. Format detection — For JSON the parser inspects the shape and routes to the v3 nested handler (standard_charges[] with payers_information[]) or the v1/v2 flat handler. For CSV it reads the hospital header rows, then the charge header, and handles both the tall layout (one row per payer) and the wide layout (payer and plan in the column names). 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

{
  "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

{
  "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

{
  "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 URL, JSON or CSV. Required for mrf_parse.
hospitalDomain	string	—	discover_and_parse: the hospital's website host, skipping the site lookup.
maxMrfSizeMb	integer	64	discover_and_parse: larger JSON MRF files are reported but not downloaded. CSV files are streamed and have no size limit.
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.

---

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

{
  "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

{
  "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, mrf_discovery for discovery status

Discovery status — one record per hospital (discover_and_parse)

Each hospital in scope gets one mrf_discovery record, so a hospital with no usable file shows up as a row instead of silently producing nothing. Besides the hospital identity fields it carries:

Field	Type	Description
discovery_status	string	found, not_found or error
discovery_reason	string	Why: mrf_parsed, no_domain, no_hpt_file, no_location_match, mrf_format_unsupported, mrf_too_large, mrf_unreachable, ...
domain	string	Hospital website host used
domain_source	string	How the website was found: input, openstreetmap or serp (a web search for the hospital's own site)
hpt_file_url	string	The hospital's cms-hpt.txt URL, when it has one
hpt_http_status	integer	HTTP status of the cms-hpt.txt lookup
location_name	string	The cms-hpt.txt location entry matched to the hospital
mrf_url	string	Discovered MRF URL
mrf_format	string	json, csv, zip, ... json and csv files are parsed into charge rows
mrf_http_status	integer	HTTP status of the MRF probe
mrf_size_bytes	integer	File size when the server reports it
mrf_last_modified	string	Last-Modified header when the server reports it
charge_rows_emitted	integer	Charge rows parsed from this hospital's file in this run

In this mode maxItems counts status records and charge rows together. Use hospitalCcn with hospitalDomain to run one hospital.

---

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 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. No hidden fees. Parsing a typical hospital MRF (a few thousand rows) costs cents in platform fees.

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 another file format (ZIP or Excel MRFs) or a feature that is missing? Open an issue 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