HUD - US Department of Housing and Urban Development CHAS API

openapi: 3.0.3
info:
  title: HUD User CHAS API
  description: Comprehensive Housing Affordability Strategy (CHAS) data provides custom tabulations of American Community Survey (ACS) data on housing needs at national, state, county, place, and census tract levels. CHAS data is used for Consolidated Planning submissions required to receive HUD formula grant funds. Requires a free bearer token obtained from the HUD User portal.
  version: 1.0.0
  contact:
    name: HUD User Support
    url: https://www.huduser.gov/portal/contact.html
  license:
    name: Public Domain
    url: https://www.huduser.gov/portal/dataset/api-terms-of-service.html
servers:
- url: https://www.huduser.gov/hudapi/public
  description: HUD User Public API
security:
- bearerAuth: []
tags:
- name: CHAS
  description: Comprehensive Housing Affordability Strategy data
paths:
  /chas:
    get:
      summary: Get CHAS Data by Geography
      description: Returns CHAS housing needs data for a specified geography at a given geographic level. Supports national, state, county, place, MCD (Minor Civil Division), and census tract geographies. Data includes household housing problems by income level and tenure (owner vs. renter).
      operationId: getCHASData
      tags:
      - CHAS
      parameters:
      - name: type
        in: query
        required: true
        description: 'Geographic level type: 1 = National, 2 = State, 3 = County, 4 = Place (incorporated city/town), 5 = Minor Civil Division (MCD), 6 = Census Tract'
        schema:
          type: integer
          minimum: 1
          maximum: 6
          example: 3
      - name: stateId
        in: query
        required: false
        description: 2-digit state FIPS code. Required for type 3 (county), type 4 (place), type 5 (MCD), and type 6 (census tract).
        schema:
          type: string
          pattern: ^\d{2}$
          example: '11'
      - name: entityId
        in: query
        required: false
        description: Geographic entity identifier. For counties, use the 3-digit county FIPS code. For places, use the 5-digit FIPS place code. For census tracts, use the 11-digit FIPS tract code.
        schema:
          type: string
          example: '001'
      - name: year
        in: query
        required: false
        description: Data year. CHAS data is published periodically as ACS 5-year estimates become available.
        schema:
          type: integer
          example: 2019
      responses:
        '200':
          description: Successful response with CHAS data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CHASResponse'
        '401':
          description: Unauthorized - missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No CHAS data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Unauthorized access. Please provide a valid bearer token.
    CHASRecord:
      type: object
      description: CHAS housing needs data record
      properties:
        geoname:
          type: string
          description: Geographic area name
          example: District of Columbia
        sumlevel:
          type: string
          description: Summary level code for the geography
          example: '040'
        year:
          type: string
          description: ACS 5-year estimate period (e.g., 2015-2019)
          example: 2015-2019
        A1:
          type: integer
          description: Total households
        A2:
          type: integer
          description: Owner-occupied households
        A3:
          type: integer
          description: Renter-occupied households
        T1_est:
          type: integer
          description: Total households with housing problems estimate
        T1_moe:
          type: number
          description: Total households with housing problems margin of error
        T2_est:
          type: integer
          description: Extremely Low Income (<=30% AMI) households with housing problems
        T2_moe:
          type: number
          description: ELI households with housing problems margin of error
        T3_est:
          type: integer
          description: Very Low Income (30-50% AMI) households with housing problems
        T3_moe:
          type: number
          description: VLI households with housing problems margin of error
        T4_est:
          type: integer
          description: Low Income (50-80% AMI) households with housing problems
        T4_moe:
          type: number
          description: LI households with housing problems margin of error
    CHASResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CHASRecord'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained by registering at https://www.huduser.gov/hudapi/public/register
externalDocs:
  description: HUD User CHAS API Documentation
  url: https://www.huduser.gov/portal/dataset/chas-api.html