openapi: 3.0.3
info:
  title: HUD User Fair Market Rents API
  description: >-
    Provides Fair Market Rent (FMR) data by state, county, and metropolitan
    area. Returns efficiency through four-bedroom rental rates used as the
    basis for Section 8 Housing Choice Voucher payment standards. 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
externalDocs:
  description: HUD User Fair Market Rents API Documentation
  url: https://www.huduser.gov/portal/dataset/fmr-api.html
security:
  - bearerAuth: []
tags:
  - name: Fair Market Rents
    description: Fair Market Rent data by geography
paths:
  /fmr/statedata/{state}:
    get:
      summary: Get Fair Market Rents by State
      description: >-
        Returns Fair Market Rent data for all counties and metropolitan
        areas within the specified state. FMRs cover efficiency through
        four-bedroom unit sizes.
      operationId: getFMRByState
      tags:
        - Fair Market Rents
      parameters:
        - name: state
          in: path
          required: true
          description: Two-letter state abbreviation (e.g., AL, CA, TX)
          schema:
            type: string
            pattern: '^[A-Z]{2}$'
            example: DC
        - name: year
          in: query
          required: false
          description: Fiscal year for FMR data (e.g., 2024). Defaults to the most recent year.
          schema:
            type: integer
            example: 2024
      responses:
        '200':
          description: Successful response with FMR data for the state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FMRStateResponse'
        '401':
          description: Unauthorized - missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: State not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /fmr/data/{entityid}:
    get:
      summary: Get Fair Market Rents by Entity
      description: >-
        Returns Fair Market Rent data for a specific geographic entity
        identified by its HUD entity ID (county FIPS code or CBSA code).
      operationId: getFMRByEntity
      tags:
        - Fair Market Rents
      parameters:
        - name: entityid
          in: path
          required: true
          description: >-
            HUD geographic entity identifier. For counties, use the
            5-digit FIPS code. For metropolitan areas, use the CBSA code.
          schema:
            type: string
            example: '1100199999'
        - name: year
          in: query
          required: false
          description: Fiscal year for FMR data
          schema:
            type: integer
            example: 2024
      responses:
        '200':
          description: Successful response with FMR data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FMREntityResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token obtained by registering at
        https://www.huduser.gov/hudapi/public/register
  schemas:
    FMRUnit:
      type: object
      description: Fair Market Rent values by unit size
      properties:
        Efficiency:
          type: number
          description: Fair Market Rent for an efficiency (studio) unit in USD
          example: 1200
        One-Bedroom:
          type: number
          description: Fair Market Rent for a one-bedroom unit in USD
          example: 1450
        Two-Bedroom:
          type: number
          description: Fair Market Rent for a two-bedroom unit in USD
          example: 1700
        Three-Bedroom:
          type: number
          description: Fair Market Rent for a three-bedroom unit in USD
          example: 2200
        Four-Bedroom:
          type: number
          description: Fair Market Rent for a four-bedroom unit in USD
          example: 2600
    FMRArea:
      type: object
      description: FMR data for a geographic area
      properties:
        area_name:
          type: string
          description: Name of the geographic area
          example: 'Washington-Arlington-Alexandria, DC-VA-MD HUD Metro FMR Area'
        area_code:
          type: string
          description: HUD area code
          example: 'METRO47900M47900'
        county_name:
          type: string
          description: County name if applicable
          example: 'District of Columbia'
        counties_msa:
          type: string
          description: Counties within the MSA
        year:
          type: string
          description: Fiscal year for the FMR data
          example: '2024'
        fmr_type:
          type: integer
          description: FMR type (40 for 40th percentile, 50 for 50th percentile)
          example: 40
        smallarea_status:
          type: string
          description: Indicates if small area FMRs are applicable
          enum: ['0', '1']
        basicdata:
          $ref: '#/components/schemas/FMRUnit'
    FMRStateResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            metroareas:
              type: array
              items:
                $ref: '#/components/schemas/FMRArea'
            counties:
              type: array
              items:
                $ref: '#/components/schemas/FMRArea'
    FMREntityResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FMRArea'
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: 'Unauthorized access. Please provide a valid bearer token.'