{
  "openapi": "3.1.0",
  "info": {
    "title": "Flood Zone API",
    "version": "1.0.0",
    "description": "FEMA flood zone, SFHA flag, static base flood elevation and FIRM panel for a US address or point, from the National Flood Hazard Layer. Informational: not a Standard Flood Hazard Determination.",
    "contact": {
      "email": "support@floodzoneapi.com",
      "url": "https://floodzoneapi.com/docs/"
    },
    "termsOfService": "https://floodzoneapi.com/terms.html"
  },
  "servers": [
    {
      "url": "https://api.floodzoneapi.com/api/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key starting fza_, from your account page."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_key",
              "invalid_request",
              "address_not_found",
              "quota_exceeded",
              "rate_limited",
              "upstream_unavailable",
              "internal_error"
            ]
          },
          "message": {
            "type": "string"
          },
          "field": {
            "type": "string",
            "enum": [
              "address",
              "lat",
              "lon"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "no_match",
              "not_address_level"
            ]
          },
          "upstream": {
            "type": "string",
            "enum": [
              "fema_nfhl",
              "geocoder"
            ]
          },
          "retry_after": {
            "type": "integer"
          }
        }
      },
      "FloodZone": {
        "type": "object",
        "required": [
          "query",
          "location",
          "flood_zone",
          "firm_panel",
          "source",
          "notice"
        ],
        "properties": {
          "query": {
            "type": "object"
          },
          "location": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lon": {
                "type": "number"
              },
              "geocoder": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "census",
                  "openstreetmap",
                  null
                ]
              },
              "precision": {
                "type": "string",
                "enum": [
                  "address_range",
                  "address_point",
                  "input_coordinates"
                ]
              },
              "matched_address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "candidates": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "county": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "county_fips": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "flood_zone": {
            "type": "object",
            "properties": {
              "mapped": {
                "type": "boolean"
              },
              "zone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "subtype": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sfha": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "static_bfe": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "elevation": {
                    "type": "number"
                  },
                  "unit": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "datum": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "depth": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "value": {
                    "type": "number"
                  },
                  "unit": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "dfirm_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "polygon_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "at_zone_boundary": {
                "type": "boolean"
              },
              "other_zones": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "zone": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "subtype": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "sfha": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "firm_panel": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "panel": {
                "type": "string"
              },
              "effective_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              },
              "panel_type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "dfirm_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "other_panels": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "panel": {
                      "type": "string"
                    },
                    "effective_date": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date"
                    },
                    "panel_type": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "dfirm_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "source": {
            "type": "object",
            "properties": {
              "dataset": {
                "type": "string"
              },
              "service": {
                "type": "string"
              },
              "layers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                }
              },
              "query_point": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lon": {
                    "type": "number"
                  }
                }
              },
              "queried_at": {
                "type": "string",
                "format": "date-time"
              },
              "cached": {
                "type": "boolean"
              },
              "cache_ttl_seconds": {
                "type": "integer"
              }
            }
          },
          "notice": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/flood/zone": {
      "get": {
        "operationId": "getFloodZone",
        "summary": "FEMA flood zone at an address or point",
        "description": "Send exactly one of address, or lat with lon.",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 5,
              "maxLength": 300
            },
            "description": "US street address with a house number."
          },
          {
            "name": "lat",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lon",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The zone at the point (including unmapped points).",
            "headers": {
              "X-Quota-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Calls included this calendar month (UTC)."
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Calls left this month."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FloodZone"
                },
                "example": {
                  "query": {
                    "address": "1700 Convention Center Dr, Miami Beach, FL 33139"
                  },
                  "location": {
                    "lat": 25.792247,
                    "lon": -80.134934,
                    "geocoder": "census",
                    "precision": "address_range",
                    "matched_address": "1700 CONVENTION CENTER DR, MIAMI BEACH, FL, 33139",
                    "candidates": 1,
                    "county": "Miami-Dade County",
                    "county_fips": "12086",
                    "state": "FL"
                  },
                  "flood_zone": {
                    "mapped": true,
                    "zone": "AE",
                    "subtype": null,
                    "description": "1% annual chance flood hazard. Base flood elevations determined.",
                    "sfha": true,
                    "static_bfe": {
                      "elevation": 8.0,
                      "unit": "Feet",
                      "datum": "NGVD29"
                    },
                    "depth": null,
                    "dfirm_id": "12086C",
                    "polygon_id": "12086C_1179",
                    "at_zone_boundary": false,
                    "other_zones": []
                  },
                  "firm_panel": {
                    "panel": "12086C0317L",
                    "effective_date": "2009-09-11",
                    "panel_type": "Countywide, Panel Printed",
                    "dfirm_id": "12086C",
                    "other_panels": []
                  },
                  "source": {
                    "dataset": "FEMA National Flood Hazard Layer (NFHL)",
                    "service": "https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer",
                    "layers": [
                      {
                        "id": 28,
                        "name": "Flood Hazard Zones"
                      },
                      {
                        "id": 3,
                        "name": "FIRM Panels"
                      }
                    ],
                    "query_point": {
                      "lat": 25.79225,
                      "lon": -80.13493
                    },
                    "queried_at": "2026-09-29T08:36:12Z",
                    "cached": true,
                    "cache_ttl_seconds": 86400
                  },
                  "notice": "Informational. This is the zone shown on FEMA's effective flood map (NFHL) at this point. It is not a Standard Flood Hazard Determination (FEMA Form 086-0-32), a prediction of flood risk, or an insurance quote, and it does not reflect a Letter of Map Amendment issued for a single structure."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Address not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid request (refunded).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exceeded or rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "FEMA or the geocoder is unavailable (refunded).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}