# Distill > Distill sells pre-computed answers to narrow factual questions to AI agents, per call, over x402 (HTTP 402 and a USDC payment on Base). Every answer carries its sources, an as_of time, a computed confidence and the method version that produced it. No account, API key or signup. ## How to pay Paid routes use x402 v2. Call the route; it answers 402 with the payment requirements in the `PAYMENT-REQUIRED` header (base64 JSON, also the body): USDC on Base, the exact amount (or, for `upto` routes, a ceiling). Retry with the signed payment payload in `PAYMENT-SIGNATURE`. The answer comes with the settlement receipt in `PAYMENT-RESPONSE`. Settlement happens only after the answer is computed, so a failed answer is never charged. Any x402 client works, for example `@x402/fetch`. Over MCP (https://data.spencermcw.com/mcp, streamable HTTP, stateless) the same objects travel in `_meta`: an unpaid call to a paid tool (with no free tier, or once it is used or skipped) returns `isError` with the x402 PaymentRequired object as `structuredContent`; retry with the PaymentPayload in `_meta["x402/payment"]`; the receipt is in `_meta["x402/payment-response"]`. This is the `@x402/mcp` convention. Some paid routes have a small free tier per IP (3 calls a day per vertical, with fewer rows; each route says); free answers use the same envelope with `price_paid: null`. Over HTTP the free tier is opt-in: send the header `Distill-Free-Tier: use` on an unpaid call. Without it, an unpaid call to a paid route answers 402, before its input is checked; once the day's free calls are used up, the header gets the 402 too. Over MCP an unpaid call takes the free tier while it lasts; send `_meta["distill/free-tier"]: "skip"` to get the payment-required result instead. ## Every answer Every answer, free or paid, is one JSON envelope: `data` (the route-specific answer), `sources` (url, fetched_at, sha256, publisher, license for every source used), `as_of` (the freshness of the underlying data), `confidence` (0 to 1, computed by the formula each route documents), `method_version` (bumped on any change to how the answer is made), `price_paid` (null when free), `notices` (disclaimers) and `request_id`. Distill sells posted facts and computed aggregates, never medical, financial or tax advice. ## Sales tax Sales-tax rates in the 24 Streamlined Sales Tax states, read from each state’s own rate and boundary files: by ZIP+4, ZIP or street address, with every jurisdiction’s rate, the period it holds, and a quarterly change feed. Every answer cites the state files by URL and sha256. ### GET /v1/tax/sales-rate From the state’s own Streamlined Sales Tax rate and boundary files (24 states: AR, GA, IA, IN, KS, KY, MI, MN, NC, ND, NE, NJ, NV, OH, OK, RI, SD, TN, UT, VT, WA, WI, WV, WY). Matches an address when the state publishes address records, else the ZIP+4 record, else the 5-digit record (the lowest rate in the ZIP, per SSUTA 305). Returns each jurisdiction’s rate, the combined rate, and the period it holds. Locations outside these states answer 404 and are not charged. - Route id: `tax.sales_rate` - Price: $0.005 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `tax_sales_rate` - Method version: `tax.sales_rate@1.0.0` - Freshness: quarterly - Confidence: agreement × freshness. Agreement: for a 5-digit ZIP answer, the share of that ZIP’s ZIP+4 records with the same combined rate; for a ZIP+4 answer, the share of address records inside it with the same rate; 1 for an address match or when the state publishes nothing finer. Freshness: 1 until the next SST posting deadline (the 1st of Mar, Jun, Sep or Dec) after the files were last checked, then halving every 30 days. - Notice: Not tax advice. Rates as published by the state in its Streamlined Sales Tax rate and boundary files for the stated effective period; verify with the state. See /terms. Input (query and path parameters): ```json { "type": "object", "properties": { "zip": { "type": "string", "pattern": "^\\d{5}(-?\\d{4})?$", "description": "A 5-digit ZIP code or a ZIP+4 (98101-3143 or 981013143)." }, "address": { "type": "string", "minLength": 3, "maxLength": 120, "description": "Optional street address line with house number, e.g. \"1010 E Alder St\" or \"PO Box 12\"; matched against the state address records when it publishes them." }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The sale date, YYYY-MM-DD (default: today, UTC). From the first day of the previous quarter onward." } }, "required": [ "zip" ], "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "location": { "type": "object", "properties": { "zip": { "type": "string" }, "plus4": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "date": { "type": "string" } }, "required": [ "zip", "plus4", "address", "date" ], "additionalProperties": false }, "state": { "type": "string" }, "state_fips": { "type": "string" }, "matched": { "type": "string", "enum": [ "address", "zip4", "zip5" ] }, "rate": { "type": "string", "description": "The combined general rate for an in-state (intrastate) sale, as a decimal fraction." }, "combined": { "type": "object", "properties": { "general": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false }, "food_drug": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false } }, "required": [ "general", "food_drug" ], "additionalProperties": false }, "components": { "type": "array", "items": { "type": "object", "properties": { "jurisdiction": { "type": "string", "enum": [ "state", "county", "place", "special" ] }, "code": { "type": "string" }, "type": { "type": "string" }, "type_name": { "type": "string" }, "general": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false }, "food_drug": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false }, "effective_from": { "type": "string" }, "effective_to": { "type": [ "string", "null" ] } }, "required": [ "jurisdiction", "code", "type", "type_name", "general", "food_drug", "effective_from", "effective_to" ], "additionalProperties": false } }, "jurisdiction_codes": { "type": "object", "properties": { "state_indicator": { "type": "string" }, "county": { "type": [ "string", "null" ] }, "place": { "type": [ "string", "null" ] }, "place_class": { "type": [ "string", "null" ] }, "composite_ser_code": { "type": [ "string", "null" ] }, "specials": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" } }, "required": [ "source", "code", "type" ], "additionalProperties": false } } }, "required": [ "state_indicator", "county", "place", "place_class", "composite_ser_code", "specials" ], "additionalProperties": false }, "alternate": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string" }, "code": { "type": "string" }, "rate": { "type": "string" } }, "required": [ "product", "code", "rate" ], "additionalProperties": false } }, "effective": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": [ "string", "null" ] } }, "required": [ "from", "to" ], "additionalProperties": false }, "agreement": { "type": "object", "properties": { "finer_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "agreeing": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "finer_records", "agreeing" ], "additionalProperties": false } }, "required": [ "location", "state", "state_fips", "matched", "rate", "combined", "components", "jurisdiction_codes", "alternate", "effective", "agreement" ], "additionalProperties": false } ``` Example 1: `GET https://data.spencermcw.com/v1/tax/sales-rate?zip=98101-3143&date=2026-10-19` ```json { "location": { "zip": "98101", "plus4": "3143", "address": null, "date": "2026-10-19" }, "state": "WA", "state_fips": "53", "matched": "zip4", "rate": "0.1055", "combined": { "general": { "intrastate": "0.1055", "interstate": "0.1055" }, "food_drug": { "intrastate": "0.1055", "interstate": "0.1055" } }, "components": [ { "jurisdiction": "state", "code": "53", "type": "45", "type_name": "State Taxing Authority", "general": { "intrastate": "0.065", "interstate": "0.065" }, "food_drug": { "intrastate": "0.065", "interstate": "0.065" }, "effective_from": "1983-03-01", "effective_to": null }, { "jurisdiction": "place", "code": "63000", "type": "01", "type_name": "City", "general": { "intrastate": "0.0405", "interstate": "0.0405" }, "food_drug": { "intrastate": "0.0405", "interstate": "0.0405" }, "effective_from": "2026-01-01", "effective_to": "2027-03-31" } ], "jurisdiction_codes": { "state_indicator": "53", "county": null, "place": "63000", "place_class": null, "composite_ser_code": "01726", "specials": [] }, "alternate": [], "effective": { "from": "2026-01-01", "to": "2027-03-31" }, "agreement": { "finer_records": 1, "agreeing": 1 } } ``` ### POST /v1/tax/sales-rate/batch The same answer as tax.sales_rate for each location, in order. A location that fails (outside the SST states, a bad date) carries its own error; the call is still one price. - Route id: `tax.sales_rate_batch` - Price: $0.1 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `tax_sales_rate_batch` - Method version: `tax.sales_rate@1.0.0` - Freshness: quarterly - Confidence: The lowest per-location confidence in the batch; each is agreement × freshness. Agreement: for a 5-digit ZIP answer, the share of that ZIP’s ZIP+4 records with the same combined rate; for a ZIP+4 answer, the share of address records inside it with the same rate; 1 for an address match or when the state publishes nothing finer. Freshness: 1 until the next SST posting deadline (the 1st of Mar, Jun, Sep or Dec) after the files were last checked, then halving every 30 days. - Notice: Not tax advice. Rates as published by the state in its Streamlined Sales Tax rate and boundary files for the stated effective period; verify with the state. See /terms. Input (JSON body): ```json { "type": "object", "properties": { "locations": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "zip": { "type": "string", "pattern": "^\\d{5}(-?\\d{4})?$", "description": "A 5-digit ZIP code or a ZIP+4 (98101-3143 or 981013143)." }, "address": { "type": "string", "minLength": 3, "maxLength": 120, "description": "Optional street address line with house number, e.g. \"1010 E Alder St\" or \"PO Box 12\"; matched against the state address records when it publishes them." }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The sale date, YYYY-MM-DD (default: today, UTC). From the first day of the previous quarter onward." } }, "required": [ "zip" ], "additionalProperties": false } } }, "required": [ "locations" ], "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ok": { "type": "boolean", "const": true }, "answer": { "type": "object", "properties": { "location": { "type": "object", "properties": { "zip": { "type": "string" }, "plus4": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "date": { "type": "string" } }, "required": [ "zip", "plus4", "address", "date" ], "additionalProperties": false }, "state": { "type": "string" }, "state_fips": { "type": "string" }, "matched": { "type": "string", "enum": [ "address", "zip4", "zip5" ] }, "rate": { "type": "string", "description": "The combined general rate for an in-state (intrastate) sale, as a decimal fraction." }, "combined": { "type": "object", "properties": { "general": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false }, "food_drug": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false } }, "required": [ "general", "food_drug" ], "additionalProperties": false }, "components": { "type": "array", "items": { "type": "object", "properties": { "jurisdiction": { "type": "string", "enum": [ "state", "county", "place", "special" ] }, "code": { "type": "string" }, "type": { "type": "string" }, "type_name": { "type": "string" }, "general": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false }, "food_drug": { "type": "object", "properties": { "intrastate": { "type": "string" }, "interstate": { "type": "string" } }, "required": [ "intrastate", "interstate" ], "additionalProperties": false }, "effective_from": { "type": "string" }, "effective_to": { "type": [ "string", "null" ] } }, "required": [ "jurisdiction", "code", "type", "type_name", "general", "food_drug", "effective_from", "effective_to" ], "additionalProperties": false } }, "jurisdiction_codes": { "type": "object", "properties": { "state_indicator": { "type": "string" }, "county": { "type": [ "string", "null" ] }, "place": { "type": [ "string", "null" ] }, "place_class": { "type": [ "string", "null" ] }, "composite_ser_code": { "type": [ "string", "null" ] }, "specials": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" } }, "required": [ "source", "code", "type" ], "additionalProperties": false } } }, "required": [ "state_indicator", "county", "place", "place_class", "composite_ser_code", "specials" ], "additionalProperties": false }, "alternate": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string" }, "code": { "type": "string" }, "rate": { "type": "string" } }, "required": [ "product", "code", "rate" ], "additionalProperties": false } }, "effective": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": [ "string", "null" ] } }, "required": [ "from", "to" ], "additionalProperties": false }, "agreement": { "type": "object", "properties": { "finer_records": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "agreeing": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "finer_records", "agreeing" ], "additionalProperties": false } }, "required": [ "location", "state", "state_fips", "matched", "rate", "combined", "components", "jurisdiction_codes", "alternate", "effective", "agreement" ], "additionalProperties": false } }, "required": [ "index", "ok", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "index", "ok", "error" ], "additionalProperties": false } ] } } }, "required": [ "results" ], "additionalProperties": false } ``` Example 1: `POST https://data.spencermcw.com/v1/tax/sales-rate/batch` ```json { "locations": [ { "zip": "98101-3143", "date": "2026-10-19" }, { "zip": "90210" } ] } ``` ```json { "results": [ { "index": 0, "ok": true, "answer": { "location": { "zip": "98101", "plus4": "3143", "address": null, "date": "2026-10-19" }, "state": "WA", "state_fips": "53", "matched": "zip4", "rate": "0.1055", "combined": { "general": { "intrastate": "0.1055", "interstate": "0.1055" }, "food_drug": { "intrastate": "0.1055", "interstate": "0.1055" } }, "components": [ { "jurisdiction": "state", "code": "53", "type": "45", "type_name": "State Taxing Authority", "general": { "intrastate": "0.065", "interstate": "0.065" }, "food_drug": { "intrastate": "0.065", "interstate": "0.065" }, "effective_from": "1983-03-01", "effective_to": null }, { "jurisdiction": "place", "code": "63000", "type": "01", "type_name": "City", "general": { "intrastate": "0.0405", "interstate": "0.0405" }, "food_drug": { "intrastate": "0.0405", "interstate": "0.0405" }, "effective_from": "2026-01-01", "effective_to": "2027-03-31" } ], "jurisdiction_codes": { "state_indicator": "53", "county": null, "place": "63000", "place_class": null, "composite_ser_code": "01726", "specials": [] }, "alternate": [], "effective": { "from": "2026-01-01", "to": "2027-03-31" }, "agreement": { "finer_records": 1, "agreeing": 1 } } }, { "index": 1, "ok": false, "error": { "code": "not_covered", "message": "90210 is not in any Streamlined Sales Tax member state's boundary file on 2026-10-19" } } ] } ``` ### GET /v1/tax/changes Change records read from the states’ rate and boundary files: rates that change, begin or end; ZIP+4 and 5-digit ZIP ranges whose jurisdictions change; new files posted. Each record cites the sha256 of the files it came from. Pages of up to 100, oldest first; pass next_cursor back as cursor. - Route id: `tax.changes` - Price: $0.05 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `tax_changes` - Method version: `tax.changes@1.0.0` - Freshness: quarterly - Confidence: Freshness only (change records are read from the state files deterministically): 1 until the next SST posting deadline (the 1st of Mar, Jun, Sep or Dec) after the files were last checked, then halving every 30 days. - Notice: Not tax advice. Rates as published by the state in its Streamlined Sales Tax rate and boundary files for the stated effective period; verify with the state. See /terms. Input (query and path parameters): ```json { "type": "object", "properties": { "since": { "description": "Only records detected after this time (ISO 8601).", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "effective_from": { "description": "Only changes effective on or after this day.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "state": { "description": "Two-letter state code, e.g. WA.", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "entity": { "type": "string", "enum": [ "rate", "zip4", "zip5", "address_records", "file" ] }, "cursor": { "type": "string", "pattern": "^\\d{1,12}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "string", "enum": [ "rate", "zip4", "zip5", "address_records", "file" ] }, "state": { "type": "string" }, "key": { "type": "string" }, "field": { "type": "string" }, "old": { "type": [ "string", "null" ] }, "new": { "type": [ "string", "null" ] }, "effective": { "type": "string" }, "detected_at": { "type": "string" }, "source_sha256_old": { "type": [ "string", "null" ] }, "source_sha256_new": { "type": [ "string", "null" ] }, "method_version": { "type": "string" } }, "required": [ "id", "entity", "state", "key", "field", "old", "new", "effective", "detected_at", "source_sha256_old", "source_sha256_new", "method_version" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "records", "next_cursor" ], "additionalProperties": false } ``` Example 1: `GET https://data.spencermcw.com/v1/tax/changes?state=WA&entity=rate&limit=1` ```json { "records": [ { "id": "61970", "entity": "rate", "state": "WA", "key": "44165 (type 01)", "field": "food_drug_interstate", "old": "0.019", "new": "0.018", "effective": "2026-10-01", "detected_at": "2026-10-19T22:23:30.961Z", "source_sha256_old": "fb0d4514b4713057bc4d08f79184fb952ea9442b350bc65a2fb3c0214d7f23e1", "source_sha256_new": "fb0d4514b4713057bc4d08f79184fb952ea9442b350bc65a2fb3c0214d7f23e1", "method_version": "tax.sst@1.0.0" } ], "next_cursor": "61970" } ``` ## Hospital prices Posted standard charges from the machine-readable files US hospitals must publish under 45 CFR 180 (Colorado first): for a CPT, HCPCS or MS-DRG code near a ZIP code, each hospital’s gross charge, discounted cash price and every payer and plan’s negotiated rate, with payers canonicalized; a payer comparison, a hospital comparison and a weekly change feed. Every answer cites the hospital’s file by URL and sha256. Posted rates, not a quote; not medical or financial advice. CPT codes come without their AMA descriptors. ### GET /v1/hospital/prices From the machine-readable standard-charge files hospitals must publish (45 CFR 180), parsed and normalized: for each hospital within the radius that posts the code, nearest first, the gross charge, the discounted cash price, the de-identified minimum and maximum, and every payer and plan’s negotiated dollar amount or percentage (with the v3.0 median, 10th and 90th percentile allowed amounts), payers canonicalized to a stable payer_id. Filters: payer, plan type, plan name text, setting, billing class. A summary gives nearest-rank statistics over the hospitals returned. Served states: Colorado. An area with no hospital posting the code answers 404 and is not charged. - Route id: `hospital.prices` - Price: $0.02 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `hospital_prices` - Method version: `hospital.prices@1.1.0` - Freshness: weekly - Confidence: Mean over the returned rows (each rate; an item with no rate counts once) of normalize × quality × freshness. Normalize: the stored per-rate normalize confidence (payer canonicalization: rule 1, model 0.9, fallback 0.6; rate basis for rates with no dollar amount: rule 1, model 0.9, fallback 0.75; 1 for an item with no rate). Quality of the MRF: 1 valid against the v3.0 schema, 0.85 parsed with conformance errors, 0.7 parsed only after header repair. Freshness: 1 while the MRF’s last_updated_on is at most 365 days old, then halving every 180 days (0.5 with no date), times 1 within 14 days of our fetch, then halving every 30 days. - Notice: Posted standard charges from hospital machine-readable files (45 CFR 180): posted rates, not a quote; not medical or financial advice. What you pay depends on your plan, your care and the hospital. See /terms. Input (query and path parameters): ```json { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z]{3,5}$", "description": "The billing code: CPT (5 characters, e.g. 99213), HCPCS Level II (a letter and 4 digits, e.g. J1885) or MS-DRG (3 digits, e.g. 470)." }, "code_type": { "type": "string", "enum": [ "CPT", "HCPCS", "MS-DRG" ], "description": "Optional: the code type. Inferred from the code’s shape when omitted." }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "A 5-digit ZIP code (its Census ZCTA point). Give a zip, or lat and lon." }, "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude of the point (with lon)." }, "lon": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude of the point (with lat)." }, "radius_miles": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Search radius in miles (default 25, at most 100)." }, "payer": { "type": "string", "pattern": "^[a-z0-9_]{2,40}$", "description": "Optional: a canonical payer_id (e.g. aetna, cigna, unitedhealthcare, anthem, medicare, medicaid). hospital.payers lists the payers with prices for a code." }, "plan_type": { "type": "string", "enum": [ "commercial", "medicare_advantage", "medicaid", "medicare", "exchange", "tricare", "va", "workers_comp", "auto", "supplemental", "other", "unspecified" ], "description": "Optional: the canonical plan type." }, "plan": { "type": "string", "minLength": 2, "maxLength": 80, "description": "Optional: text the plan name (or payer name) contains as the hospital writes it, case-insensitive, e.g. \"PPO\" or \"Medicare Advantage\"." }, "setting": { "type": "string", "enum": [ "inpatient", "outpatient" ], "description": "Optional: inpatient or outpatient (items posted for both always match)." }, "billing_class": { "type": "string", "enum": [ "facility", "professional" ], "description": "Optional: facility or professional (items posted for both always match)." }, "limit": { "description": "How many hospitals to return, nearest first (default 10, at most 50).", "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "code" ], "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "code": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CPT", "HCPCS", "MS-DRG" ] }, "code": { "type": "string" }, "description": { "description": "The CMS HCPCS Level II description or MS-DRG title; always null for CPT (AMA copyright).", "type": [ "string", "null" ] }, "description_source": { "anyOf": [ { "type": "string", "enum": [ "cms_hcpcs_level_ii", "cms_ms_drg" ] }, { "type": "null" } ] }, "drg": { "anyOf": [ { "type": "object", "properties": { "mdc": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "gmlos": { "type": [ "number", "null" ] }, "amlos": { "type": [ "number", "null" ] } }, "required": [ "mdc", "kind", "weight", "gmlos", "amlos" ], "additionalProperties": false }, { "type": "null" } ] }, "mrfs_statewide": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hospital files in the served states that price this code." } }, "required": [ "type", "code", "description", "description_source", "drg", "mrfs_statewide" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "zip": { "type": [ "string", "null" ] }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_miles": { "type": "number" } }, "required": [ "zip", "lat", "lon", "radius_miles" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "payer": { "type": [ "string", "null" ] }, "plan_type": { "type": [ "string", "null" ] }, "plan": { "type": [ "string", "null" ] }, "setting": { "type": [ "string", "null" ] }, "billing_class": { "type": [ "string", "null" ] } }, "required": [ "payer", "plan_type", "plan", "setting", "billing_class" ], "additionalProperties": false }, "hospitals_in_radius": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hospitals_with_file": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hospitals_with_prices": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hospitals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ccn": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "distance_miles": { "type": "number" }, "mrfs": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string" }, "url": { "type": "string" }, "sha256": { "type": "string" }, "fetched_at": { "type": "string" }, "last_updated_on": { "type": [ "string", "null" ] }, "conformance": { "type": "string", "enum": [ "valid", "errors", "repaired" ] } }, "required": [ "source_id", "url", "sha256", "fetched_at", "last_updated_on", "conformance" ], "additionalProperties": false } }, "items": { "type": "array", "items": { "type": "object", "properties": { "mrf": { "type": "string", "description": "The source_id of the MRF this item is from." }, "setting": { "anyOf": [ { "type": "string", "enum": [ "inpatient", "outpatient", "both" ] }, { "type": "null" } ] }, "billing_class": { "anyOf": [ { "type": "string", "enum": [ "facility", "professional", "both" ] }, { "type": "null" } ] }, "modifiers": { "type": "array", "items": { "type": "string" } }, "gross": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "gross_max": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "discounted_cash": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "discounted_cash_max": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "deidentified_min": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "deidentified_max": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "drug_unit": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "type": { "type": [ "string", "null" ] } }, "required": [ "amount", "type" ], "additionalProperties": false }, { "type": "null" } ] }, "rates": { "type": "array", "items": { "type": "object", "properties": { "payer_id": { "type": "string" }, "payer": { "type": "string" }, "plan_type": { "type": "string" }, "payer_name": { "description": "The payer as the hospital writes it.", "type": [ "string", "null" ] }, "plan_name": { "description": "The plan as the hospital writes it.", "type": [ "string", "null" ] }, "negotiated_dollar": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "negotiated_dollar_max": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ], "description": "The highest dollar when the file posts several for this payer/plan and methodology." }, "negotiated_percentage": { "type": [ "number", "null" ] }, "methodology": { "anyOf": [ { "type": "string", "enum": [ "case rate", "fee schedule", "percent of total billed charges", "per diem", "other" ] }, { "type": "null" } ], "description": "How the rate is paid (v3.0 methodology). A payer/plan with lines of several methodologies (a per diem and a case rate) has one rate per methodology." }, "algorithm": { "description": "standard_charge|negotiated_algorithm: the contract term that is the price.", "type": [ "string", "null" ] }, "rate_basis": { "type": [ "string", "null" ] }, "allowed": { "anyOf": [ { "type": "object", "properties": { "median": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "median_max": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "p10": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "p90": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "count": { "type": [ "string", "null" ] } }, "required": [ "median", "median_max", "p10", "p90", "count" ], "additionalProperties": false }, { "type": "null" } ], "description": "v3.0 median, 10th and 90th percentile allowed amounts and their count (percentage/algorithm rates). When several lines of the file give different ones for this payer/plan and methodology: median is the lowest median and median_max the highest, p10 the lowest 10th percentile and p90 the highest 90th, count their sum when every count is a number (else null)." }, "normalized_by": { "type": "object", "properties": { "payer": { "type": "string" }, "basis": { "type": [ "string", "null" ] } }, "required": [ "payer", "basis" ], "additionalProperties": false }, "confidence": { "type": "number" } }, "required": [ "payer_id", "payer", "plan_type", "payer_name", "plan_name", "negotiated_dollar", "negotiated_dollar_max", "negotiated_percentage", "methodology", "algorithm", "rate_basis", "allowed", "normalized_by", "confidence" ], "additionalProperties": false } } }, "required": [ "mrf", "setting", "billing_class", "modifiers", "gross", "gross_max", "discounted_cash", "discounted_cash_max", "deidentified_min", "deidentified_max", "drug_unit", "rates" ], "additionalProperties": false } }, "confidence": { "type": "number" } }, "required": [ "id", "ccn", "name", "city", "zip", "distance_miles", "mrfs", "items", "confidence" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "hospitals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rates": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negotiated_dollar": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." }, "discounted_cash": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." }, "gross": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." } }, "required": [ "hospitals", "items", "rates", "negotiated_dollar", "discounted_cash", "gross" ], "additionalProperties": false, "description": "Over the hospitals returned." } }, "required": [ "code", "location", "filters", "hospitals_in_radius", "hospitals_with_file", "hospitals_with_prices", "hospitals", "summary" ], "additionalProperties": false } ``` Example 1: `GET https://data.spencermcw.com/v1/hospital/prices?code=A4550&zip=81052&radius_miles=10&payer=medicare&limit=1` ```json { "code": { "type": "HCPCS", "code": "A4550", "description": "Surgical trays", "description_source": "cms_hcpcs_level_ii", "drg": null, "mrfs_statewide": 13 }, "location": { "zip": "81052", "lat": 37.9744, "lon": -102.639, "radius_miles": 10 }, "filters": { "payer": "medicare", "plan_type": null, "plan": null, "setting": null, "billing_class": null }, "hospitals_in_radius": 1, "hospitals_with_file": 1, "hospitals_with_prices": 1, "hospitals": [ { "id": "co-061323", "ccn": "061323", "name": "PROWERS MEDICAL CENTER", "city": "LAMAR", "zip": "81052", "distance_miles": 6.7, "mrfs": [ { "source_id": "hpt-mrf-31836e761c89c201", "url": "https://www.prowersmedical.com/wp-content/uploads/840584583_PROWERS-MEDICAL-CENTER_STANDARDCHARGES.csv", "sha256": "1d4105709236d42f631e79f4e3fe22c408fe1e69b11118319869affa5f7fbbb1", "fetched_at": "2026-10-19T23:08:32.284Z", "last_updated_on": "2025-01-01", "conformance": "errors" } ], "items": [ { "mrf": "hpt-mrf-31836e761c89c201", "setting": "both", "billing_class": null, "modifiers": [], "gross": "67", "gross_max": null, "discounted_cash": "40.2", "discounted_cash_max": null, "deidentified_min": "32.83", "deidentified_max": "63.65", "drug_unit": null, "rates": [ { "payer_id": "medicare", "payer": "Medicare (CMS)", "plan_type": "medicare", "payer_name": "Medicare", "plan_name": null, "negotiated_dollar": "32.83", "negotiated_dollar_max": null, "negotiated_percentage": 49, "methodology": "percent of total billed charges", "algorithm": "annual cost report", "rate_basis": "percent_of_charges", "allowed": null, "normalized_by": { "payer": "rule", "basis": "fallback" }, "confidence": 0.2756 } ] } ], "confidence": 0.2756 } ], "summary": { "hospitals": 1, "items": 1, "rates": 1, "negotiated_dollar": { "n": 1, "min": "32.83", "p10": "32.83", "median": "32.83", "p90": "32.83", "max": "32.83" }, "discounted_cash": { "n": 1, "min": "40.2", "p10": "40.2", "median": "40.2", "p90": "40.2", "max": "40.2" }, "gross": { "n": 1, "min": "67", "p10": "67", "median": "67", "p90": "67", "max": "67" } } } ``` ### GET /v1/hospital/compare For each named hospital: whether it posts the code, and over its items for the code (only those without modifiers when it posts any, so a professional -26 or bilateral -50 line does not skew the row) nearest-rank statistics of its gross charges, discounted cash prices and negotiated dollar amounts across payers and plans, the range of negotiated percentages, the de-identified minimum and maximum, and the number of payers. The same filters as hospital.prices. Hospital ids come from hospital.prices (or pass a CMS certification number). Not charged when none of the hospitals is known. - Route id: `hospital.compare` - Price: $0.02 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `hospital_compare` - Method version: `hospital.compare@1.1.0` - Freshness: weekly - Confidence: Mean over the returned rows (each rate; an item with no rate counts once) of normalize × quality × freshness. Normalize: the stored per-rate normalize confidence (payer canonicalization: rule 1, model 0.9, fallback 0.6; rate basis for rates with no dollar amount: rule 1, model 0.9, fallback 0.75; 1 for an item with no rate). Quality of the MRF: 1 valid against the v3.0 schema, 0.85 parsed with conformance errors, 0.7 parsed only after header repair. Freshness: 1 while the MRF’s last_updated_on is at most 365 days old, then halving every 180 days (0.5 with no date), times 1 within 14 days of our fetch, then halving every 30 days. Rows are each hospital’s items for the code as compared. - Notice: Posted standard charges from hospital machine-readable files (45 CFR 180): posted rates, not a quote; not medical or financial advice. What you pay depends on your plan, your care and the hospital. See /terms. Input (query and path parameters): ```json { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z]{3,5}$", "description": "The billing code: CPT (5 characters, e.g. 99213), HCPCS Level II (a letter and 4 digits, e.g. J1885) or MS-DRG (3 digits, e.g. 470)." }, "code_type": { "type": "string", "enum": [ "CPT", "HCPCS", "MS-DRG" ], "description": "Optional: the code type. Inferred from the code’s shape when omitted." }, "hospitals": { "type": "string", "pattern": "^[A-Za-z0-9-]{6,20}(,[A-Za-z0-9-]{6,20}){0,9}$", "description": "One to ten hospital ids (e.g. co-060001) or CMS certification numbers, comma-separated." }, "payer": { "type": "string", "pattern": "^[a-z0-9_]{2,40}$", "description": "Optional: a canonical payer_id (e.g. aetna, cigna, unitedhealthcare, anthem, medicare, medicaid). hospital.payers lists the payers with prices for a code." }, "plan_type": { "type": "string", "enum": [ "commercial", "medicare_advantage", "medicaid", "medicare", "exchange", "tricare", "va", "workers_comp", "auto", "supplemental", "other", "unspecified" ], "description": "Optional: the canonical plan type." }, "plan": { "type": "string", "minLength": 2, "maxLength": 80, "description": "Optional: text the plan name (or payer name) contains as the hospital writes it, case-insensitive, e.g. \"PPO\" or \"Medicare Advantage\"." }, "setting": { "type": "string", "enum": [ "inpatient", "outpatient" ], "description": "Optional: inpatient or outpatient (items posted for both always match)." }, "billing_class": { "type": "string", "enum": [ "facility", "professional" ], "description": "Optional: facility or professional (items posted for both always match)." } }, "required": [ "code", "hospitals" ], "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "code": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CPT", "HCPCS", "MS-DRG" ] }, "code": { "type": "string" }, "description": { "description": "The CMS HCPCS Level II description or MS-DRG title; always null for CPT (AMA copyright).", "type": [ "string", "null" ] }, "description_source": { "anyOf": [ { "type": "string", "enum": [ "cms_hcpcs_level_ii", "cms_ms_drg" ] }, { "type": "null" } ] }, "drg": { "anyOf": [ { "type": "object", "properties": { "mdc": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "gmlos": { "type": [ "number", "null" ] }, "amlos": { "type": [ "number", "null" ] } }, "required": [ "mdc", "kind", "weight", "gmlos", "amlos" ], "additionalProperties": false }, { "type": "null" } ] }, "mrfs_statewide": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hospital files in the served states that price this code." } }, "required": [ "type", "code", "description", "description_source", "drg", "mrfs_statewide" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "payer": { "type": [ "string", "null" ] }, "plan_type": { "type": [ "string", "null" ] }, "plan": { "type": [ "string", "null" ] }, "setting": { "type": [ "string", "null" ] }, "billing_class": { "type": [ "string", "null" ] } }, "required": [ "payer", "plan_type", "plan", "setting", "billing_class" ], "additionalProperties": false }, "hospitals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ccn": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "priced": { "type": "boolean" }, "basis": { "anyOf": [ { "type": "string", "enum": [ "unmodified", "all" ] }, { "type": "null" } ], "description": "unmodified: only items without modifiers were compared; all: the hospital posts the code only with modifiers." }, "mrfs": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string" }, "url": { "type": "string" }, "sha256": { "type": "string" }, "fetched_at": { "type": "string" }, "last_updated_on": { "type": [ "string", "null" ] }, "conformance": { "type": "string", "enum": [ "valid", "errors", "repaired" ] } }, "required": [ "source_id", "url", "sha256", "fetched_at", "last_updated_on", "conformance" ], "additionalProperties": false } }, "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." }, "discounted_cash": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." }, "negotiated_dollar": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." }, "negotiated_percentage": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "n", "min", "max" ], "additionalProperties": false }, { "type": "null" } ] }, "deidentified_min": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "deidentified_max": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, { "type": "null" } ] }, "confidence": { "type": [ "number", "null" ] } }, "required": [ "id", "ccn", "name", "city", "status", "priced", "basis", "mrfs", "items", "payers", "gross", "discounted_cash", "negotiated_dollar", "negotiated_percentage", "deidentified_min", "deidentified_max", "confidence" ], "additionalProperties": false } }, "not_found": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "filters", "hospitals", "not_found" ], "additionalProperties": false } ``` Example 1: `GET https://data.spencermcw.com/v1/hospital/compare?code=470&hospitals=co-060001%2Cco-061323&payer=aetna` ```json { "code": { "type": "MS-DRG", "code": "470", "description": "MAJOR HIP AND KNEE JOINT REPLACEMENT OR REATTACHMENT OF LOWER EXTREMITY WITHOUT MCC", "description_source": "cms_ms_drg", "drg": { "mdc": "08", "kind": "SURG", "weight": 1.9563, "gmlos": 2, "amlos": 2.3 }, "mrfs_statewide": 45 }, "filters": { "payer": "aetna", "plan_type": null, "plan": null, "setting": null, "billing_class": null }, "hospitals": [ { "id": "co-060001", "ccn": "060001", "name": "BANNER NORTH COLORADO MEDICAL CENTER", "city": "GREELEY", "status": "served", "priced": true, "basis": "unmodified", "mrfs": [ { "source_id": "hpt-mrf-459d3e4251c49cf7", "url": "https://images.pricetransparency.healthcare/public-mrfs/banner/841287638_banner-north-colorado-medical-center_standardcharges.csv", "sha256": "505667e76aaa7803d44a670ee04ddc3b07b81da8702657983a40c1eb1f168997", "fetched_at": "2026-10-19T23:09:02.163Z", "last_updated_on": "2026-09-23", "conformance": "valid" } ], "items": 1, "payers": 3, "gross": null, "discounted_cash": { "n": 1, "min": "24121.08", "p10": "24121.08", "median": "24121.08", "p90": "24121.08", "max": "24121.08" }, "negotiated_dollar": { "n": 3, "min": "18340.39", "p10": "18340.39", "median": "51555.64", "p90": "70238.96", "max": "70238.96" }, "negotiated_percentage": null, "deidentified_min": "17790.18", "deidentified_max": "70238.96", "confidence": 1 }, { "id": "co-061323", "ccn": "061323", "name": "PROWERS MEDICAL CENTER", "city": "LAMAR", "status": "served", "priced": false, "basis": null, "mrfs": [ { "source_id": "hpt-mrf-31836e761c89c201", "url": "https://www.prowersmedical.com/wp-content/uploads/840584583_PROWERS-MEDICAL-CENTER_STANDARDCHARGES.csv", "sha256": "1d4105709236d42f631e79f4e3fe22c408fe1e69b11118319869affa5f7fbbb1", "fetched_at": "2026-10-19T23:08:32.284Z", "last_updated_on": "2025-01-01", "conformance": "errors" } ], "items": 0, "payers": 0, "gross": null, "discounted_cash": null, "negotiated_dollar": null, "negotiated_percentage": null, "deidentified_min": null, "deidentified_max": null, "confidence": null } ], "not_found": [] } ``` ### GET /v1/hospital/payers Every payer’s negotiated dollar amounts for the code at the hospitals within the radius, grouped by canonical payer_id (the stable id behind the many ways hospitals write a payer’s name), plan type and methodology (a per diem and a case rate are never pooled): how many hospitals and rates, and nearest-rank statistics. Payers with the most hospitals first. Percentage-only rates are left out (they have no dollar amount; hospital.prices shows them). The payer_ids here are what the payer filter of hospital.prices and hospital.compare takes. - Route id: `hospital.payers` - Price: $0.02 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `hospital_payers` - Method version: `hospital.payers@1.1.0` - Freshness: weekly - Confidence: Mean over every rate in the payer rows returned of normalize × quality × freshness, with the same factors as hospital.prices (normalize: the stored per-rate payer canonicalization confidence, rule 1, model 0.9, fallback 0.6; quality: 1 valid v3.0, 0.85 with conformance errors, 0.7 after header repair; freshness: 1 while last_updated_on is at most 365 days old, then halving every 180 days, times 1 within 14 days of our fetch, then halving every 30 days). - Notice: Posted standard charges from hospital machine-readable files (45 CFR 180): posted rates, not a quote; not medical or financial advice. What you pay depends on your plan, your care and the hospital. See /terms. Input (query and path parameters): ```json { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z]{3,5}$", "description": "The billing code: CPT (5 characters, e.g. 99213), HCPCS Level II (a letter and 4 digits, e.g. J1885) or MS-DRG (3 digits, e.g. 470)." }, "code_type": { "type": "string", "enum": [ "CPT", "HCPCS", "MS-DRG" ], "description": "Optional: the code type. Inferred from the code’s shape when omitted." }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "A 5-digit ZIP code (its Census ZCTA point). Give a zip, or lat and lon." }, "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude of the point (with lon)." }, "lon": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude of the point (with lat)." }, "radius_miles": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Search radius in miles (default 25, at most 100)." }, "setting": { "type": "string", "enum": [ "inpatient", "outpatient" ], "description": "Optional: inpatient or outpatient (items posted for both always match)." }, "plan_type": { "type": "string", "enum": [ "commercial", "medicare_advantage", "medicaid", "medicare", "exchange", "tricare", "va", "workers_comp", "auto", "supplemental", "other", "unspecified" ], "description": "Optional: the canonical plan type." } }, "required": [ "code" ], "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "code": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CPT", "HCPCS", "MS-DRG" ] }, "code": { "type": "string" }, "description": { "description": "The CMS HCPCS Level II description or MS-DRG title; always null for CPT (AMA copyright).", "type": [ "string", "null" ] }, "description_source": { "anyOf": [ { "type": "string", "enum": [ "cms_hcpcs_level_ii", "cms_ms_drg" ] }, { "type": "null" } ] }, "drg": { "anyOf": [ { "type": "object", "properties": { "mdc": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "gmlos": { "type": [ "number", "null" ] }, "amlos": { "type": [ "number", "null" ] } }, "required": [ "mdc", "kind", "weight", "gmlos", "amlos" ], "additionalProperties": false }, { "type": "null" } ] }, "mrfs_statewide": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Hospital files in the served states that price this code." } }, "required": [ "type", "code", "description", "description_source", "drg", "mrfs_statewide" ], "additionalProperties": false }, "location": { "type": "object", "properties": { "zip": { "type": [ "string", "null" ] }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_miles": { "type": "number" } }, "required": [ "zip", "lat", "lon", "radius_miles" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "setting": { "type": [ "string", "null" ] }, "plan_type": { "type": [ "string", "null" ] } }, "required": [ "setting", "plan_type" ], "additionalProperties": false }, "hospitals_with_prices": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payers_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payers": { "type": "array", "items": { "type": "object", "properties": { "payer_id": { "type": "string" }, "payer": { "type": "string" }, "plan_type": { "type": "string" }, "methodology": { "anyOf": [ { "type": "string", "enum": [ "case rate", "fee schedule", "percent of total billed charges", "per diem", "other" ] }, { "type": "null" } ], "description": "The rates’ v3.0 methodology: a payer’s per diems and case rates are separate rows, never pooled." }, "hospitals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rates": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negotiated_dollar": { "anyOf": [ { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "min": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p10": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "median": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "p90": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" }, "max": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$" } }, "required": [ "n", "min", "p10", "median", "p90", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Nearest-rank statistics in USD (each value is one of the posted amounts)." }, "fallback_rates": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rates whose payer the canonicalizer’s fallback placed (lower confidence)." }, "confidence": { "type": "number" } }, "required": [ "payer_id", "payer", "plan_type", "methodology", "hospitals", "rates", "negotiated_dollar", "fallback_rates", "confidence" ], "additionalProperties": false } } }, "required": [ "code", "location", "filters", "hospitals_with_prices", "payers_total", "payers" ], "additionalProperties": false } ``` Example 1: `GET https://data.spencermcw.com/v1/hospital/payers?code=470&zip=80631&radius_miles=15&plan_type=commercial` ```json { "code": { "type": "MS-DRG", "code": "470", "description": "MAJOR HIP AND KNEE JOINT REPLACEMENT OR REATTACHMENT OF LOWER EXTREMITY WITHOUT MCC", "description_source": "cms_ms_drg", "drg": { "mdc": "08", "kind": "SURG", "weight": 1.9563, "gmlos": 2, "amlos": 2.3 }, "mrfs_statewide": 45 }, "location": { "zip": "80631", "lat": 40.4447, "lon": -104.6794, "radius_miles": 15 }, "filters": { "setting": null, "plan_type": "commercial" }, "hospitals_with_prices": 2, "payers_total": 8, "payers": [ { "payer_id": "anthem", "payer": "Anthem Blue Cross and Blue Shield (Elevance Health)", "plan_type": "commercial", "methodology": "case rate", "hospitals": 2, "rates": 5, "negotiated_dollar": { "n": 5, "min": "32550.19", "p10": "32550.19", "median": "58474.6", "p90": "62303.47", "max": "62303.47" }, "fallback_rates": 0, "confidence": 1 }, { "payer_id": "aetna", "payer": "Aetna (CVS Health)", "plan_type": "commercial", "methodology": "case rate", "hospitals": 2, "rates": 2, "negotiated_dollar": { "n": 2, "min": "58937.54", "p10": "58937.54", "median": "58937.54", "p90": "70238.96", "max": "70238.96" }, "fallback_rates": 0, "confidence": 1 }, { "payer_id": "cigna", "payer": "Cigna Healthcare", "plan_type": "commercial", "methodology": "case rate", "hospitals": 1, "rates": 3, "negotiated_dollar": { "n": 3, "min": "42541.89", "p10": "42541.89", "median": "46501.92", "p90": "59871.13", "max": "59871.13" }, "fallback_rates": 0, "confidence": 1 }, { "payer_id": "other", "payer": "Other payer", "plan_type": "commercial", "methodology": "fee schedule", "hospitals": 1, "rates": 3, "negotiated_dollar": { "n": 3, "min": "22008.47", "p10": "22008.47", "median": "42182.9", "p90": "46767.99", "max": "46767.99" }, "fallback_rates": 3, "confidence": 0.6 }, { "payer_id": "kaiser", "payer": "Kaiser Permanente", "plan_type": "commercial", "methodology": "case rate", "hospitals": 1, "rates": 2, "negotiated_dollar": { "n": 2, "min": "37789.08", "p10": "37789.08", "median": "37789.08", "p90": "42605.54", "max": "42605.54" }, "fallback_rates": 0, "confidence": 1 }, { "payer_id": "unitedhealthcare", "payer": "UnitedHealthcare", "plan_type": "commercial", "methodology": "case rate", "hospitals": 1, "rates": 2, "negotiated_dollar": { "n": 2, "min": "49185.02", "p10": "49185.02", "median": "49185.02", "p90": "66736.08", "max": "66736.08" }, "fallback_rates": 0, "confidence": 1 }, { "payer_id": "denver_health_medical_plan", "payer": "Denver Health Medical Plan", "plan_type": "commercial", "methodology": "fee schedule", "hospitals": 1, "rates": 1, "negotiated_dollar": { "n": 1, "min": "32750.43", "p10": "32750.43", "median": "32750.43", "p90": "32750.43", "max": "32750.43" }, "fallback_rates": 0, "confidence": 1 }, { "payer_id": "other", "payer": "Other payer", "plan_type": "commercial", "methodology": "case rate", "hospitals": 1, "rates": 1, "negotiated_dollar": { "n": 1, "min": "38245.26", "p10": "38245.26", "median": "38245.26", "p90": "38245.26", "max": "38245.26" }, "fallback_rates": 1, "confidence": 0.6 } ] } ``` ### GET /v1/hospital/changes Change records from diffing consecutive weekly builds: a hospital republishing its file (source raw_sha256), items and payer rates that appear, disappear or change price, a hospital’s status or file date changing, and the canonical payer of a payer/plan name changing. Keys: source ``; hospital ``; item `|||||`; rate `|||` (names as the hospital writes them; one rate per methodology, empty when none is given); plan `|`. Money is integer micro-USD (unit usd_micro). Each record cites the sha256 of the file versions it came from. Pages of up to 100, oldest first; pass next_cursor back as cursor. - Route id: `hospital.changes` - Price: $0.05 per call (x402, exact) - Free tier: 3 free calls a day per IP, at most 3 rows per answer, with the header Distill-Free-Tier: use (without it an unpaid call answers 402) - MCP tool: `hospital_changes` - Method version: `hospital.changes@1.1.0` - Freshness: weekly - Confidence: Change records are diffs of consecutive serving DBs, computed deterministically; confidence is the feed’s freshness only: 1 within 14 days of the newest build, then halving every 30 days. - Notice: Posted standard charges from hospital machine-readable files (45 CFR 180): posted rates, not a quote; not medical or financial advice. What you pay depends on your plan, your care and the hospital. See /terms. Input (query and path parameters): ```json { "type": "object", "properties": { "since": { "description": "Only records detected at or after this time (ISO 8601).", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "cursor": { "description": "next_cursor from the previous page.", "type": "string", "pattern": "^\\d{1,12}$" }, "limit": { "description": "Records per page (default 100).", "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output (`data` inside the envelope): ```json { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "string", "enum": [ "source", "hospital", "item", "rate", "plan" ] }, "key": { "type": "string" }, "field": { "type": "string" }, "old": { "type": [ "string", "null" ] }, "new": { "type": [ "string", "null" ] }, "unit": { "anyOf": [ { "type": "string", "enum": [ "usd_micro", "percent" ] }, { "type": "null" } ], "description": "usd_micro: integer micro-USD (1000000 = $1)." }, "detected_at": { "type": "string" }, "source_sha256_old": { "type": [ "string", "null" ] }, "source_sha256_new": { "type": [ "string", "null" ] }, "method_version": { "type": "string" } }, "required": [ "id", "entity", "key", "field", "old", "new", "unit", "detected_at", "source_sha256_old", "source_sha256_new", "method_version" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "records", "next_cursor" ], "additionalProperties": false } ``` Example 1: `GET https://data.spencermcw.com/v1/hospital/changes?limit=1` ```json { "records": [], "next_cursor": null } ``` ## Machine-readable - [OpenAPI 3.1](https://data.spencermcw.com/openapi.json): every route's input and output schemas, examples, `x-price` and `x-payment` - [MCP server](https://data.spencermcw.com/mcp): one tool per route, streamable HTTP - [llms.txt](https://data.spencermcw.com/llms.txt): the short version of this file ## Optional - [Terms](https://data.spencermcw.com/terms): no warranty; liability limited to the amount paid for the call - [Changelog](https://data.spencermcw.com/changelog): route, price and method changes - [Distill-Bot](https://data.spencermcw.com/bot): how Distill fetches its sources