FMR IL Dataset API Documentation

Dataset/FMR IL Dataset API Documentation

• Other Datasets

FMR & IL API

Getting an Access Token

Follow these steps to create an account and get an access token:

1. Sign up for an account and select the Datasets API you want to access.
2. Confirm your account, if it's new - Check your inbox for a confirmation email from HUD User.
3. After log in, Get an access token by clicking on Create New Token.
4. Use it in the Authorization: Bearer header to make API calls.

Base URL

The base URL for all FMR API endpoints is https://www.huduser.gov/hudapi/public/fmr
The table below shows the path that completes the URI for each endpoint.

To..	Endpoint
Get a list of all states	fmr/listStates
Get a list of all counties in a state	fmr/listCounties/{stateid}
Get a list of all Metropolitan areas	fmr/listMetroAreas
Get FMR data for a town(in NE state), county or metropolitan area.	fmr/data/{entityid}
Get FMR data for a state.	fmr/statedata/{statecode}
Get IL data for a town(in NE state), county or metropolitan area.	il/data/{entityid}
Get IL data for a state.	il/statedata/{statecode}

Response Codes

One of the following response codes will be returned with every request:

code	description
200	Request was successful
400	An invalid value was specified for one of the query parameters in the request URI.
401	Authentication failure
403	Not allowed to access this dataset API because you have not registered for it.
404	No data found using '(value you entered)'
405	Unsupported method, only GET is supported
406	Unsupported Accept Header value, must be application/json
500	Internal server error occurred

Input parameters

These parameters appear after a question mark (?) in the endpoint. They are separated using the ampersand (&) character.

name	description
year	Year of the data to retrieve E.g. 2017. Default is latest year. Optional

Example Call

Pass the accesstoken in the header to make API calls. An example using the command-line client curl is shown below:

  curl -H "Authorization: Bearer YOUR_API_KEY" https://www.huduser.gov/hudapi/public/fmr/data/0801499999 

API Tester

Use the API Tester to make API calls to Datasets. The API Tester requires an access token. If you have forgotten or do not have a token, click here.

Response Structure for /listStates

property	type	description
state_name	string	State name
state_code	string	State code
state_num	string	State number
category	string	Value is "State"

Response Example for /listStates

API call: https://www.huduser.gov/hudapi/public/fmr/listStates

	
		"data":[
		{
		"state_name": "Alabama",
		"state_code": "AL",
		"state_num": "1",
		"category": "State"
		},	
		{
		"state_name": "Alaska",
		"state_code": "AK",
		"state_num": "2",
		"category": "State"
		},
		{
		"state_name": "American Samoa",
		"state_code": "AS",
		"state_num": "60",
		"category": "State"
		},
		...
		]
	

Response Structure for /listCounties/{state_code}

property	type	description
state_code	string	State code
fips_code	string	fips code of the county
county_name	string	County name
town_name	string	Town name - applicable for North East regions
category	string	Value is "County"

Response Example for /listCounties/{state_code}

API call: https://www.huduser.gov/hudapi/public/fmr/listCounties/VA

	
		"data":[
		{
		"state_code": "VA",
		"fips_code": "5100199999",
		"county_name": "Accomack County",
		"town_name": "",
		"category": "County"
		},
		{
		"state_code": "VA",
		"fips_code": "5100399999",
		"county_name": "Albemarle County",
		"town_name": "",
		"category": "County"
		},
		{
		"state_code": "VA",
		"fips_code": "5151099999",
		"county_name": "Alexandria city",
		"town_name": "",
		"category": "County"
		},
		...
		]
	

Response Structure for /listMetroAreas

property	type	description
cbsa_code	string	cbsa code of the Metropolitan Area
area_name	string	area name
category	string	Value is "MetroArea"

Response Example for /listMetroAreas

API call: https://www.huduser.gov/hudapi/public/fmr/listMetroAreas

	
		"data":[
		{
		"cbsa_code": "METRO10180M10180",
		"area_name": "Abilene, TX MSA",
		"category": "MetroArea"
		},
		{
		"cbsa_code": "METRO29180N22001",
		"area_name": "Acadia Parish, LA HUD Metro FMR Area",
		"category": "MetroArea"
		},
		{
		"cbsa_code": "METRO10380M10380",
		"area_name": "Aguadilla-Isabela, PR HUD Metro FMR Area",
		"category": "MetroArea"
		},
		...
		]
	

Response Structure for fmr/data/{entityid}?year=2017

