Hospital Data API
What is an API?
An Application Programming Interface (API) allows a computer to fetch data from another computer. The Community Benefit Insight data API allows you to retrieve hospital data for use in research right from your web browser. The API returns data formatted in JSON - JavaScript Object Notation. In a JSON file, the data are stored in the format {"field_name1":"field_value1","field_name2":"field_value2"}. For example:
[{"hospital_id":"1","hospital_org_id":"1","ein":"123456789","name":"Hospital Name","street_address":"100 Street","city":"City Name","state":"XY","zip_code":"12345","updated_dt":"November 21, 2024"}]
Below are some resources about JSON and how to use it:
Using the Community Benefit Insight Hospital Data API
The Community Benefit Insight data API allows you to retrieve the following types of data:
- Hospital data (optionally filtered by state)
- Detailed data about a single hospital
The instructions below explain how to get each type of data and the fields that are returned. To see the data in your web browser, add the API links to the base Community Benefit Insight base URL. For example, to see all of the hospitals in North Carolina, you would enter:
http://www.communitybenefitinsight.org/api/get_hospitals.php?state=NC
Once you see the right data, you can copy and paste the text on the webpage into a text editor and save it with a .json extension. You can also save the file directly from your browser into a text file, but make sure it has a .json extension. In the example above you might save the file as nc_hospitals.json.
Retrieving hospitals
api/get_hospitals.phpProvides hospitals in JSON format
GET Parameters
-
state
Optional 2 character state postal code parameter to return hospitals within the provided state.
Example: api/get_hospitals.php?state=NC
Fields returned
| Code | Description |
|---|---|
| hospital_id | Internal hospital ID |
| hospital_org_id | Internal hospital organization ID |
| ein | Hospital EIN |
| name | Hospital name |
| name_cr | Hospital name from alternate source (CR) |
| street_address | Street address |
| city | City |
| state | State |
| zip_code | Zip code |
| medicare_provider_number | Medicare provider number |
| fips_state_and_county_code | FIPS state and county code |
| hospital_bed_count | Number of beds |
| chrch_affl_f | Church affiliation flag |
| memb_counc_teach_hosps_f | Member of the Council of Teaching Hospitals flag |
| urban_location_f | Urban location flag |
| children_hospital_f | Children hospital flag |
| county | Hospital county |
| hospital_bed_size | Hospital bed size |
| updated_dt | Date record was updated |
Retrieving hospital data for a single hospital
api/get_hospital_data.phpProvides hospital data in JSON format
GET Parameters
-
hospital_id
Required internal hospital ID parameter to return all years of hospital data for provided hospital.
Example: api/get_hospital_data.php?hospital_id=1000
Fields returned
| Code | Description |
|---|---|
| hospital_data_id | Internal hospital data ID |
| fiscal_yr | Fiscal Year |
| data_ein | EIN within data year |
| data_name | Hospital name within data year |
| form_990_filed_part_grp_ret_f | Form 990 was filed as part of a group return |
| form_990_num_fac_oper | Form 990 number of facilities operated |
| form_990_name | Form 990 name |
| tot_func_exp | Total functional expenses |
| tot_revenue | Total revenue |
| tot_comm_bnfts | Total community benefits |
| chrty_care | Charity care |
| unreim_medcd | Unreimbursed Medicaid |
| unreim_costs | Unreimbursed costs |
| comm_hlth_impr_svcs_comm_bnft_oper | Community health improvement services and community benefit operations |
| hlth_prof_educ | Health professions education |
| subsd_hlth_svcs | Subsidized health services |
| rsrch | Research |
| cash_inknd_contrib_comm_grps | Cash and in-kind contributions to community groups |
| comm_bldg_actvs | Community building activities |
| comm_bldg_actvs_physimprvhse | Physical improvements and housing |
| comm_bldg_actvs_econdevlp | Economic development |
| comm_bldg_actvs_cmntysuprt | Community support |
| comm_bldg_actvs_envrnimprv | Environmental improvements |
| comm_bldg_actvs_ldrdevlp | Leadership development and training for community members |
| comm_bldg_actvs_cltnbldg | Coalition building |
| comm_bldg_actvs_htlhimprvadvcy | Community health improvement advocacy |
| comm_bldg_actvs_wrkfrcdevlp | Workforce development |
| comm_bldg_actvs_other | Other |
| comm_bldg_actvs_physimprvhse_pct | Physical improvements and housing percentage of community building activities |
| comm_bldg_actvs_econdevlp_pct | Economic development percentage of community building activities |
| comm_bldg_actvs_cmntysuprt_pct | Community support percentage of community building activities |
| comm_bldg_actvs_envrnimprv_pct | Environmental improvements percentage of community building activities |
| comm_bldg_actvs_ldrdevlp_pct | Leadership development and training for community members percentage of community building activities |
| comm_bldg_actvs_cltnbldg_pct | Coalition building percentage of community building activities |
| comm_bldg_actvs_htlhimprvadvcy_pct | Community health improvement advocacy percentage of community building activities |
| comm_bldg_actvs_wrkfrcdevlp_pct | Workforce development percentage of community building activities |
| comm_bldg_actvs_other_pct | Other percentage of community building activities |
| bad_debt | Bad debt |
| bad_debt_tot_func_exp_atrb_pat_elig_fncl_asst | Bad debt, attributable to patients eligible for financial assistance |
| mdcre_shrtfl | Medicare Shortfall (negative value indicates surplus) |
| tot_comm_bnfts_tot_func_exp_pct | Total community benefits as % of total functional expenses |
| chrty_care_tot_func_exp_pct | Charity care as % of total functional expenses |
| unreim_medcd_tot_func_exp_pct | Unreimbursed Medicaid as % of total functional expenses |
| unreim_costs_tot_func_exp_pct | Unreimbursed costs as % of total functional expenses |
| comm_hlth_impr_svcs_comm_bnft_oper_tot_func_exp_pct | Community health improvement services and community benefit operations as % of total functional expenses |
| hlth_prof_educ_tot_func_exp_pct | Health professions education as % of total functional expenses |
| subsd_hlth_svcs_tot_func_exp_pct | Subsidized health services as % of total functional expenses |
| rsrch_tot_func_exp_pct | Research as % of total functional expenses |
| cash_inknd_contrib_comm_grps_tot_func_exp_pct | Cash and in-kind contributions to community groups as % of total functional expenses |
| hosp_rpt_comm_bldg_actvs_f | Did hospital report community building activities? |
| comm_bldg_actvs_tot_func_exp_pct | Community building activities as % of total functional expenses |
| bad_debt_tot_func_exp_pct | Bad debt as % of total functional expenses |
| bad_debt_tot_func_exp_atrb_pat_elig_fncl_asst_pct | Bad debt as % of total functional expenses, attributable to patients eligible for financial assistance |
| mdcre_shrtfl_tot_func_exp_pct | Medicare Shortfall as % of total functional expenses (negative value indicates surplus) |
| rat_pat_care_npat_care_comm_bnfts | Ratio of Patient Care to Non-patient Care Community Benefits |
| sole_comm_prov_f | Sole community provider |
| written_fncl_asst_policy_f | Written financial assistance policy |
| used_fed_pov_gdlns_det_elig_free_disc_care_f | Used federal poverty guidelines to determine eligibility for free or discounted care |
| rpted_credit_agency_f | Reported to credit agency |
| filed_lawsuit_f | Filed lawsuit |
| placed_liens_resdnc_f | Placed liens on residence |
| issued_body_attch_f | Issued body attachments |
| chna_cond_comm_hlth_needs_assmt_f | Conducted community health needs assessment (CHNA) |
| chna_defined_comm_served_f | CHNA defined the community served |
| chna_took_into_acct_input_ppl_rep_broad_intrst_comm_served_f | CHNA took into account input from persons who represent broad interests of the community served |
| chna_cond_w_mult_hosp_facilities_f | CHNA conducted with multiple hospital facilities |
| chna_made_wide_avail_pub_f | CHNA made widely available to the public |
| hosp_adp_imp_stg_addr_hlth_needs_comm_f | Hospital adopted implementation strategy to address health needs of community |
| hosp_exe_imp_stg_addr_hlth_needs_comm_f | Hospital executed implementation strategy addressing health needs of community |
| hosp_prtcp_dev_commwide_comm_bnft_plan_f | Hospital participated in development of community-wide community benefit plan |
| per_capita_inc_qrt | Quartile of per capita income |
| med_hsehld_inc_qrt | Quartile of median household income |
| percent_ppl_pov_qrt | Quartile of percent persons in poverty |
| percent_ppl_65_yrs_old_without_hlth_insr_qrt | Quartile of percent persons <65 years old without health insurance |
| unemp_rate_16_yrs_older_qrt | Quartile of unemployment rate, 16 years and older |
| st_impl_aca_medcd_exp_cvrg_adlts_w_incs_up_138pct_fpl_f | State implemented ACA Medicaid expansion covering adults with incomes up to 138% FPL |
| st_inc_elig_prnts_dep_chldrn_enrol_medcd_ltd_76pct_fpl_less_f | State income eligibility for parents of dependent children enrolling in Medicaid limited to 76% FPL or less |
| st_law_req_hosp_rpt_comm_bnfts_f | State law requiring hospital to report community benefits |
| updated_dt | Date record was updated |
