Skip to main content

CONSOLIDATED PLANNING/CHAS Dataset API Documentation

HUD.GOV HUDUser.gov
Dataset Banner Image

CONSOLIDATED PLANNING/CHAS Dataset API Documentation

    Dataset/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:

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









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