Apify Public Data & Leads

CMS Healthcare Provider Search

cms_healthcare_provider_search

Read-only

Search official CMS directories for Medicare-certified hospitals, nursing homes, home health agencies, hospices, dialysis, and rehab facilities, returning ownership, capacity, and star ratings.

Instructions

Search official CMS Provider Data Catalog directories for Medicare-certified hospitals, nursing homes, home health agencies, hospices, dialysis facilities, long-term care hospitals, and inpatient rehab facilities. Returns normalized facility records (identity, ownership, capacity, and star ratings) across all seven provider types through one consistent row shape.

Behavioral Transparency:

Execution: Network call executed synchronously in the cloud via Apify Actor 'captainhandsome/cms-healthcare-provider-search'.
Side Effects: Reads public sources and creates a billed Actor run and dataset on your Apify account.
Authentication: Requires APIFY_TOKEN environment variable.
Latency & Limits: Typical run duration is 10-30 seconds; timeout capped at 120 seconds.

Usage Guidelines:

When to use: Use for healthcare facility due diligence, star-rating and quality comparisons, nursing-home staffing/inspection/fines research, or building a location-bounded list of Medicare-certified providers.
When NOT to use: Do not use for clinical trial recruitment data, environmental compliance, campaign finance, corporate registry lookups, or contractor licensing.
Named alternatives: Use 'clinical_trials_search' for ClinicalTrials.gov study data, 'epa_facility_search' for environmental compliance, 'us_business_entity_search' or 'us_contractor_license_search' for corporate/contractor registries, or 'europe_pmc_paper_search' for biomedical literature.

Input Schema

TableJSON Schema

