# Hospital Price Transparency MRF Normalizer (`george.the.developer/hospital-mrf-normalizer`) Actor

Normalize hospital price transparency MRF files into clean payer, code, and negotiated rate rows for builders and buyers.

- **URL**: https://apify.com/george.the.developer/hospital-mrf-normalizer.md
- **Developed by:** [George Kioko](https://apify.com/george.the.developer) (community)
- **Categories:** Business, Developer tools
- **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event + usage

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## Hospital Price Transparency MRF Normalizer

Hospitals now publish price transparency MRF files with payer names, plans, billing codes, and negotiated rates, but the files are usually too large and inconsistent to use directly. CMS added new 2026 template fields and began enforcement for those fields on April 1, 2026, which means hospitals, consultants, TPAs, employers, revenue cycle teams, and data buyers need cleaner feeds now. This Actor turns public hospital MRF files into normalized rows that can go straight into a dataset, warehouse, quoting tool, or benefits product.

### Quick start

Normalize one public hospital MRF:

```bash
curl "https://george-the-developer--hospital-mrf-normalizer.apify.actor/normalize?url=https%3A%2F%2Frequest.cooperhealth.org%2Ffinancial%2F210634462_CooperUniversityHealthCare_standardcharges_update.csv&hospital=Cooper%20University%20Hospital&limit=50" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"
````

Discover MRF links from a hospital pricing page or domain:

```bash
curl "https://george-the-developer--hospital-mrf-normalizer.apify.actor/discover?hospital=cooperhealth.org" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN"
```

### What it returns

Every normalized row uses the same field names, whether the source file is JSON, CSV, or gzip compressed JSON or CSV.

For best results, pass a direct file URL plus the hospital name. Discovery is free and useful for finding likely files, but hospital websites move links often and some publish several facility files from one page. If the file is very large, start with `limit=50`, inspect the dataset, then raise the limit for the full pull. The Actor skips rows that do not have a numeric payer rate because blank contract rows are noise for downstream buyers.

<table>
<tr><th>Field</th><th>Meaning</th></tr>
<tr><td>hospital_id</td><td>Stable slug derived from the hospital name</td></tr>
<tr><td>hospital_name</td><td>Hospital display name from input or source file</td></tr>
<tr><td>provider_npi</td><td>Type 2 NPI when present</td></tr>
<tr><td>billing_code</td><td>CPT, HCPCS, DRG, revenue code, or local code</td></tr>
<tr><td>billing_code_type</td><td>CPT, HCPCS, DRG, MS DRG, APR DRG, EAPG, RC, or LOCAL</td></tr>
<tr><td>billing_code_description</td><td>Plain description of the service</td></tr>
<tr><td>payer_name</td><td>Insurance payer name</td></tr>
<tr><td>plan_name</td><td>Plan name when present</td></tr>
<tr><td>negotiated_rate</td><td>Parsed numeric negotiated dollar rate</td></tr>
<tr><td>negotiated_type</td><td>negotiated, fee schedule, percentage, per diem, or case rate</td></tr>
<tr><td>expiration_date</td><td>Contract expiration date when present</td></tr>
<tr><td>modifiers</td><td>Billing modifiers as an array when present</td></tr>
<tr><td>service_setting</td><td>inpatient, outpatient, both, or null</td></tr>
<tr><td>source_url</td><td>Original MRF URL</td></tr>
<tr><td>last_updated</td><td>ISO timestamp for the row</td></tr>
</table>

### Architecture

```mermaid
graph LR
  A[Input URL or hospital domain] ==> B[Discover]
  B ==> C[Fetch]
  C ==> D[Format detect]
  D ==> E[Stream parse]
  E ==> F[Normalize]
  F ==> G[Apify dataset]
```

The parser probes the first 2 KB of the stream, handles redirects, detects gzip bytes, rejects XML in v1, and caps reads at 1 GB per URL. JSON files are streamed with `stream-json`. CSV files are streamed with `csv-parse`. The Actor does not load full MRF files into memory.

### Pricing

<table>
<tr><th>Event</th><th>Price</th><th>When it fires</th></tr>
<tr><td>actor start</td><td>$0.50</td><td>Once per paid normalize request or batch run</td></tr>
<tr><td>rate row</td><td>$0.002</td><td>Each normalized row pushed to the dataset</td></tr>
<tr><td>normalized bundle</td><td>$0.02</td><td>Each unique provider, billing code, and payer triplet</td></tr>
</table>

Health check literals such as `example.com`, `test@gmail.com`, `stripe.com`, `test`, and `ping` return mocked data and are not billed.

### Positioning

Turquoise Health, Castlight, and similar products are full SaaS dashboards with their own workflows, contracts, and user interfaces. This Actor is different. It gives builders the raw normalized feed so they can plug hospital rates into their own search, quoting, plan design, procurement, or analytics stack without waiting on a sales cycle.

Use this when you want data rows, not another dashboard.

### Use cases

1. TPA shopping engine: compare negotiated rates across hospitals by payer, plan, CPT, and facility.
2. Employer benefit lookup: show members expected negotiated rates for common procedures.
3. Healthcare bluebook clone: build fair price bands from multiple hospital MRF feeds.
4. Revenue cycle denial appeals: pull payer specific rates as support for underpayment review.
5. M and A diligence: inspect payer mix and contract rate exposure across target facilities.

### FAQ

#### Which formats are supported?

JSON, CSV, gzip JSON, and gzip CSV are supported in v1. The parser handles CMS v3 JSON files and common older flat CSV layouts.

#### Does it handle gzip?

Yes. The Actor detects gzip magic bytes and pipes the stream through Node gzip decompression before format detection.

#### What is not supported in v1?

XML MRF files, zip archives, XLSX files, multi file index expansion, and payer allowed amount files are not parsed in v1.

#### Why did my row count come back lower than the limit?

The limit is the number of source rows to scan. Rows with blank codes, blank payers, or non numeric rates are skipped because they do not produce useful normalized output.

#### Can I get a refund for a bad source file?

If the source URL returns unusable data or the Actor fails before pushing rows, open an issue on the Actor page with the run ID and URL. Failed runs and parser bugs are reviewed case by case.

#### Are there rate limits?

Bulk mode accepts up to 10 URLs per request. Keep limits low for first tests, then increase once you confirm the source format.

#### How do I contact the maintainer?

Open an issue on the Apify Actor page with the MRF URL, run ID, and what output you expected.

# Actor input Schema

## `mrfUrl` (type: `string`):

Direct URL to a hospital JSON, CSV, or gzip MRF file.

## `hospitalName` (type: `string`):

Optional hospital name to attach to normalized rows.

## `limit` (type: `integer`):

Maximum normalized rows to return per URL.

## `mode` (type: `string`):

Run mode for batch calls.

## `urls` (type: `array`):

URLs for bulk mode. Maximum 10 URLs.

## Actor input object example

```json
{
  "mrfUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json",
  "hospitalName": "West Mercy Hospital",
  "limit": 100,
  "mode": "normalize"
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("george.the.developer/hospital-mrf-normalizer").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("george.the.developer/hospital-mrf-normalizer").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 george.the.developer/hospital-mrf-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=george.the.developer/hospital-mrf-normalizer",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Hospital Price Transparency MRF Normalizer",
        "description": "Normalize hospital price transparency MRF files into clean payer, code, and negotiated rate rows for builders and buyers.",
        "version": "1.0",
        "x-build-id": "VEsPymMdcdMj1Atqo"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/george.the.developer~hospital-mrf-normalizer/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-george.the.developer-hospital-mrf-normalizer",
                "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/george.the.developer~hospital-mrf-normalizer/runs": {
            "post": {
                "operationId": "runs-sync-george.the.developer-hospital-mrf-normalizer",
                "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/george.the.developer~hospital-mrf-normalizer/run-sync": {
            "post": {
                "operationId": "run-sync-george.the.developer-hospital-mrf-normalizer",
                "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": {
                    "mrfUrl": {
                        "title": "MRF URL",
                        "type": "string",
                        "description": "Direct URL to a hospital JSON, CSV, or gzip MRF file.",
                        "default": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json"
                    },
                    "hospitalName": {
                        "title": "Hospital Name",
                        "type": "string",
                        "description": "Optional hospital name to attach to normalized rows.",
                        "default": "West Mercy Hospital"
                    },
                    "limit": {
                        "title": "Row Limit",
                        "minimum": 1,
                        "maximum": 100000,
                        "type": "integer",
                        "description": "Maximum normalized rows to return per URL.",
                        "default": 100
                    },
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "normalize",
                            "discover",
                            "bulk"
                        ],
                        "type": "string",
                        "description": "Run mode for batch calls.",
                        "default": "normalize"
                    },
                    "urls": {
                        "title": "Bulk URLs",
                        "maxItems": 10,
                        "type": "array",
                        "description": "URLs for bulk mode. Maximum 10 URLs.",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```