{
  "openapi": "3.0.2",
  "info": {
    "title": "Property Flood Zone Lookup",
    "version": "1.0.0",
    "description": "Look up the effective FEMA National Flood Hazard Layer (NFHL) flood zone and matching FIRM panel at a U.S. street address or latitude/longitude. This independent service is not affiliated with or endorsed by FEMA. Results are informational and are not Standard Flood Hazard Determinations or insurance decisions. An unmapped result does not mean low risk. Address geocodes may be interpolated."
  },
  "servers": [{ "url": "https://flood.foreclosureapi.com" }],
  "tags": [{ "name": "Flood zone", "description": "Point-level FEMA flood map context" }],
  "paths": {
    "/v1/flood-zone": {
      "get": {
        "tags": ["Flood zone"],
        "operationId": "getFloodZone",
        "summary": "Get FEMA flood zone by address or point",
        "description": "Provide either `address` or both `lat` and `lon`. One result is returned for the matched point. If no zone polygon appears, the NFHL Availability layer distinguishes `unmapped` from `unknown` where possible. Neither means low risk. If overlapping polygons conflict, status is `ambiguous` and no single zone is selected.",
        "security": [{ "RapidApiKey": [] }],
        "parameters": [
          { "name": "address", "in": "query", "description": "U.S. street address. Use with city/state or ZIP. Do not combine with lat/lon.", "required": false, "schema": { "type": "string", "minLength": 5, "maxLength": 220 }, "example": "1600 Pennsylvania Ave NW, Washington, DC 20500" },
          { "name": "lat", "in": "query", "description": "Latitude in decimal degrees. Requires lon; do not combine with address.", "required": false, "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 38.8987 },
          { "name": "lon", "in": "query", "description": "Longitude in decimal degrees. Requires lat; do not combine with address.", "required": false, "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -77.0352 }
        ],
        "responses": {
          "200": {
            "description": "Mapped, unmapped, unknown, or ambiguous FEMA point lookup. The `result.status` field identifies which.",
            "content": { "application/json": {
              "schema": { "$ref": "#/components/schemas/FloodZoneResponse" },
              "example": {
                "location": { "latitude": 38.8987, "longitude": -77.0352, "coordinateSource": "caller" },
                "result": { "status": "mapped", "floodZone": "X", "zoneSubtype": "AREA OF MINIMAL FLOOD HAZARD", "specialFloodHazardArea": false, "staticBaseFloodElevation": null, "elevationUnit": null, "mapPanel": { "number": "1100010018C", "effectiveDate": "2010-09-27", "printed": true } },
                "source": { "name": "FEMA National Flood Hazard Layer", "availabilityUrl": "https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer/0", "floodZonesUrl": "https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer/28", "firmPanelsUrl": "https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer/3", "mapServiceCenterUrl": "https://msc.fema.gov/portal/search", "capturedAt": "2026-11-08T00:00:00.000Z" },
                "notices": ["Map context is informational, not a Standard Flood Hazard Determination or insurance decision."],
                "meta": { "requestId": "e61be374-06e7-4338-b25d-9c795e54a869", "servedAt": "2026-11-08T00:00:00.000Z" }
              }
            } }
          },
          "400": { "description": "Invalid or conflicting parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Call through RapidAPI with an active subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Street address could not be geocoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Street address matched multiple places", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "503": { "description": "Census/FEMA upstream or service authentication temporarily unavailable", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": { "RapidApiKey": { "type": "apiKey", "in": "header", "name": "X-RapidAPI-Key", "description": "Subscribe on RapidAPI, then use your X-RapidAPI-Key and X-RapidAPI-Host. The origin accepts only RapidAPI gateway traffic." } },
    "schemas": {
      "FloodZoneResponse": {
        "type": "object",
        "required": ["location", "result", "source", "notices", "meta"],
        "properties": {
          "location": { "$ref": "#/components/schemas/Location" },
          "result": { "$ref": "#/components/schemas/FloodResult" },
          "source": { "$ref": "#/components/schemas/Source" },
          "notices": { "type": "array", "items": { "type": "string" } },
          "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "servedAt": { "type": "string", "format": "date-time" } } }
        }
      },
      "Location": {
        "type": "object",
        "required": ["latitude", "longitude", "coordinateSource"],
        "properties": {
          "inputAddress": { "type": "string" },
          "matchedAddress": { "type": "string", "nullable": true },
          "latitude": { "type": "number" },
          "longitude": { "type": "number" },
          "geocodeMatchType": { "type": "string", "nullable": true },
          "coordinateSource": { "type": "string", "enum": ["caller", "US Census Geocoder"] }
        }
      },
      "FloodResult": {
        "type": "object",
        "required": ["status", "floodZone", "zoneSubtype", "specialFloodHazardArea", "staticBaseFloodElevation", "elevationUnit", "mapPanel"],
        "properties": {
          "status": { "type": "string", "enum": ["mapped", "unmapped", "unknown", "ambiguous"] },
          "floodZone": { "type": "string", "nullable": true },
          "zoneSubtype": { "type": "string", "nullable": true },
          "specialFloodHazardArea": { "type": "boolean", "nullable": true },
          "staticBaseFloodElevation": { "type": "number", "nullable": true },
          "elevationUnit": { "type": "string", "nullable": true },
          "mapPanel": { "allOf": [{ "$ref": "#/components/schemas/MapPanel" }], "nullable": true },
          "candidateZones": { "type": "array", "description": "Present only when status is ambiguous.", "items": { "type": "object", "properties": { "floodZone": { "type": "string" }, "zoneSubtype": { "type": "string", "nullable": true }, "specialFloodHazardArea": { "type": "boolean", "nullable": true }, "dfirmId": { "type": "string", "nullable": true } } } }
        }
      },
      "MapPanel": { "type": "object", "required": ["number", "effectiveDate", "printed"], "properties": { "number": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date", "nullable": true }, "printed": { "type": "boolean" } } },
      "Source": { "type": "object", "required": ["name", "availabilityUrl", "floodZonesUrl", "firmPanelsUrl", "mapServiceCenterUrl", "capturedAt"], "properties": { "name": { "type": "string" }, "availabilityUrl": { "type": "string", "format": "uri" }, "floodZonesUrl": { "type": "string", "format": "uri" }, "firmPanelsUrl": { "type": "string", "format": "uri" }, "mapServiceCenterUrl": { "type": "string", "format": "uri" }, "capturedAt": { "type": "string", "format": "date-time" } } },
      "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "retryable", "requestId"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } } } } }
    }
  }
}