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.
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 |
|||||||||||||||||||||||||
|
||||||||||||||||||||||||||
object |
Extremely Low (30%) Income Limits |
|||||||||||||||||||||||||
|
||||||||||||||||||||||||||
object |
Low (80%) Income Limits |
|||||||||||||||||||||||||
|
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 } }