Income Limits

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] Parameters as well as [output data] Returns 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 IL 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 = ['VA', 'MD'], year = ['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.

# Gets il data for METRO area.
hud_il(query = "METRO47900M47900", year = [2018])

Most recent Income Limits files

To get the most recent Income Limits files by year:

hud_rec_il_yr()

Querying for Geographic Identifers

US States

This is an example to show you how to query for all states and territories in the US.

hud_nation_states_territories()

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(["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

Years 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 = "a-sample-key"

Returns

Data

Description

query

Identifier for county, state, or cbsadiv depending on function

year

Year when measurement was taken.

  • year = c(2019, 2018, 2021)

  • year = c(2016)

  • year = 2021

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 region

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

References

"Income Limits | HUD USER." Huduser.gov, 2015,

www.huduser.gov/portal/datasets/il.html.