Program Overview
According to (Income Limits | HUD USER), HUD establishes income restrictions for assisted housing programs such as Public Housing, Section 8 project-based, Section 8 Housing Choice Voucher, Section 202 housing for the elderly, and Section 811 housing for persons with disabilities. For each metropolitan region, parts of some metropolitan areas, and non-metropolitan county, HUD creates income limitations based on Median Family Income estimates and Fair Market Rent area criteria.
Examples
This page contains basic examples of how to query the HUD Income Limits API. Before looking at the examples I reccomend first taking a look at the parameters as well as output data located at the bottom of the page.
Disclaimer: The output tables are too large to be displayed here so we choose to leave them out.
- Querying a state will return a single row containing the Income Limits for that state.
- Querying for a county will return the IL measurement for that county.
- Querying for a cbsa will return the measurement for that cbsa.
State Level Income Limits
These are examples which show you how to query the Income Limits on a state level basis. You can use the state abbreviation, state name, or state fipscode. It will return a single row indicating the income limits for that particular state.
# These function calls gets income limits data for the state of Virginia in 2021.
hud_il(query = 'VA', year = '2021')
hud_il(query= "Virginia", year = '2021')
hud_il(query= "51", year = '2021')
# You can also choose to query for multiple states or multiple years.
hud_il(query = c('VA', 'MD'), year = c('2021', '2019'))County Level Income Limits
These are examples that show you how to query the Income Limits on a county-level basis: counties are defined with a 2 digit state fipscode + 3 digit county fipscode. You also need a 99999 code added to the end. We currently don’t know why the extra 99999 is included and have not found any cases where it’s different. I recommend looking at US Counties to determine what counties are available for particular states.
# Getting a county requires a 2 digit state fip + 3 digit county fip + 99999
# This queries for Income Limits in 2017.
hud_il(query = '0100199999', year = '2017')Small Areas Income Limits
These are examples that show you how to query the Small Areas Income Limits. Small Areas are defined as metropolitan and micropolitan areas specified using CBSA codes. Currently, we know how to query for metropolitan small areas, but are not sure for micropolitan yet. I recommend looking at US Metropolitan Areas to determine what counties are available.
Most recent Income Limits files
To get the most recent Income Limits files by year:
# rhud::hud_rec_il_yr()Querying for Geographic Identifers
US Counties
This is an example to show you how to query for all counties in MD, Virginia, and California, respectively.
hud_state_counties("MD")
hud_state_counties("Virginia")
hud_state_counties("6")US Metropolitan Areas
This is an example to show you how to query for metropolitan areas for a state.
# Get all metropolitan areas in Maryland and Virginia.
hud_state_metropolitan(c("MD", "VA"))Parameters
| Parameters | Description |
|---|---|
| query |
Can provide either a 10 digit FIPS code which is almost always state
fips + county fips + 99999, or state abbreviation. Can also provide a
CBSA code. You are only allowed to query for metropolitan areas.
Run hud_states() to get a list of counties. Run hud_metropolitan(“MD”) to get a list of metropolitan areas in MD. Run hud_counties(“MD”) to get list of counties in MD. * query = ‘METRO12700M12700’ * query = ‘MD’ * query = ‘5100199999’ |
| year |
Year range of the data to retrieve: defaults to the current year.
* year = c(2019, 2018, 2021) * year = c(2016) * year = 2021 |
| key |
The API key provided by HUD USER. * key = “wqokqo2138jdi13wfwwfwcytjyr” |
Returns
| Data Field | Description |
|---|---|
| query | Identifier for county, state, or cbsadiv depending on function |
| year | Year when measurement was taken. |
| county_name | Name of the county if it is a county. |
| counties_msa | Names of all counties belonging to the Metro Area if it is a Metro Area (MSA). |
| town_name | Town name - applicable for North East regions |
| metro_status | value will be “1” if it is a metropolitan county. Otherwise value will be “0”. |
| metro_name | Metro area name if metro_status is “1” |
| smallarea_status | value will be “1” if it is a small area. Otherwise value will be “0”. |
| median_income | Median Income for this geographic identifier |
| very_low + | Very low (50%) Income Limits. For more details on il50 check the associated documentation at https://www.huduser.gov/portal/dataset/fmr-api.html |
| extremely_low + | Extremely low (30%) Income Limits. For more details on il30 check the associated documentation at https://www.huduser.gov/portal/dataset/fmr-api.html |
| low + | Low (80%) Income Limits. For more details on il80 check the associated documentation at https://www.huduser.gov/portal/dataset/fmr-api.html |