property	type	description
county_name	string	Name of the county if it is a county.
counties_msa	string	Names of all counties belonging to the Metro Area if it is a Metro Area (MSA).
town_name	string	Town name - applicable for North East regions
metro_status	string	value will be "1" if it is a metropolitan county. Otherwise value will be "0".
metro_name	string	Metro area name if metro_status is "1"
smallarea_status	string	value will be "1" if it is a small area. Otherwise value will be "0".
basicdata	object	Data for the requested year.
Efficiency	string	Efficiency FMR
One-Bedroom	string	1-bedroom FMR
Two-Bedroom	string	2-bedroom FMR
Three-Bedroom	string	3-bedroom FMR
Four-Bedroom	string	4-bedroom FMR
year	string	Value of year

Response Example for fmr/data/{entityid}?year=2017

API call: https://www.huduser.gov/hudapi/public/fmr/data/5002175925?year=2017

	
		"data": {
        "county_name": "Rutland County, VT",
        "counties_msa": "",
        "town_name": "Wallingford town",
        "metro_status": "0",
        "metro_name": "",
        "basicdata": {
		"Efficiency": "758.0",
		"One-Bedroom": "769.0",
		"Two-Bedroom": "948.0",
		"Three-Bedroom": "1186.0",
		"Four-Bedroom": "1386.0",
		"year": "2017"
        },
        
		}
	

Response Example for fmr/data/{entityid} if entity will use Small Area FMRs as defined by ZIP codes.

API call: https://www.huduser.gov/hudapi/public/fmr/data/METRO47900M47900

	
		"data": {
		"county_name": "",
		"counties_msa": "District of Columbia, DC; Calvert County, MD; Charles County, MD; Frederick County, MD; Montgomery County, MD; Prince George's County, MD; Arlington County, VA; Clarke County, VA; Fairfax County, VA; Fauquier County, VA; Loudoun County, VA; Prince William County, VA; Spotsylvania County, VA; Stafford County, VA; Alexandria city, VA; Fairfax city, VA; Falls Church city, VA; Fredericksburg city, VA; Manassas city, VA; and Manassas Park city, VA.",
		"town_name": "",
		"metro_status": "1",
		"metro_name": "Washington-Arlington-Alexandria, DC-VA-MD-WV MSA",
		"area_name": "Washington-Arlington-Alexandria, DC-VA-MD HUD Metro FMR Area",
		"smallarea_status": "1",
		"year": "2018",
		"basicdata": [
		{   
		"zip_code": "20001",
		"efficiency": "1550",
		"One-Bedroom": "1610",
		"Two-Bedroom": "1840",
		"Three-Bedroom": "2420",
		"Four-Bedroom": "2990",            
		},
		{   
		"zip_code": "20002",
		"efficiency": "1300",
		"One-Bedroom": "1360",
		"Two-Bedroom": "1570",
		"Three-Bedroom": "2070",
		"Four-Bedroom": "2570",            
		},
		{
		"zip_code": "20003",
		"efficiency": "2080",
		"One-Bedroom": "2160",
		"Two-Bedroom": "2480",
		"Three-Bedroom": "3250",
		"Four-Bedroom": "4010",
		},
		...
		]
		}
	

Response Structure for fmr/statedata/{statecode}?year=2017

property	type	description
year	String	The year of the data being displayed
metroareas	array	Data of all metro areas in this State
counties	array	Data of all counties in this State
code	string	code of cbsa/county
name	string	Name of the cbsa/county
Efficiency	string	Efficiency FMR
One-Bedroom	string	1-bedroom FMR
Two-Bedroom	string	2-bedroom FMR
Three-Bedroom	string	3-bedroom FMR
Four-Bedroom	string	4-bedroom FMR
statename	string	state name
state_code	string	state code
town_name	string	Town name - applicable for North East States
smallarea_status	string	value will be "1" if it is a small area. Otherwise value will be "0".

Response Example for fmr/statedata/{statecode}

