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 is stored in the format {"field_name1":"field_value1","field_name2":"field_value2"}. For example, the data about the Duke University Health System in Durham, NC looks like:

{"hospital_system_id":"205","name":"Duke University Health System","street_address":"Erwin Road","city":"Durham","state":"NC","zip_code":"27710","updated_dt":"November 21, 2017"}

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:

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 hospital systems 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_hospital_systems.json.

Retrieving hospital systems

api/get_hospital_systems.php

Provides hospital systems in JSON format

GET Parameters

Fields returned

Code Description
hospital_system_idInternal hospital system ID
nameHospital system name
street_addressStreet address
cityCity
stateState
zip_codeZip code
updated_dtDate record was updated

Retrieving hospitals

api/get_hospitals.php

Provides hospitals in JSON format

GET Parameters

Fields returned

Code Description
hospital_idInternal hospital ID
einHospital EIN
nameHospital name
street_addressStreet address
cityCity
stateState
zip_codeZip code
american_association_idAmerican Hospital Association (AHA) ID
medicare_provider_numberMedicare provider number
fips_state_and_county_codeFIPS state and county code
chrch_affl_fChurch affiliation flag
memb_counc_teach_hosps_fMember of the Council of Teaching Hospitals flag
urban_location_fUrban location flag
children_hospital_fChildren hospital flag
countyHospital county
hospital_bed_sizeHospital bed size
updated_dtDate record was updated

Retrieving hospital data

api/get_hospital_data.php

Provides hospital data in JSON format

GET Parameters

Fields returned

Code Description
hospital_data_idInternal hospital data ID
fiscal_yrFiscal Year
form_990_filed_part_grp_ret_fForm 990 was filed as part of a group return
form_990_nameForm 990 name
tot_func_expTotal functional expenses
tot_revenueTotal revenue
tot_comm_bnftsTotal community benefits
chrty_careCharity care
unreim_medcdUnreimbursed Medicaid
unreim_costsUnreimbursed costs
comm_hlth_impr_svcs_comm_bnft_operCommunity health improvement services and community benefit operations
hlth_prof_educHealth professions education
subsd_hlth_svcsSubsidized health services
rsrchResearch
cash_inknd_contrib_comm_grpsCash and in-kind contributions to community groups
comm_bldg_actvsCommunity building activities
bad_debtBad debt
bad_debt_tot_func_exp_atrb_pat_elig_fncl_asstBad debt, attributable to patients eligible for financial assistance
mdcre_shrtflMedicare Shortfall (negative value indicates surplus)
tot_comm_bnfts_tot_func_exp_pctTotal community benefits as % of total functional expenses
chrty_care_tot_func_exp_pctCharity care as % of total functional expenses
unreim_medcd_tot_func_exp_pctUnreimbursed Medicaid as % of total functional expenses
unreim_costs_tot_func_exp_pctUnreimbursed costs as % of total functional expenses
comm_hlth_impr_svcs_comm_bnft_oper_tot_func_exp_pctCommunity health improvement services and community benefit operations as % of total functional expenses
hlth_prof_educ_tot_func_exp_pctHealth professions education as % of total functional expenses
subsd_hlth_svcs_tot_func_exp_pctSubsidized health services as % of total functional expenses
rsrch_tot_func_exp_pctResearch as % of total functional expenses
cash_inknd_contrib_comm_grps_tot_func_exp_pctCash and in-kind contributions to community groups as % of total functional expenses
hosp_rpt_comm_bldg_actvs_fDid hospital report community building activities?
comm_bldg_actvs_tot_func_exp_pctCommunity building activities as % of total functional expenses
bad_debt_tot_func_exp_pctBad debt as % of total functional expenses
bad_debt_tot_func_exp_atrb_pat_elig_fncl_asst_pctBad debt as % of total functional expenses, attributable to patients eligible for financial assistance
mdcre_shrtfl_tot_func_exp_pctMedicare Shortfall as % of total functional expenses (negative value indicates surplus)
rat_pat_care_npat_care_comm_bnftsRatio of Patient Care to Non-patient Care Community Benefits
sole_comm_prov_fSole community provider
written_fncl_asst_policy_fWritten financial assistance policy
used_fed_pov_gdlns_det_elig_free_disc_care_fUsed federal poverty guidelines to determine eligibility for free or discounted care
rpted_credit_agency_fReported to credit agency
filed_lawsuit_fFiled lawsuit
placed_liens_resdnc_fPlaced liens on residence
issued_body_attch_fIssued body attachments
chna_cond_comm_hlth_needs_assmt_fConducted community health needs assessment (CHNA)
chna_defined_comm_served_fCHNA defined the community served
chna_took_into_acct_input_ppl_rep_broad_intrst_comm_served_fCHNA took into account input from persons who represent broad interests of the community served
chna_cond_w_mult_hosp_facilities_fCHNA conducted with multiple hospital facilities
chna_made_wide_avail_pub_fCHNA made widely available to the public
hosp_adp_imp_stg_addr_hlth_needs_comm_fHospital adopted implementation strategy to address health needs of community
hosp_exe_imp_stg_addr_hlth_needs_comm_fHospital executed implementation strategy addressing health needs of community
hosp_prtcp_dev_commwide_comm_bnft_plan_fHospital participated in development of community-wide community benefit plan
per_capita_inc_qrtQuartile of per capita income
med_hsehld_inc_qrtQuartile of median household income
percent_ppl_pov_qrtQuartile of percent persons in poverty
percent_ppl_65_yrs_old_without_hlth_insr_qrtQuartile of percent persons <65 years old without health insurance
unemp_rate_16_yrs_older_qrtQuartile of unemployment rate, 16 years and older
st_impl_aca_medcd_exp_cvrg_adlts_w_incs_up_138pct_fpl_fState implemented ACA Medicaid expansion covering adults with incomes up to 138% FPL
st_inc_elig_prnts_dep_chldrn_enrol_medcd_ltd_76pct_fpl_less_fState income eligibility for parents of dependent children enrolling in Medicaid limited to 76% FPL or less
st_law_req_hosp_rpt_comm_bnfts_fState law requiring hospital to report community benefits
updated_dtDate record was updated