CONSOLIDATED PLANNING/CHAS Dataset API Documentation

Comprehensive Housing Affordability Strategy (CHAS) 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:

If you already have an account, Login and update the datasets you want to access in your account.
Otherwise 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 CHAS API endpoints is https://www.huduser.gov/hudapi/public/chas

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
type	REQUIRED; Must be a number between 1 and 5 depending on the Summary Level. 1 - Nation 2 - State 3 - County 4 - MCD 5 - Place
year	Year range of the data to retrieve. Default is latest year range. Optional 2014-2018 2013-2017 2012-2016 2011-2015 2010-2014 2009-2013 2008-2012 2007-2011 2006-2010
stateId	REQUIRED for type 2, 3, 4 and 5; Must be a number between 1 and 56. 1 - Alabama 2 - Alaska 4 - Arizona 5 - Arkansas 6 - California 8 - Colorado 9 - Connecticut 10 - Delaware 11 - District of Columbia 12 - Florida 13 - Georgia 15 - Hawaii 16 - Idaho 17 - Illinois 18 - Indiana 19 - Iowa 20 - Kansas 21 - Kentucky 22 - Louisiana 23 - Maine 24 - Maryland 25 - Massachusetts 26 - Michigan 27 - Minnesota 28 - Mississippi 29 - Missouri 30 - Montana 31 - Nebraska 32 - Nevada 33 - New Hampshire 34 - New Jersey 35 - New Mexico 36 - New York 37 - North Carolina 38 - North Dakota 39 - Ohio 40 - Oklahoma 41 - Oregon 42 - Pennsylvania 72 - Puerto Rico 44 - Rhode Island 45 - South Carolina 46 - South Dakota 47 - Tennessee 48 - Texas 49 - Utah 50 - Vermont 51 - Virginia 53 - Washington 54 - West Virginia 55 - Wisconsin 56 - Wyoming
entityId	REQUIRED for type 3, 4 and 5;

The table below shows the path for each endpoint to get entityId.

To get entityIds of..	Endpoint
all counties in a state	chas/listCounties/{stateId}
all MCDs in a state	chas/listMCDs/{stateId}
all cities in a state.	chas/listCities/{stateId}

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" -G -d 'type=1&year=2008-2012' https://www.huduser.gov/hudapi/public/chas

API Tester

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

Access Token:

type:

stateId:

year:

Response Structure

