cms_facility_directory
Find Medicare/Medicaid-certified healthcare facilities by type, state, or name. Search nursing homes, home health agencies, hospices, and dialysis providers to get addresses and ownership details.
Instructions
Medicare/Medicaid-certified healthcare facilities by type — nursing homes, home health agencies, hospices, or dialysis facilities — with name, address, city, state, zip, and ownership (CMS provider-data, keyless; data.cms.gov datastore-query API, four datasets). Input: facilityType (REQUIRED enum — 'nursing_home' ~14,695 / 'home_health' ~12,460 / 'hospice' ~6,852 / 'dialysis' ~7,490; selects the dataset id via a constant map, the value NEVER enters the URL path). Optional state (2-letter, EXACT), facilityName (case-insensitive substring), size (1–100, def 25), offset. Returns { facilities:[{ name, address, city, state, zip, facilityType, ownership }] } + honest _meta. ★HONESTY: totalAvailable is the response's EXACT top-level count for the filter set — NEVER the returned-rows length; hasMore = offset+returned < count. name/address/ownership column names DIFFER across the four datasets → each is COALESCED over per-dataset candidates (name: provider_name/facility_name/legal_business_name; address: address/provider_address/address_line_1; ownership: ownership_type/type_of_ownership/profit_or_nonprofit) — a field absent in the chosen dataset is null (NEVER an empty string, NEVER fabricated). facilityType is echoed on each row. Filters applied SERVER-SIDE (AND-combined) — nothing silently dropped. Genuine no-match → honest empty; invalid facilityType → invalid_input (enum-blocked); 4xx → invalid_input/not_found; 5xx → THROWS; 200 non-array or missing count/results → schema_drift. NOT a clinical-quality or fitness determination.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Max facility rows to return (1–100, default 25). Offset-paginated. | |
| state | No | An optional 2-letter US state/territory code (→ state, EXACT match), e.g. 'VA', 'TX'. Validated ^[A-Za-z]{2}$. | |
| offset | No | Row offset for pagination (default 0). Page with _meta.pagination.nextOffset. | |
| facilityName | No | An optional facility-name fragment (case-insensitive SUBSTRING/contains match against the dataset's primary-name column). Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars). | |
| facilityType | Yes | REQUIRED — which CMS provider-data dataset to search: 'nursing_home' (~14,695), 'home_health' (~12,460), 'hospice' (~6,852), or 'dialysis' (~7,490). Selects the dataset id via a constant map (the value never enters the URL path). |