Name	Required	Description
`zip`	No	Five-digit US ZIP code to filter by, e.g. '77030'.
`city`	No	City name to filter by, matched exactly (case-insensitive, not a substring), e.g. 'Houston'.
`state`	Yes	Two-letter US state or territory abbreviation to search within, e.g. 'TX'.
`county`	No	County name to filter by, matched exactly (case-insensitive), e.g. 'Harris'.
`max_results`	No	Maximum number of provider records to retrieve and bill. Defaults to 10.
`name_contains`	No	Case-insensitive substring to match against the provider or facility name, e.g. 'Memorial'.
`provider_types`	No	One or more CMS provider-directory types to search, e.g. ['hospital'] or ['nursing_home', 'hospice']. Omit to search hospitals only, the Actor's own fallback.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`run`	No
`error`	No
`status`	Yes
`results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed38 schema fields changedv1.1.0Sep 15, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
addedInput schema / properties / provider_types / maxItems
```
Added value: +100
```
addedOutput schema / properties / error
```
Added value: +{
+  "type": "object"
+}
```

removedOutput schema / properties / results / description

Removed value: -"Collection of normalized Medicare-certified provider records matching the search."

changedOutput schema / properties / results / items / properties / address / description

Previous value: -"Public street address reported by CMS."New value: +"Public street address reported by the source."

addedOutput schema / properties / results / items / properties / address / title
```
Added value: +"Street address"
```

changedOutput schema / properties / results / items / properties / beds / description

Previous value: -"Number of certified beds. Nursing homes and long-term care hospitals only."New value: +"Structured beds value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / beds / title
```
Added value: +"Beds"
```

changedOutput schema / properties / results / items / properties / ccn / description

Previous value: -"CMS Certification Number, the stable identifier for the provider (hospitals use their facility ID here)."New value: +"Structured ccn value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / ccn / title
```
Added value: +"Ccn"
```

changedOutput schema / properties / results / items / properties / certification_date / description

Previous value: -"Date CMS certified the provider, in YYYY-MM-DD form where available."New value: +"Structured certification date value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / certification_date / title
```
Added value: +"Certification Date"
```

changedOutput schema / properties / results / items / properties / chain / description

Previous value: -"Chain or corporate ownership group name, when CMS reports one. Nursing homes and dialysis facilities only."New value: +"Structured chain value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / chain / title
```
Added value: +"Chain"
```
addedOutput schema / properties / results / items / properties / city / title
```
Added value: +"City"
```

changedOutput schema / properties / results / items / properties / county / description

Previous value: -"County reported for the record."New value: +"Structured county value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / county / title
```
Added value: +"County"
```

changedOutput schema / properties / results / items / properties / emergency_services / description

Previous value: -"Whether the hospital reports emergency services ('Yes'/'No'). Hospitals only."New value: +"Structured emergency services value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / emergency_services / title
```
Added value: +"Emergency Services"
```

changedOutput schema / properties / results / items / properties / name / description

Previous value: -"Facility or provider name as published by CMS."New value: +"Organization, company, facility or record name as published by the source."

addedOutput schema / properties / results / items / properties / name / title
```
Added value: +"Name"
```

changedOutput schema / properties / results / items / properties / ownership / description

Previous value: -"Ownership or profit status as classified by CMS for this directory."New value: +"Structured ownership value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / ownership / title
```
Added value: +"Ownership"
```

changedOutput schema / properties / results / items / properties / phone / description

Previous value: -"Public provider telephone number in CMS display format."New value: +"Public provider telephone number in source display format."

addedOutput schema / properties / results / items / properties / phone / title
```
Added value: +"Telephone number"
```

changedOutput schema / properties / results / items / properties / provider_type / description

Previous value: -"Which CMS directory this row came from (hospital, nursing_home, home_health, hospice, dialysis, long_term_care_hospital, or inpatient_rehab)."New value: +"Structured provider type value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / provider_type / title
```
Added value: +"Provider Type"
```

changedOutput schema / properties / results / items / properties / star_rating / description

Previous value: -"CMS overall one-to-five star rating for the provider, when the directory publishes one."New value: +"Structured star rating value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / star_rating / title
```
Added value: +"Star Rating"
```

changedOutput schema / properties / results / items / properties / state / description

Previous value: -"Two-letter US state or territory abbreviation."New value: +"US state or territory abbreviation."

addedOutput schema / properties / results / items / properties / state / title
```
Added value: +"State"
```

changedOutput schema / properties / results / items / properties / subtype / description

Previous value: -"Directory-specific subtype, e.g. hospital type for hospitals or provider type for nursing homes."New value: +"Structured subtype value returned by official CMS Provider Data Catalog APIs."

addedOutput schema / properties / results / items / properties / subtype / title
```
Added value: +"Subtype"
```
addedOutput schema / properties / results / items / properties / zip / title
```
Added value: +"Postal code"
```
removedOutput schema / properties / results / items / required
```
Removed value: -[
-  "ccn",
-  "name"
-]
```
addedOutput schema / properties / run
```
Added value: +{
+  "type": "object"
+}
```

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "success",
+    "empty_unverified",
+    "partial",
+    "error"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "results"
-]New value: +[
+  "results",
+  "status"
+]

Addedv1.0.11Sep 13, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover readOnly/openWorld/destructive hints, but the description adds substantial operational detail: synchronous network execution via a named Apify Actor, billing side effects, APIFY_TOKEN requirement, latency expectations, and a 120-second timeout cap. There is no contradiction with the annotations; the billed run is a side effect of a read-only data fetch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is organized into labeled sections that front-load the core behavior and then cover operational and usage details. It is longer than average, but every section carries decision-relevant information such as auth, billing, latency, exclusions, and named alternatives.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers scope, return shape, execution model, side effects, authentication, latency limits, exclusions, and alternatives. An output schema exists for detailed return values, and annotations cover the safety profile, so nothing critical is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already includes type, constraints, defaults, examples, and behavioral notes such as the hospital-only fallback for provider_types. The description reinforces that results are normalized and covers the seven provider types, but it adds little per-parameter meaning beyond what the input schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Search') plus a precise resource: official CMS Provider Data Catalog directories for Medicare-certified providers. It enumerates all seven provider types and clarifies the consistent row shape, so an agent knows exactly what kind of data is returned. This clearly differentiates it from the many general-purpose sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description contains explicit 'When to use' and 'When NOT to use' sections, and it names exact alternative tools such as clinical_trials_search, epa_facility_search, and us_contractor_license_search. An agent can route correctly without needing to inspect other tool schemas.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.