Hospitals
Find hospitals and metro areas, read a hospital's file links and payers, and see what data is loaded.
Free lookups. They return ids and directory facts, which the paid search tools then take: find a metro, find its hospitals, then search their prices.
find_hospitals
Finds hospitals that publish a price file, by name, place or size.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 25 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
max_beds | integer | none | Most licensed beds. |
metro | string | none | Metro area (CBSA) code, 5 digits, for example 12060 for Atlanta. Find it with find_metro. |
min_beds | integer | none | Fewest licensed beds. |
near_address | string | none | A street address to search around. Use with radius_miles. |
q | string | none | Search the service description, up to 200 characters. |
radius_miles | number | 50 | Distance in miles from near_address. |
state | string | none | Two-letter US state, for example FL. A state on its own is not enough: add codes, apc, q or hospital_ids. |
zips | list of string | none | ZIP codes to search in. |
Every filter is optional but at least one is needed, and they combine. limit is at most 100, default 25. With near_address, rows are closest first and carry distance_miles. Each row has hospital_id, name, city, state, zip, ccn, beds, metro (CBSA code) and has_charges (its prices parsed).
get_hospital
One hospital's details, the links to its own price files, and the payer names it publishes.
| Parameter | Type | Default | What it does |
|---|---|---|---|
hospital_id | string | required | One hospital id (UUID), as returned by find_hospitals. |
hospital carries the address, phone, ccn, beds, metro, mrf_retrieved, data_status and page_url: the hospital's page on CognitoLabs, with its details, the insurers it lists, and the links to its own price files. find_hospitals rows carry the same page_url. payers lists each name as published with the carrier it maps to, up to 200.
find_metro
Finds a metro area (CBSA) by name, or the metro a ZIP code is in. The cbsa_code is what find_hospitals takes as metro.
| Parameter | Type | Default | What it does |
|---|---|---|---|
limit | integer | 20 | Most rows to return. Each tool has its own cap. On a free plan, paid data returns 8 rows whatever you ask for. |
q | string | none | Search the service description, up to 200 characters. |
state | string | none | Two-letter US state, for example FL. A state on its own is not enough: add codes, apc, q or hospital_ids. |
zip | string | none | A 5-digit ZIP code. |
Each row has cbsa_code, cbsa_title, state and hospitals. The best name match comes first, then the biggest metros; metros with no hospitals are left out. A rural ZIP is in no metro and returns no rows.
describe_coverage
Which states and years are loaded for each dataset, with the source links. It takes no parameters.
The answer opens with summary (states with price files, the newest price-file pull date, the datasets) and then has price_files (hospitals per state and how many parsed), utilization (code counts and year per state), payer_rates (hospitals, codes and newest file date per state) and sources (dataset, title, year and landing page; the first entry is the hospital price files and their pull date).
Example questions
- Which hospitals in the Atlanta metro publish prices?
- What metro is ZIP 30303 in?
- Which hospitals within 25 miles of 1 Peachtree St have more than 300 beds?
- Which states do you have data for?
- Which insurers does Grady publish rates for?