# Hospital Price Transparency File Normalizer (`afkdigital/hospital-price-transparency-file-normalizer`) Actor

Normalize CMS v3 hospital price transparency JSON or CSV MRFs to traceable records. 100 MB / 50,000 rows per file; $0.50 per successful file.

- **URL**: https://apify.com/afkdigital/hospital-price-transparency-file-normalizer.md
- **Developed by:** [AFK Digital](https://apify.com/afkdigital) (community)
- **Categories:** Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / successfully processed hospital mrf

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hospital Price Transparency File Normalizer

Normalize CMS **Hospital Price Transparency** standard charge machine-readable files (MRFs) in **v3.0.0 JSON, CSV Tall, or CSV Wide** format. Files declaring v3.0.0 are decoded as UTF-8, with a Windows-1252 fallback for published CSVs with invalid UTF-8 bytes; undecodable bytes are replaced and should be checked against the source. The source is a user-supplied public HTTPS URL or a file uploaded to an Apify key-value store. This Actor does not parse insurer Transparency in Coverage MRFs, proprietary hospital formats, or older CMS versions.

### Input

Supply exactly one of `fileUrl` and `uploadedFile`. Uploaded files may be private Apify key-value store records (read with the run-scoped Apify token), or public HTTPS URLs; API callers may also supply a base64 data URL or `{"base64Data":"..."}` directly, but large base64 inputs may exceed Apify's own input size limit. `serviceCodes` and `chargeTypes` filter exact values. `payerFilter` and `planFilter` match case-insensitive substrings and exclude charges without a payer. `maxRows` defaults to 1,000, maximum 50,000.

### Output

Each dataset item contains `hospital_name`, `hospital_identifier` (first Type 2 NPI when present, otherwise state:license), `service_code`, `code_type`, `description`, `payer`, `plan`, `charge_type`, `amount`, `currency`, `setting`, `source_file_date`, `source_row`, plus `source_url` (query parameters removed to protect tokens), `raw_value`, and `value_state`. The dataset exports to JSON or CSV in Apify. `source_row` is a one-based CSV line and column or a zero-based JSON pointer. Multiple billing codes for one service produce separate records.

Percentage and algorithm charge rows retain the original expression in `raw_value` and have `amount=null`, `currency=null`. The dollar-valued median and percentiles are separate historical allowed amount rows; they are not substituted for a negotiated percentage or algorithm. A numeric zero is an actual value with `value_state=present`; `-1` / `N/A` means `not_applicable`; missing/empty charge fields do not produce records. A standard charge is **not** a guaranteed patient out-of-pocket payment.

See the `SUMMARY` key in the default key-value store: `complete=false` explicitly marks truncated matching output, and `records_written` gives its actual count. Reaching `maxRows` exactly with no additional matching record remains complete.

### Limits and pricing

100 MB maximum downloaded bytes **and** 100 MB maximum decompressed bytes (gzip and single-entry unencrypted ZIP supported); at most 50,000 output records; HTTPS port 443 and public IPs only, with redirects revalidated and DNS pinned. 120-second download time limit. Execution and Apify platform resource costs vary with input size. Target Store pay-per-event price: **$0.50 per successfully processed file**; failed and malformed files produce no paid event. Processing capped by maxRows counts as successful **limited** output, disclosed in SUMMARY. No actor-start or dataset-item charge should be configured. Local SDK tests do not establish the actual Store price; verify the Console pricing before public release.

CMS sources: [v3 JSON dictionary](https://github.com/CMSgov/hospital-price-transparency/blob/master/documentation/JSON/README.md), [v3 CSV dictionary](https://github.com/CMSgov/hospital-price-transparency/blob/master/documentation/CSV/README.md), [official examples](https://github.com/CMSgov/hospital-price-transparency/tree/master/examples), [v3 schema](https://github.com/CMSgov/hospital-price-transparency/blob/master/documentation/JSON/schemas/V3.0.0_Hospital_price_transparency_schema.json). These CMS examples represent a fictional hospital; they are schema tests, not observations of real provider prices.

**No medical, billing, legal or reimbursement advice.** Verify every charge at its source and with the hospital and insurer before using it for decisions.

# Actor input Schema

## `fileUrl` (type: `string`):

Public HTTPS CMS hospital price transparency v3.0.0 MRF; 100 MB downloaded and uncompressed limit.

## `uploadedFile` (type: `string`):

Upload a file into Apify key-value storage, or provide its public HTTPS URL. Use either this field or fileUrl.

## `serviceCodes` (type: `array`):

Exact CPT, HCPCS, DRG or other service code matches.

## `payerFilter` (type: `string`):

Case-insensitive substring match; excludes non-payer charges.

## `planFilter` (type: `string`):

Case-insensitive substring match; excludes non-payer charges.

## `chargeTypes` (type: `array`):

Omit to include all present charges.

## `maxRows` (type: `integer`):

Hard cap 50,000. If more matching records exist, SUMMARY.complete=false.

## Actor input object example

```json
{
  "fileUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json",
  "maxRows": 1000
}
```

# Actor output Schema

## `records` (type: `string`):

No description

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

// Prepare Actor input
const input = {
    "fileUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json"
};

// Run the Actor and wait for it to finish
const run = await client.actor("afkdigital/hospital-price-transparency-file-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 = { "fileUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json" }

# Run the Actor and wait for it to finish
run = client.actor("afkdigital/hospital-price-transparency-file-normalizer").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "fileUrl": "https://raw.githubusercontent.com/CMSgov/hospital-price-transparency/master/examples/JSON/v3_json_format_example.json"
}' |
apify call afkdigital/hospital-price-transparency-file-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,afkdigital/hospital-price-transparency-file-normalizer"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YNfv40simre1dkdEZ/builds/fCXDr3QZtYStvXPaj/openapi.json