openapi: 3.0.3
info:
  title: OpenFEMA 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: Disaster Declarations
    description: Federally declared disasters.
  - name: Public Assistance
    description: FEMA Public Assistance (PA) grant program data.
  - name: Hazard Mitigation
    description: Hazard Mitigation Assistance (HMA) grant program data.
  - name: NFIP
    description: National Flood Insurance Program redacted policy and claims data.
  - name: IPAWS
    description: Integrated Public Alert and Warning System archived alerts.
  - name: Web Disaster Summaries
    description: Per-disaster financial summary totals from NEMIS.
  - name: Catalog
    description: Self-describing metadata - dataset list and data dictionaries.
paths:
  /v2/DisasterDeclarationsSummaries:
    get:
      operationId: listDisasterDeclarationsSummaries
      tags:
        - Disaster Declarations
      summary: List disaster declarations summaries
      description: >-
        Returns summarized records for every official FEMA disaster
        declaration since 1953 - major disaster, emergency, and fire
        management assistance declarations.
      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 disaster declarations summary records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      DisasterDeclarationsSummaries:
                        type: array
                        items:
                          $ref: '#/components/schemas/DisasterDeclarationsSummary'
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadFilter'
  /v1/PublicAssistanceFundedProjectsDetails:
    get:
      operationId: listPublicAssistanceFundedProjectsDetails
      tags:
        - Public Assistance
      summary: List Public Assistance funded projects details
      description: >-
        Returns obligated Public Assistance grant projects (project
        worksheets), joinable to Public Assistance Applicants via
        applicantId.
      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 Public Assistance funded project detail records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      PublicAssistanceFundedProjectsDetails:
                        type: array
                        items:
                          $ref: '#/components/schemas/PublicAssistanceFundedProjectDetail'
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadFilter'
  /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'
  /v2/FimaNfipPolicies:
    get:
      operationId: listFimaNfipPolicies
      tags:
        - NFIP
      summary: List NFIP redacted policies
      description: >-
        Returns policy-level NFIP transactions redacted to protect
        policyholder personally identifiable information.
      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 redacted NFIP policy records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      FimaNfipPolicies:
                        type: array
                        items:
                          $ref: '#/components/schemas/FimaNfipPolicy'
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadFilter'
  /v2/FimaNfipClaims:
    get:
      operationId: listFimaNfipClaims
      tags:
        - NFIP
      summary: List NFIP redacted claims
      description: >-
        Returns NFIP claims transactions redacted to protect policyholder
        personally identifiable information.
      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 redacted NFIP claim records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      FimaNfipClaims:
                        type: array
                        items:
                          $ref: '#/components/schemas/FimaNfipClaim'
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadFilter'
  /v1/IpawsArchivedAlerts:
    get:
      operationId: listIpawsArchivedAlerts
      tags:
        - IPAWS
      summary: List IPAWS archived alerts
      description: >-
        Returns archived Common Alerting Protocol (CAP) messages issued
        through the Integrated Public Alert and Warning System. The payload
        is hierarchical/nested, unlike most other OpenFEMA datasets.
      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 IPAWS archived alert records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      IpawsArchivedAlerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/IpawsArchivedAlert'
        '400':
          $ref: '#/components/responses/BadFilter'
  /v1/FemaWebDisasterSummaries:
    get:
      operationId: listFemaWebDisasterSummaries
      tags:
        - Web Disaster Summaries
      summary: List FEMA web disaster summaries
      description: >-
        Returns per-disaster financial summary totals (Individual Assistance,
        Public Assistance, and Hazard Mitigation) sourced raw from NEMIS.
      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 FEMA web disaster summary records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      FemaWebDisasterSummaries:
                        type: array
                        items:
                          $ref: '#/components/schemas/FemaWebDisasterSummary'
            text/csv:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadFilter'
  /v1/OpenFemaDataSets:
    get:
      operationId: listOpenFemaDataSets
      tags:
        - Catalog
      summary: List the OpenFEMA dataset catalog
      description: >-
        Returns metadata describing every dataset and version published on
        OpenFEMA - name, version, description, last-refresh date, record
        count, and whether an API endpoint exists for it.
      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'
      responses:
        '200':
          description: A page of dataset catalog records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      OpenFemaDataSets:
                        type: array
                        items:
                          $ref: '#/components/schemas/OpenFemaDataSet'
        '400':
          $ref: '#/components/responses/BadFilter'
  /v1/OpenFemaDataSetFields:
    get:
      operationId: listOpenFemaDataSetFields
      tags:
        - Catalog
      summary: List the data dictionary for a dataset/version
      description: >-
        Returns the field-level data dictionary (name, title, type,
        description) for a given dataset name and version. Typically called
        with a $filter such as
        `openFemaDataSet eq 'DisasterDeclarationsSummaries' and datasetVersion eq 2`.
      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'
      responses:
        '200':
          description: A page of data dictionary field records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OpenFemaEnvelope'
                  - type: object
                    properties:
                      OpenFemaDataSetFields:
                        type: array
                        items:
                          $ref: '#/components/schemas/OpenFemaDataSetField'
        '400':
          $ref: '#/components/responses/BadFilter'
