Header Image for Print
Dataset Banner Image

FMR IL Dataset API Documentation


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

Code sample

	
		<html>	
		<body>
		<script>
		function loadJson() {
		var xhttp = new XMLHttpRequest();
		var url = "https://www.huduser.gov/hudapi/public/fmr/data/{entityid}?year=2018";
		xhttp.open("GET",url, true);
		xhttp.setRequestHeader("Authorization", "Bearer YOUR_API_KEY")
		xhttp.send();
		xhttp.onreadystatechange = function() {
		if (this.readyState == 4) {
		document.getElementById("demo").innerHTML = xhttp.responseText;
		}
		};
		}
		</script>
		
		<button type="submit" onclick="loadJson()">Try it! </button>
	    <div id="demo"> </div>	
		</body>
		</html>
	

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

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



 

 

 



Note: Guidance documents, except when based on statutory or regulatory authority or law, do not have the force and effect of law and are not meant to bind the public in any way. Guidance documents are intended only to provide clarity to the public regarding existing requirements under the law or agency policies.