property	description
A1	Household Income <= 30% HAMFI (Owner Occupied)
A2	Household Income <= 30% HAMFI (Renter Occupied)
A3,	Household Income <= 30% HAMFI (Total)
A4	Household Income >30% to <=50% HAMFI (Owner Occupied)
A5	Household Income >30% to <=50% HAMFI (Renter Occupied)
A6	Household Income >30% to <=50% HAMFI (Total)
A7	Household Income >50% to <=80% HAMFI (Owner Occupied)
A8	Household Income >50% to <=80% HAMFI (Renter Occupied)
A9	Household Income >50% to <=80% HAMFI (Total)
A10	Household Income >80% to <=100% HAMFI (Owner Occupied)
A11	Household Income >80% to <=100% HAMFI (Renter Occupied)
A12	Household Income >80% to <=100% HAMFI (Total)
A13	Household Income >100% HAMFI (Owner Occupied)
A14	Household Income >100% HAMFI (Renter Occupied)
A15	Household Income >100% HAMFI (Total)
A16	Total Owner Occupied
A17	Total Renter Occupied
A18	Total Occupied housing units
B1	Household has at least 1 of 4 Housing Problems (Owner Occupied)
B2	Household has at least 1 of 4 Housing Problems (Renter Occupied)
B3	Household has at least 1 of 4 Housing Problems (Total)
B4	Household has none of 4 Housing Problems (Owner Occupied)
B5	Household has none of 4 Housing Problems (Renter Occupied)
B6	Household has none of 4 Housing Problems (Total)
B7	Cost burden not available, no other problems (Owner Occupied)
B8	Cost burden not available, no other problems (Renter Occupied)
B9	Cost burden not available, no other problems (Total)
C1	Household has at least 1 of 4 Severe Housing Problems (Owner Occupied)
C2	Household has at least 1 of 4 Severe Housing Problems (Renter Occupied)
C3	Household has at least 1 of 4 Severe Housing Problems (Total)
C4	Household has none of 4 Severe Housing Problems (Owner Occupied)
C5	Household has none of 4 Severe Housing Problems (Renter Occupied)
C6	Household has none of 4 Severe Housing Problems (Total)
D1	Cost Burden <=30% (Owner Occupied)
D2	Cost Burden <=30% (Renter Occupied)
D3	Cost Burden <=30% (Total)
D4	Cost Burden >30% to <=50% (Owner Occupied)
D5	Cost Burden >30% to <=50% (Renter Occupied)
D6	Cost Burden >30% to <=50% (Total)
D7	Cost Burden >50% (Owner Occupied)
D8	Cost Burden >50% (Renter Occupied)
D9	Cost Burden >50% (Total)
D10	Cost Burden not available (Owner Occupied)
D11	Cost Burden not available (Renter Occupied)
D12	Cost Burden not available (Total)
E1	Household Income <= 30% HAMFI (Owners and Renters) and Household has at least 1 of 4 Housing Problems
E2	Household Income <= 30% HAMFI (Owners and Renters) and Household has none of 4 Housing Problems
E3	Household Income <= 30% HAMFI (Owners and Renters) and Cost Burden not available, no other housing problems
E5	Household Income >30% to <=50% HAMFI (Owners and Renters) and Household has at least 1 of 4 Housing Problems
E6	Household Income >30% to <=50% HAMFI (Owners and Renters) and Household has none of 4 Housing Problems
E7	Household Income >30% to <=50% HAMFI (Owners and Renters) and Cost Burden not available, no other housing problems
E9	Household Income >50% to <=80% HAMFI (Owners and Renters) and Household has at least 1 of 4 Housing Problems
E10	Household Income >50% to <=80% HAMFI (Owners and Renters) and Household has none of 4 Housing Problems
E11	Household Income >50% to <=80% HAMFI (Owners and Renters) and Cost Burden not available, no other housing problems
E13	Household Income >80% to <=100% HAMFI (Owners and Renters) and Household has at least 1 of 4 Housing Problems
E14	Household Income >80% to <=100% HAMFI (Owners and Renters) and Household has none of 4 Housing Problems
E15	Household Income >80% to <=100% HAMFI (Owners and Renters) and Cost Burden not available, no other housing problems
E17	Household Income >100% HAMFI (Owners and Renters) and Household has at least 1 of 4 Housing Problems
E18	Household Income >100% HAMFI (Owners and Renters) and Household has none of 4 Housing Problems
E19	Household Income >100% HAMFI (Owners and Renters) and Cost Burden not available, no other housing problems
E21	Total Household has at least 1 of 4 Housing Problems (Owners and Renters)
E22	Total Household has none of 4 Housing Problems (Owners and Renters)
E23	Total Cost Burden not available, no other housing problems (Owners and Renters)
F1	Household Income <= 30% HAMFI (Renters only) and Household has at least 1 of 4 Housing Problems
F2	Household Income <= 30% HAMFI (Renters only) and Household has none of 4 Housing Problems
F3	Household Income <= 30% HAMFI (Renters only) and Cost Burden not available, no other housing problems
F5	Household Income >30% to <=50% HAMFI (Renters only) and Household has at least 1 of 4 Housing Problems
F6	Household Income >30% to <=50% HAMFI (Renters only) and Household has none of 4 Housing Problems
F7	Household Income >30% to <=50% HAMFI (Renters only) and Cost Burden not available, no other housing problems
F9	Household Income >50% to <=80% HAMFI (Renters only) and Household has at least 1 of 4 Housing Problems
F10	Household Income >50% to <=80% HAMFI (Renters only) and Household has none of 4 Housing Problems
F11	Household Income >50% to <=80% HAMFI (Renters only) and Cost Burden not available, no other housing problems
F13	Household Income >80% to <=100% HAMFI (Renters only) and Household has at least 1 of 4 Housing Problems
F14	Household Income >80% to <=100% HAMFI (Renters only) and Household has none of 4 Housing Problems
F15	Household Income >80% to <=100% HAMFI (Renters only) and Cost Burden not available, no other housing problems
F17	Household Income >100% HAMFI (Renters only) and Household has at least 1 of 4 Housing Problems
F18	Household Income >100% HAMFI (Renters only) and Household has none of 4 Housing Problems
F19	Household Income >100% HAMFI (Renters only) and Cost Burden not available, no other housing problems
F21	Total Household has at least 1 of 4 Housing Problems (Renters only)
F22	Total Household has none of 4 Housing Problems (Renters only)
F23	Total Cost Burden not available, no other housing problems (Renters only)
G1	Household Income <= 30% HAMFI (Owners only) and Household has at least 1 of 4 Housing Problems
G2	Household Income <= 30% HAMFI (Owners only) and Household has none of 4 Housing Problems
G3	Household Income <= 30% HAMFI (Owners only) and Cost Burden not available, no other housing problems
G5	Household Income >30% to <=50% HAMFI (Owners only) and Household has at least 1 of 4 Housing Problems
G6	Household Income >30% to <=50% HAMFI (Owners only) and Household has none of 4 Housing Problems
G7	Household Income >30% to <=50% HAMFI (Owners only) and Cost Burden not available, no other housing problems
G9	Household Income >50% to <=80% HAMFI (Owners only) and Household has at least 1 of 4 Housing Problems
G10	Household Income >50% to <=80% HAMFI (Owners only) and Household has none of 4 Housing Problems
G11	Household Income >50% to <=80% HAMFI (Owners only) and Cost Burden not available, no other housing problems
G13	Household Income >80% to <=100% HAMFI (Owners only) and Household has at least 1 of 4 Housing Problems
G14	Household Income >80% to <=100% HAMFI (Owners only) and Household has none of 4 Housing Problems
G15	Household Income >80% to <=100% HAMFI (Owners only) and Cost Burden not available, no other housing problems
G17	Household Income >100% HAMFI (Owners only) and Household has at least 1 of 4 Housing Problems
G18	Household Income >100% HAMFI (Owners only) and Household has none of 4 Housing Problems
G19	Household Income >100% HAMFI (Owners only) and Cost Burden not available, no other housing problems
G21	Total Household has at least 1 of 4 Housing Problems (Owners only)
G22	Total Household has none of 4 Housing Problems (Owners only)
G23	Total Cost Burden not available, no other housing problems (Owners only)
H1	Household Income <= 30% HAMFI (Owners and Renters) and Cost burden > 30%
H2	Household Income <= 30% HAMFI (Owners and Renters) and Cost burden > 50%
H4	Household Income >30% to <=50% HAMFI (Owners and Renters) and Cost burden > 30%
H5	Household Income >30% to <=50% HAMFI (Owners and Renters) and Cost burden > 50%
H7	Household Income >50% to <=80% HAMFI (Owners and Renters) and Cost burden > 30%
H8	Household Income >50% to <=80% HAMFI (Owners and Renters) and Cost burden > 50%
H10	Household Income >80% to <=100% HAMFI (Owners and Renters) and Cost burden > 30%
H11	Household Income >80% to <=100% HAMFI (Owners and Renters) and Cost burden > 50%
H13	Household Income >100% HAMFI (Owners and Renters) and Cost burden > 30%
H14	Household Income >100% HAMFI (Owners and Renters) and Cost burden > 30%
H16	Total (Owners and Renters) and Cost burden > 30%
H17	Total (Owners and Renters) and Cost burden > 50%
I1	Household Income <= 30% HAMFI (Renters only) and Cost burden > 30%
I2	Household Income <= 30% HAMFI (Renters only) and Cost burden > 50%
I4	Household Income >30% to <=50% HAMFI (Renters only) and Cost burden > 30%
I5	Household Income >30% to <=50% HAMFI (Renters only) and Cost burden > 50%
I7	Household Income >50% to <=80% HAMFI (Renters only) and Cost burden > 30%
I8	Household Income >50% to <=80% HAMFI (Renters only) and Cost burden > 50%
I10	Household Income >80% to <=100% HAMFI (Renters only) and Cost burden > 30%
I11	Household Income >80% to <=100% HAMFI (Renters only) and Cost burden > 50%
I13	Household Income >100% HAMFI (Renters only) and Cost burden > 30%
I14	Household Income >100% HAMFI (Renters only) and Cost burden > 30%
I16	Total (Renters only) and Cost burden > 30%
I17	Total (Renters only) and Cost burden > 50%
J1	Household Income <= 30% HAMFI (Owners only) and Cost burden > 30%
J2	Household Income <= 30% HAMFI (Owners only) and Cost burden > 50%
J4	Household Income >30% to <=50% HAMFI (Owners only) and Cost burden > 30%
J5	Household Income >30% to <=50% HAMFI (Owners only) and Cost burden > 50%
J7	Household Income >50% to <=80% HAMFI (Owners only) and Cost burden > 30%
J8	Household Income >50% to <=80% HAMFI (Owners only) and Cost burden > 50%
J10	Household Income >80% to <=100% HAMFI (Owners only) and Cost burden > 30%
J11	Household Income >80% to <=100% HAMFI (Owners only) and Cost burden > 50%
J13	Household Income >100% HAMFI (Owners only) and Cost burden > 30%
J14	Household Income >100% HAMFI (Owners only) and Cost burden > 30%
J16	Total (Owners only) and Cost burden > 30%
J17	Total (Owners only) and Cost burden > 50%

