openapi: 3.0.3
info:
  title: HUD User CHAS Housing Counseling 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: Housing Counseling
  description: HUD-approved housing counseling agency search
paths:
  /Housing_Counselor/search:
    get:
      summary: Search Housing Counseling Agencies by Name/Location
      description: Search for HUD-approved housing counseling agencies by agency name, city, and/or state. Returns a list of agencies matching the search criteria with full contact and service information. No API key required.
      operationId: searchHousingCounselors
      tags:
      - Housing Counseling
      parameters:
      - name: AgencyName
        in: query
        required: false
        description: Full or partial agency name to search for
        schema:
          type: string
          example: Community Housing
      - name: City
        in: query
        required: false
        description: City name to filter results
        schema:
          type: string
          example: Washington
      - name: State
        in: query
        required: false
        description: Two-letter state abbreviation to filter results
        schema:
          type: string
          pattern: ^[A-Z]{2}$
          example: DC
      responses:
        '200':
          description: Successful response with matching agencies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HousingCounselingAgency'
              example:
              - nme: UNIVERSITY LEGAL SERVICES
                phone1: 202-527-7070
                statecd: DC
                weburl: https://www.uls-dc.org/
                zipcd: 20019-3402
                agc_ADDR_LATITUDE: '38.894443'
                agc_ADDR_LONGITUDE: '-76.948045'
                languages: ENG
                agcid: '90489'
                adr1: 3939 Benning Rd NE
                city: WASHINGTON
                agc_STATUS: P
                counslg_METHOD: Face to Face Counseling,Group Counseling,Phone Counseling,Video Conference
                services: DFC,FBC,HIC,HMC,NDW,PPC,PPW,RHC
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /Housing_Counselor/searchByLocation:
    get:
      summary: Search Housing Counseling Agencies by Location
      description: Search for HUD-approved housing counseling agencies near a specified geographic location (latitude/longitude) within a given distance radius. Returns agencies sorted by proximity to the search coordinates.
      operationId: searchHousingCounselorsByLocation
      tags:
      - Housing Counseling
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude of the search center point (decimal degrees)
        schema:
          type: number
          format: double
          minimum: -90
          maximum: 90
          example: 38.9
      - name: long
        in: query
        required: true
        description: Longitude of the search center point (decimal degrees)
        schema:
          type: number
          format: double
          minimum: -180
          maximum: 180
          example: -77.0
      - name: distance
        in: query
        required: false
        description: Search radius in miles (default is typically 5 miles)
        schema:
          type: number
          default: 5
          example: 10
      responses:
        '200':
          description: Successful response with nearby agencies sorted by distance
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HousingCounselingAgency'
        '400':
          description: Bad request - missing or invalid coordinates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Bad request - invalid parameters provided
    HousingCounselingAgency:
      type: object
      description: HUD-approved housing counseling agency
      properties:
        nme:
          type: string
          description: Agency name
          example: UNIVERSITY LEGAL SERVICES
        agcid:
          type: string
          description: HUD agency identifier
          example: '90489'
        parentid:
          type: string
          nullable: true
          description: Parent organization agency ID if applicable
          example: '80219'
        adr1:
          type: string
          description: Primary address line
          example: 3939 Benning Rd NE
        adr2:
          type: string
          nullable: true
          description: Secondary address line
        city:
          type: string
          description: City
          example: WASHINGTON
        statecd:
          type: string
          description: Two-letter state code
          example: DC
        zipcd:
          type: string
          description: ZIP code
          example: 20019-3402
        county_NME:
          type: string
          description: County name
        state_NME:
          type: string
          description: Full state name
          example: District of Columbia
        state_FIPS_CODE:
          type: string
          nullable: true
          description: State FIPS code
        mailingadr1:
          type: string
          description: Mailing address line 1
        mailingadr2:
          type: string
          nullable: true
          description: Mailing address line 2
        mailingcity:
          type: string
          description: Mailing city
        mailingstatecd:
          type: string
          description: Mailing state code
        mailingzipcd:
          type: string
          description: Mailing ZIP code
        phone1:
          type: string
          description: Primary phone number
          example: 202-527-7070
        phone2:
          type: string
          nullable: true
          description: Secondary phone number
        fax:
          type: string
          nullable: true
          description: Fax number
        email:
          type: string
          description: Agency email address
          example: info@agency.org
        weburl:
          type: string
          description: Agency website URL
          example: https://www.uls-dc.org/
        agc_ADDR_LATITUDE:
          type: string
          description: Geographic latitude of agency address
          example: '38.894443'
        agc_ADDR_LONGITUDE:
          type: string
          description: Geographic longitude of agency address
          example: '-76.948045'
        agc_STATUS:
          type: string
          description: Agency status (A = Active, P = Probationary, S = Suspended)
          enum:
          - A
          - P
          - S
          example: A
        agc_SRC_CD:
          type: string
          description: Agency source code
          example: HUD
        languages:
          type: string
          description: 'Comma-separated language codes supported by the agency. Common codes: ENG (English), SPA (Spanish), CHI (Chinese), FRE (French), FAR (Farsi), POR (Portuguese), OTH (Other).'
          example: ENG,SPA
        faithbased:
          type: string
          description: Whether agency is faith-based (Y/N)
          enum:
          - Y
          - N
          example: N
        colonias_IND:
          type: string
          description: Whether agency serves colonias communities (Y/N)
          enum:
          - Y
          - N
          example: N
        migrantwkrs_IND:
          type: string
          description: Whether agency serves migrant workers (Y/N)
          enum:
          - Y
          - N
          example: N
        counslg_METHOD:
          type: string
          description: 'Comma-separated list of counseling methods offered. Options include: Face to Face Counseling, Group Counseling, Phone Counseling, Internet Counseling, Video Conference, Other Counseling.'
          example: Face to Face Counseling,Phone Counseling,Video Conference
        services:
          type: string
          nullable: true
          description: 'Comma-separated service codes offered by the agency. Common codes: DFC (Default/Foreclosure Counseling), FBC (Fair Housing/Buying Counseling), HIC (Home Improvement Counseling), HMC (Home Maintenance Counseling), NDW (Non-Delinquency Post-Purchase Counseling Workshop), PPC (Pre-Purchase Counseling), PPW (Pre-Purchase Homebuyer Education Workshop), RHC (Rental Housing Counseling), PLW (Predatory Lending Workshop), FHW (Fair Housing Pre-Purchase Education Workshop), FBW (Financial Management/Budget Counseling Workshop).'
          example: DFC,FBC,HIC,HMC,PPC,PPW,RHC
  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