In etam4260/rhud: A R interface for accessing HUD (US Department of Housing and Urban Development) APIs

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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][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 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.

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

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

References

| "Income Limits | HUD USER." Huduser.gov, 2015, | www.huduser.gov/portal/datasets/il.html.

etam4260/rhud documentation built on Nov. 12, 2022, 2:53 a.m.