openapi: 3.0.3
info:
  title: OpenFEMA Catalog Hazard Mitigation API
  description: OpenFEMA is FEMA's open data platform. It exposes a read-only RESTful API over individually versioned dataset endpoints (Entities) using OData-style query string parameters. No API key, subscription, or authentication is required. Responses default to JSON; CSV and Parquet are also available via $format. This document models the confirmed public dataset endpoints covering disaster declarations, public assistance, hazard mitigation, NFIP, IPAWS alerts, web disaster summaries, and the self-describing dataset/field catalog. Field lists shown here are representative, not exhaustive - the full data dictionary for any dataset/version is available live from the OpenFemaDataSetFields endpoint modeled below.
  termsOfService: https://www.fema.gov/about/website-information/privacy-policy
  contact:
    name: OpenFEMA
    email: OpenFEMA@fema.dhs.gov
    url: https://www.fema.gov/about/openfema
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usa.gov/government-works
  version: '2.1'
servers:
- url: https://www.fema.gov/api/open
  description: OpenFEMA production API (dataset version is part of each path)
tags:
- name: Hazard Mitigation
  description: Hazard Mitigation Assistance (HMA) grant program data.
paths:
  /v3/HazardMitigationAssistanceProjects:
    get:
      operationId: listHazardMitigationAssistanceProjects
      tags:
      - Hazard Mitigation
      summary: List Hazard Mitigation Assistance projects
      description: Returns funded projects under the HMGP, FMA, and (historically) PDM hazard mitigation grant programs.
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/Metadata'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/AllRecords'
      responses:
        '200':
          description: A page of Hazard Mitigation Assistance project records.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OpenFemaEnvelope'
                - type: object
                  properties:
                    HazardMitigationAssistanceProjects:
                      type: array
                      items:
                        $ref: '#/components/schemas/HazardMitigationAssistanceProject'
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadFilter'
components:
  parameters:
    Top:
      name: $top
      in: query
      description: Number of records to return. Defaults to 1000 when omitted; maximum of 10000 per call.
      schema:
        type: integer
        default: 1000
        maximum: 10000
        minimum: 1
    Count:
      name: $count
      in: query
      description: When true, includes the total matching record count in the metadata envelope. Replacement for the deprecated $inlinecount parameter.
      schema:
        type: boolean
        default: false
    Format:
      name: $format
      in: query
      description: Response format. Defaults to json when omitted.
      schema:
        type: string
        enum:
        - json
        - csv
        - parquet
        - jsona
        - xlsx
        default: json
    Filter:
      name: $filter
      in: query
      description: OData-style filter expression, e.g. state eq 'FL' and fyDeclared eq 2024. The parser is strict about spacing, quoting, and capitalization; string literals must be single-quoted.
      schema:
        type: string
    Metadata:
      name: $metadata
      in: query
      description: When false, suppresses the metadata envelope object and returns only the data array. Accepts true/false (the legacy on/off values are deprecated).
      schema:
        type: boolean
        default: true
    OrderBy:
      name: $orderby
      in: query
      description: Field name to sort results by.
      schema:
        type: string
    Select:
      name: $select
      in: query
      description: Comma-separated list of fields to include in the response.
      schema:
        type: string
    AllRecords:
      name: $allrecords
      in: query
      description: BETA. When true, forces the full result set to be returned in one download, overriding the 10000-record $top ceiling. Intended for bulk export, not interactive paging.
      schema:
        type: boolean
        default: false
    Skip:
      name: $skip
      in: query
      description: Number of records to skip, used to page through results beyond $top.
      schema:
        type: integer
        default: 0
        minimum: 0
  responses:
    BadFilter:
      description: Malformed OData query string (commonly a $filter with incorrect quoting, spacing, or an unknown field name).
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    OpenFemaEnvelope:
      type: object
      description: Every OpenFEMA response wraps the requested dataset array in a metadata object (unless $metadata=false is passed).
      properties:
        metadata:
          type: object
          properties:
            skip:
              type: integer
            filter:
              type: string
            orderby:
              type: string
            select:
              type: string
            rundate:
              type: string
              format: date-time
            count:
              type: integer
              description: Total matching records, present only when $count=true.
            entityname:
              type: string
            version:
              type: integer
            url:
              type: string
    HazardMitigationAssistanceProject:
      type: object
      description: One funded Hazard Mitigation Assistance project.
      properties:
        id:
          type: string
        disasterNumber:
          type: integer
        state:
          type: string
        programArea:
          type: string
          description: HMGP, FMA, or PDM.
        projectType:
          type: string
        status:
          type: string
        projectTitle:
          type: string
        projectAmount:
          type: number
          format: double
        federalShareObligated:
          type: number
          format: double
        costSharePercentage:
          type: number
          format: double
        dateApproved:
          type: string
          format: date-time
        hash:
          type: string
        lastRefresh:
          type: string
          format: date-time