Response Example

API call: https://www.huduser.gov/hudapi/public/chas?type=3&year=2012-2016&stateId=51&entityId=59

    [
    {   "geoname": "Fairfax County, Virginia",
        "sumlevel": "County",
        "year": "2012-2016",
        "A1": "12895",
        "A2": "21805",
        "A3": "34700",
        "A4": "14165",
        "A5": "17535",
        "A6": "31700",
        "A7": "10690",
        "A8": "10350",
        "A9": "21040",
        "A10": "16890",
        "A11": "14325",
        "A12": "31215",
        "A13": "210710",
        "A14": "63990",
        "A15": "274700",
        "A16": "265350",
        "A17": "128005",
        "A18": "393360",
        "B1": "58925",
        "B2": "57735",
        "B3": "116660",
        "B4": "205390",
        "B5": "68400",
        "B6": "273790",
        "B7": "1035",
        "B8": "1875",
        "B9": "2910",
        "C1": "23945",
        "C2": "31650",
        "C3": "55595",
        "C4": "240370",
        "C5": "94480",
        "C6": "334850",
        "D1": "207915",
        "D2": "73630",
        "D3": "281545",
        "D4": "35735",
        "D5": "28910",
        "D6": "64645",
        "D7": "20670",
        "D8": "23405",
        "D9": "44075",
        "D10": "1035",
        "D11": "2060",
        "D12": "3095",
        "E1": "28030",
        "E2": "3760",
        "E3": "2910",
        "E5": "25945",
        "E6": "5755",
        "E7": "0",
        "E9": "14305",
        "E10": "6735",
        "E11": "0",
        "E13": "16085",
        "E14": "15135",
        "E15": "0",
        "E17": "32295",
        "E18": "242405",
        "E19": "0",
        "E21": "116660",
        "E22": "273790",
        "E23": "2910",
        "F1": "17265",
        "F2": "2665",
        "F3": "1875",
        "F5": "15720",
        "F6": "1815",
        "F7": "0",
        "F9": "8165",
        "F10": "2185",
        "F11": "0",
        "F13": "7900",
        "F14": "6430",
        "F15": "0",
        "F17": "8685",
        "F18": "55305",
        "F19": "0",
        "F21": "57735",
        "F22": "68400",
        "F23": "1875",
        "G1": "10765",
        "G2": "1095",
        "G3": "1035",
        "G5": "10225",
        "G6": "3940",
        "G7": "0",
        "G9": "6140",
        "G10": "4550",
        "G11": "0",
        "G13": "8185",
        "G14": "8705",
        "G15": "0",
        "G17": "23610",
        "G18": "187100",
        "G19": "0",
        "H1": "27605",
        "H2": "23420",
        "H4": "24970",
        "H5": "12660",
        "H7": "13465",
        "H8": "3470",
        "H10": "14930",
        "H11": "2060",
        "H13": "27750",
        "H14": "2460",
        "H16": "108720",
        "I1": "16895",
        "I2": "14490",
        "I4": "14970",
        "I5": "7115",
        "I7": "7550",
        "I8": "1180",
        "I10": "7000",
        "I11": "425",
        "I13": "5900",
        "I14": "195",
        "I16": "52315",
        "J1": "10705",
        "J2": "8930",
        "J4": "10005",
        "J5": "5550",
        "J7": "5915",
        "J8": "2290",
        "J10": "7930",
        "J11": "1635",
        "J13": "21850",
        "J14": "2265",
        "J16": "56405"
    }
]