FMR IL Dataset API Documentation

FMR & IL API

Click here to view Terms of Service of the HUD User API

Getting an Access Token

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

Sign up for an account and select the Datasets API you want to access.
Confirm your account, if it's new - Check your inbox for a confirmation email from HUD User.
After log in, Get an access token by clicking on Create New Token.
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.

Access Token:

entityid:

year:

Access Token:

state_code:

year:

Access Token:

entityid:

year:

Access Token:

state_code:

year:

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

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%)

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%)

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