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, v3 CSV dictionary, official examples, v3 schema. 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.