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}
Get MTSP IL data for a town(in NE state), county or metropolitan area.	mtspil/data/{entityid}

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:

Access Token:

entityid:

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.

Note: The field "zip_code": "MSA level" has been added to the API to provide MSA-level data for regions utilizing Small Area FMRs.

API call:

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

	"data": {
		"county_name": "",
		"counties_msa": "Alexandria city, VA; Arlington County, VA; Calvert County, MD; Charles County, MD; Clarke County, VA; District of Columbia, DC; Fairfax city, VA; Fairfax County, VA; Falls Church city, VA; Fauquier County, VA; Frederick County, MD; Fredericksburg city, VA; Loudoun County, VA; Manassas city, VA; Manassas Park city, VA; Montgomery County, MD; Prince George's County, MD; Prince William County, VA; Spotsylvania County, VA; and Stafford County, VA",
		"town_name": "",
		"metro_status": "1",
		"metro_name": "Washington-Arlington-Alexandria, DC-VA-MD-WV",
		"area_name": "Washington-Arlington-Alexandria, DC-VA-MD HUD Metro FMR Area",
		"smallarea_status": "1",
		"year": "2024",
		"basicdata": [
			{
				"zip_code": "MSA level",
				"Efficiency": 1772,
				"One-Bedroom": 1803,
				"Two-Bedroom": 2045,
				"Three-Bedroom": 2544,
				"Four-Bedroom": 3015
			},
			{
				"zip_code": "20001",
				"Efficiency": 2460,
				"One-Bedroom": 2500,
				"Two-Bedroom": 2840,
				"Three-Bedroom": 3530,
				"Four-Bedroom": 4190
			},
			{
				"zip_code": "20002",
				"Efficiency": 1750,
				"One-Bedroom": 1780,
				"Two-Bedroom": 2020,
				"Three-Bedroom": 2510,
				"Four-Bedroom": 2980
			},
			{
				"zip_code": "20003",
				"Efficiency": 2660,
				"One-Bedroom": 2710,
				"Two-Bedroom": 3070,
				"Three-Bedroom": 3820,
				"Four-Bedroom": 4530
			},
		...
		]
		}

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 (30%)
il30_p2	string	2 person family IL (30%)
il30_p3	string	3 person family IL (30%)
il30_p4	string	4 person family IL (30%)
il30_p5	string	5 person family IL (30%)
il30_p6	string	6 person family IL (30%)
il30_p7	string	7 person family IL (30%)
il30_p8	string	8 person family IL (30%)

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

Response Structure for mtspil/data/{entityid}?year=2024

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

il80_p1	string	1 person family MTSP IL (80%)
il80_p2	string	2 person family MTSP IL (80%)
il80_p3	string	3 person family MTSP IL (80%)
il80_p4	string	4 person family MTSP IL (80%)
il80_p5	string	5 person family MTSP IL (80%)
il80_p6	string	6 person family MTSP IL (80%)
il80_p7	string	7 person family MTSP IL (80%)
il80_p8	string	8 person family MTSP IL (80%)

il70_p1	string	1 person family MTSP IL (70%)
il70_p2	string	2 person family MTSP IL (70%)
il70_p3	string	3 person family MTSP IL (70%)
il70_p4	string	4 person family MTSP IL (70%)
il70_p5	string	5 person family MTSP IL (70%)
il70_p6	string	6 person family MTSP IL (70%)
il70_p7	string	7 person family MTSP IL (70%)
il70_p8	string	8 person family MTSP IL (70%)

il60_p1	string	1 person family MTSP IL (60%)
il60_p2	string	2 person family MTSP IL (60%)
il60_p3	string	3 person family MTSP IL (60%)
il60_p4	string	4 person family MTSP IL (60%)
il60_p5	string	5 person family MTSP IL (60%)
il60_p6	string	6 person family MTSP IL (60%)
il60_p7	string	7 person family MTSP IL (60%)
il60_p8	string	8 person family MTSP IL (60%)

il50_p1	string	1 person family MTSP IL (50%)
il50_p2	string	2 person family MTSP IL (50%)
il50_p3	string	3 person family MTSP IL (50%)
il50_p4	string	4 person family MTSP IL (50%)
il50_p5	string	5 person family MTSP IL (50%)
il50_p6	string	6 person family MTSP IL (50%)
il50_p7	string	7 person family MTSP IL (50%)
il50_p8	string	8 person family MTSP IL (50%)

il40_p1	string	1 person family MTSP IL (40%)
il40_p2	string	2 person family MTSP IL (40%)
il40_p3	string	3 person family MTSP IL (40%)
il40_p4	string	4 person family MTSP IL (40%)
il40_p5	string	5 person family MTSP IL (40%)
il40_p6	string	6 person family MTSP IL (40%)
il40_p7	string	7 person family MTSP IL (40%)
il40_p8	string	8 person family MTSP IL (40%)