components:
  parameters:
    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
    Select:
      name: $select
      in: query
      description: Comma-separated list of fields to include in the response.
      schema:
        type: string
    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
    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
    OrderBy:
      name: $orderby
      in: query
      description: Field name to sort results by.
      schema:
        type: string
    Format:
      name: $format
      in: query
      description: Response format. Defaults to json when omitted.
      schema:
        type: string
        enum: [json, csv, parquet, jsona, xlsx]
        default: json
    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
    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
    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
  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
    DisasterDeclarationsSummary:
      type: object
      description: One federally declared disaster summary record.
      properties:
        femaDeclarationString:
          type: string
        disasterNumber:
          type: integer
          description: Sequentially assigned number designating an event or incident declared as a disaster.
        state:
          type: string
          description: U.S. state, district, or territory name/abbreviation.
        declarationType:
          type: string
          description: Two-character code - major disaster (DR), fire management (FM), or emergency (EM).
        declarationDate:
          type: string
          format: date-time
        fyDeclared:
          type: integer
        incidentType:
          type: string
          description: Type of incident, e.g. Flood, Hurricane, Fire; affects available assistance types.
        declarationTitle:
          type: string
        incidentBeginDate:
          type: string
          format: date-time
        incidentEndDate:
          type: string
          format: date-time
        fipsStateCode:
          type: string
        fipsCountyCode:
          type: string
        designatedArea:
          type: string
        ihProgramDeclared:
          type: boolean
        iaProgramDeclared:
          type: boolean
        paProgramDeclared:
          type: boolean
        hmProgramDeclared:
          type: boolean
        hash:
          type: string
        lastRefresh:
          type: string
          format: date-time
        id:
          type: string
    PublicAssistanceFundedProjectDetail:
      type: object
      description: One obligated Public Assistance project worksheet.
      properties:
        disasterNumber:
          type: integer
        applicantId:
          type: string
          description: Joins to the Public Assistance Applicants dataset.
        pwNumber:
          type: string
        projectSize:
          type: string
        damageCategoryCode:
          type: string
          description: Category of damage (e.g. A-Debris Removal, G-Parks).
        projectAmount:
          type: number
          format: double
        federalShareObligated:
          type: number
          format: double
        totalObligated:
          type: number
          format: double
        dcc:
          type: string
        applicantName:
          type: string
        county:
          type: string
        state:
          type: string
        obligatedDate:
          type: string
          format: date-time
        hash:
          type: string
        lastRefresh:
          type: string
          format: date-time
        id:
          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
    FimaNfipPolicy:
      type: object
      description: One redacted NFIP policy transaction. The live dataset carries 81 fields; representative fields shown.
      properties:
        id:
          type: string
        policyEffectiveDate:
          type: string
          format: date
        policyTerminationDate:
          type: string
          format: date
        totalBuildingInsuranceCoverage:
          type: number
          format: double
        totalContentsInsuranceCoverage:
          type: number
          format: double
        totalInsurancePremiumOfThePolicy:
          type: number
          format: double
        propertyState:
          type: string
        countyCode:
          type: string
        censusTract:
          type: string
        floodZone:
          type: string
        occupancyType:
          type: integer
        constructionDate:
          type: string
          format: date
        ratedFloodZone:
          type: string
        hash:
          type: string
        lastRefresh:
          type: string
          format: date-time
    FimaNfipClaim:
      type: object
      description: One redacted NFIP claim transaction. The live dataset carries 73 fields; representative fields shown.
      properties:
        id:
          type: string
        dateOfLoss:
          type: string
          format: date
        state:
          type: string
        countyCode:
          type: string
        causeOfDamage:
          type: string
        floodZone:
          type: string
        amountPaidOnBuildingClaim:
          type: number
          format: double
        amountPaidOnContentsClaim:
          type: number
          format: double
        netTotalPayments:
          type: number
          format: double
        lowestFloorElevation:
          type: number
          format: double
        occupancyType:
          type: integer
        yearOfLoss:
          type: integer
        hash:
          type: string
        lastRefresh:
          type: string
          format: date-time
    IpawsArchivedAlert:
      type: object
      description: >-
        One archived Common Alerting Protocol message. Nested/hierarchical -
        an alert contains one or more info blocks, each with one or more
        resource/area blocks.
      properties:
        id:
          type: string
        identifier:
          type: string
        sender:
          type: string
        sent:
          type: string
          format: date-time
        status:
          type: string
        msgType:
          type: string
        scope:
          type: string
        searchGeometry:
          type: string
        infos:
          type: array
          items:
            type: object
            properties:
              language:
                type: string
              category:
                type: string
              event:
                type: string
              urgency:
                type: string
              severity:
                type: string
              certainty:
                type: string
              headline:
                type: string
              description:
                type: string
              area:
                type: array
                items:
                  type: object
                  properties:
                    areaDesc:
                      type: string
                    polygon:
                      type: string
        originalMessage:
          type: string
        lastRefresh:
          type: string
          format: date-time
    FemaWebDisasterSummary:
      type: object
      description: One per-disaster raw financial summary sourced from NEMIS.
      properties:
        disasterNumber:
          type: integer
        totalNumberIaApproved:
          type: integer
        totalAmountIhpApproved:
          type: number
          format: double
        totalObligatedAmountPa:
          type: number
          format: double
        totalObligatedAmountHmgp:
          type: number
          format: double
        paProgramDeclared:
          type: boolean
        iaProgramDeclared:
          type: boolean
        hmProgramDeclared:
          type: boolean
        disasterCloseoutDate:
          type: string
          format: date-time
        hash:
          type: string
        lastRefresh:
          type: string
          format: date-time
    OpenFemaDataSet:
      type: object
      description: One catalog entry describing a dataset and version.
      properties:
        name:
          type: string
        title:
          type: string
        version:
          type: integer
        description:
          type: string
        webService:
          type: string
          description: API endpoint path, when the dataset is exposed via the API.
        lastDataSetRefresh:
          type: string
          format: date-time
        recordCount:
          type: integer
        dataDictionary:
          type: string
    OpenFemaDataSetField:
      type: object
      description: One data-dictionary field entry for a dataset/version.
      properties:
        openFemaDataSet:
          type: string
        datasetVersion:
          type: integer
        name:
          type: string
        title:
          type: string
        type:
          type: string
        description:
          type: string