Setup

Are you a R developer? Check out [rhud](https://github.com/etam4260/rhud) instead.

To install from pypi use:

pip install hudpy

You can install the development version by cloning the repository

git clone https://github.com/etam4260/hudpy.git

and then running...

pip install hudpy

The US Department of Housing and Urban Development HUD USER requires users to gain an access key before querying their systems. You must go to https://www.huduser.gov/hudapi/public/register?comingfrom=1 and follow the instructions for making an account.

From the website, you need to make a new token. Make sure to save the token somewhere as you will only be able to view it once. However, you can use it as many times as you want. You can now supply the 'key' argument to the function calls.

Setting the Key

hud_set_key("2yeuduhq72ueajk", in_home = TRUE)

You can also tell RStudio to remember the key by setting in_wkdir and in_home parameter to TRUE which will write Sys.setenv("your-key") to your .Rprofile.

To check whether rhud can gain access to this environment variable...

hud_get_key()

It is now set up for the rest of the R session.

Setting a user agent

It is recommended to set a user agent before querying. This tells the HUD servers a bit more about the querying application or user.

hud_set_user_agent("This Application")

If no user agent is set, it will return an empty string.

hud_get_user_agent()

Understanding the Syntax

A noticeable issue with querying geographic data is determining what resolution the data is returned in. Therefore, understanding the syntax of these function calls should easily help you determine what you are querying and what data is returned.

The general syntax for these functions within the package follow this pattern where {1},{2}, and {3} are placeholders:

hud_{1}_{2}_{3}

{1}: This symbol represents the dataset to query for. So for example if you want fair markets rent data, this will be 'fmr'. If you want data from the crosswalk files, this will be 'cw'.

{2}: This symbol represents the geographic resolution to query for. For example, if the function requires that you input state(s), then this will be named as 'state.' If the function requires that you input county(s) then this will be 'county'.

{3}: This symbol represented the output geographic resolution. So for example, if we want data at a zip code level, then this will have 'zip'.

For those that do not have the {2} and {3}, these are omni functions which are capable of performing all queries under {1}, but these functions are harder to understand.

For those that do not have the {3}, it inherits the {2}. This means that if {2} is a state input, then the data described by the output data is also a state.

A quick example:

hud_cw_county_zip(county = 22031, year = c('2017'), quarter = c('1'))

The first part of the function begins with 'hud'.

The second part is 'cw' meaning we are querying the crosswalk files.

The third part is 'county' meaning we need to input county(s)

The fourth part is the 'zip' meaning the data will be returned at a zip code resolution.

Additional Help

If you ever get confused or need help you can easily revisit this website where you can check the all the function definitions in the *Reference* tab.

rhud_website()

This will quickly open up this website on your web browser as well as the github repository where you can submit issues.