il30_p1	string	1 person family MTSP IL (30%)
il30_p2	string	2 person family MTSP IL (30%)
il30_p3	string	3 person family MTSP IL (30%)
il30_p4	string	4 person family MTSP IL (30%)
il30_p5	string	5 person family MTSP IL (30%)
il30_p6	string	6 person family MTSP IL (30%)
il30_p7	string	7 person family MTSP IL (30%)
il30_p8	string	8 person family MTSP IL (30%)

il20_p1	string	1 person family MTSP IL (20%)
il20_p2	string	2 person family MTSP IL (20%)
il20_p3	string	3 person family MTSP IL (20%)
il20_p4	string	4 person family MTSP IL (20%)
il20_p5	string	5 person family MTSP IL (20%)
il20_p6	string	6 person family MTSP IL (20%)
il20_p7	string	7 person family MTSP IL (20%)
il20_p8	string	8 person family MTSP IL (20%)

hera_special_il50_p1	string	1 person family MTSP HERA Special IL (50%)
hera_special_il50_p2	string	2 person family MTSP HERA Special IL (50%)
hera_special_il50_p3	string	3 person family MTSP HERA Special IL (50%)
hera_special_il50_p4	string	4 person family MTSP HERA Special IL (50%)
hera_special_il50_p5	string	5 person family MTSP HERA Special IL (50%)
hera_special_il50_p6	string	6 person family MTSP HERA Special IL (50%)
hera_special_il50_p7	string	7 person family MTSP HERA Special IL (50%)
hera_special_il50_p8	string	8 person family MTSP HERA Special IL (50%)

hera_special_il60_p1	string	1 person family MTSP HERA Special IL (60%)
hera_special_il60_p2	string	2 person family MTSP HERA Special IL (60%)
hera_special_il60_p3	string	3 person family MTSP HERA Special IL (60%)
hera_special_il60_p4	string	4 person family MTSP HERA Special IL (60%)
hera_special_il60_p5	string	5 person family MTSP HERA Special IL (60%)
hera_special_il60_p6	string	6 person family MTSP HERA Special IL (60%)
hera_special_il60_p7	string	7 person family MTSP HERA Special IL (60%)
hera_special_il60_p8	string	8 person family MTSP HERA Special IL (60%)

Response Example for mtspil/data/METRO11020M11020

API call:

https://www.huduser.gov/hudapi/public/mtspil/data/METRO11020M11020

		{
            "data": {
                "county_name": "",
                "counties_msa": "Blair County, PA; ",
                "town_name": "",
                "metro_status": "1",
                "metro_name": "Altoona, PA",
                "area_name": "Altoona, PA MSA",
                "year": "2024",
                "median_income": 86900,
                "80percent": {
                    "il80_p1": 47600,
                    "il80_p2": 54320,
                    "il80_p3": 61120,
                    "il80_p4": 67920,
                    "il80_p5": 73360,
                    "il80_p6": 78800,
                    "il80_p7": 84240,
                    "il80_p8": 89680
                },
                "70percent": {
                    "il70_p1": 41650,
                    "il70_p2": 47530,
                    "il70_p3": 53480,
                    "il70_p4": 59430,
                    "il70_p5": 64190,
                    "il70_p6": 68950,
                    "il70_p7": 73710,
                    "il70_p8": 78470
                },
                "60percent": {
                    "il60_p1": 35700,
                    "il60_p2": 40740,
                    "il60_p3": 45840,
                    "il60_p4": 50940,
                    "il60_p5": 55020,
                    "il60_p6": 59100,
                    "il60_p7": 63180,
                    "il60_p8": 67260
                },
                "50percent": {
                   ...
                },
                "40percent": {
                   ...
                },
                "30percent": {
                   ...
                },
                "20percent": {
                    ...
                },
                "hera_special_50percent": {
                    "hera_special_il50_p1": 30950,
                    "hera_special_il50_p2": 35350,
                    "hera_special_il50_p3": 39750,
                    "hera_special_il50_p4": 44150,
                    "hera_special_il50_p5": 47700,
                    "hera_special_il50_p6": 51250,
                    "hera_special_il50_p7": 54750,
                    "hera_special_il50_p8": 58300
                },
                "hera_special_60percent": {
                    "hera_special_il60_p1": 37140,
                    "hera_special_il60_p2": 42420,
                    "hera_special_il60_p3": 47700,
                    "hera_special_il60_p4": 52980,
                    "hera_special_il60_p5": 57240,
                    "hera_special_il60_p6": 61500,
                    "hera_special_il60_p7": 65700,
                    "hera_special_il60_p8": 69960
                }
            }
        }

ABOUT PD&R

RESEARCH & PUBLICATIONS

DATASETS

QUICK LINKS

ABOUT PD&R

RESEARCH & PUBLICATIONS

DATASETS

QUICK LINKS

FMR IL Dataset API Documentation