API call: https://www.huduser.gov/hudapi/public/fmr/statedata/MA

		"data": {
        "year": "2018",
        "metroareas": [
		{
		"code": "METRO12700M12700",
		"name": "Barnstable Town, MA MSA",
		"state_name": "Massachusetts",
		"state_code": "MA",
		"Efficiency": "925.0",
		"One-Bedroom": "1048.0",
		"Two-Bedroom": "1394.0",
		"Three-Bedroom": "1757.0",
		"Four-Bedroom": "1919.0",
		"smallarea_status": 0
		},
		{
		"code": "METRO38340N25003",
		"name": "Berkshire County, MA (part) HUD Metro FMR Area",
		"state_name": "Massachusetts",
		"state_code": "MA",
		"Efficiency": "836.0",
		"One-Bedroom": "849.0",
		"Two-Bedroom": "988.0",
		"Three-Bedroom": "1239.0",
		"Four-Bedroom": "1441.0",
		"smallarea_status": 0
		},
    	...
		]
		,
		"counties": [
		{
		"town_name": "Abington town",
		"county_name": "Plymouth County",
		"metro_name": "Brockton, MA HUD Metro FMR Area",
		"fips_code": "2502300170",
		"Efficiency": 1064,
		"One-Bedroom": 1160,
		"Two-Bedroom": 1528,
		"Three-Bedroom": 1918,
		"Four-Bedroom": 2240,
		"FMR Percentile": 40,
		"statename": "Massachusetts",
		"statecode": "MA",
		"smallarea_status": 0
		},
		{
		"town_name": "Acton town",
		"county_name": "Middlesex County",
		"metro_name": "Boston-Cambridge-Quincy, MA-NH HUD Metro FMR Area",
		"fips_code": "2501700380",
		"Efficiency": 1715,
		"One-Bedroom": 1900,
		"Two-Bedroom": 2311,
		"Three-Bedroom": 2880,
		"Four-Bedroom": 3131,
		"FMR Percentile": 40,
		"statename": "Massachusetts",
		"statecode": "MA",
		"smallarea_status": 0
		},
    	...
    	]
		]
	

Response Structure for il/data/{entityid}?year=2017

property	type	description
county_name	string	Name of the county if it is a county.
counties_msa	string	Names of all counties belonging to the Metro Area if it is a Metro Area (MSA).
town_name	string	Town name - applicable for North East regions
metro_status	string	value will be "1" if it is a metropolitan county. Otherwise value will be "0".
metro_name	string	Metro area name if metro_status is "1"
year	string	year of the data
median_income	string	Median Income for the area
very_low +	object	Very Low (50%) Income Limits
il50_p1 string 1 person family IL (50%) il50_p2 string 2 person family IL (50%) il50_p3 string 3 person family IL (50%) il50_p4 string 4 person family IL (50%) il50_p5 string 5 person family IL (50%) il50_p6 string 6 person family IL (50%) il50_p7 string 7 person family IL (50%) il50_p8 string 8 person family IL (50%)
extremely_low +	object	Extremely Low (30%) Income Limits
il30_p1 string 1 person family IL (80%) il30_p2 string 2 person family IL (80%) il30_p3 string 3 person family IL (80%) il30_p4 string 4 person family IL (80%) il30_p5 string 5 person family IL (80%) il30_p6 string 6 person family IL (80%) il30_p7 string 7 person family IL (80%) il30_p8 string 8 person family IL (80%)
low +	object	Low (80%) Income Limits
il80_p1 string 1 person family IL (80%) il80_p2 string 2 person family IL (80%) il80_p3 string 3 person family IL (80%) il80_p4 string 4 person family IL (80%) il80_p5 string 5 person family IL (80%) il80_p6 string 6 person family IL (80%) il80_p7 string 7 person family IL (80%) il80_p8 string 8 person family IL (80%)

Response Example for il/data/0100199999

API call: https://www.huduser.gov/hudapi/public/il/data/0100199999

		"data": {
        "county_name": "Autauga County, AL",
        "counties_msa": "",
        "town_name": "",
        "metro_status": "1",
        "metro_name": "Montgomery, AL MSA",
        "area_name": "Montgomery, AL MSA",
        "year": "2019",
        "median_income": 65900,
        "very_low": {
		"il50_p1": 23100,
		"il50_p2": 26400,
		"il50_p3": 29700,
		"il50_p4": 32950,
		"il50_p5": 35600,
		"il50_p6": 38250,
		"il50_p7": 40900,
		"il50_p8": 43500
        },
        "extremely_low": {
		"il30_p1": 13850,
		"il30_p2": 16910,
		"il30_p3": 21330,
		"il30_p4": 25750,
		"il30_p5": 30170,
		"il30_p6": 34590,
		"il30_p7": 39010,
		"il30_p8": 43430
        },
        "low": {
		"il80_p1": 36900,
		"il80_p2": 42200,
		"il80_p3": 47450,
		"il80_p4": 52700,
		"il80_p5": 56950,
		"il80_p6": 61150,
		"il80_p7": 65350,
		"il80_p8": 69600
        }
		}