{
  "openapi": "3.1.0",
  "info": {
    "title": "CCA Wildfire API",
    "version": "1.0.0",
    "description": "Live and historical US wildfire data — active perimeters, incidents, evacuations, fire-weather alerts, burn scars and post-fire flooding. Part of the Cooperative Computing Alliance data-service fleet. Data is proxied and normalized from NIFC WFIGS (ArcGIS), MTBS (USGS/USFS) and NOAA/NWS.",
    "contact": { "name": "CCA Wildfire", "url": "https://wildfire.datasourceapi.com" }
  },
  "servers": [{ "url": "https://wildfire.datasourceapi.com" }],
  "tags": [
    { "name": "Statistics" }, { "name": "Fires" }, { "name": "Perimeters" },
    { "name": "Burn Scars" }, { "name": "Alerts" }, { "name": "Impacts" }
  ],
  "components": {
    "schemas": {
      "Envelope": {
        "type": "object",
        "properties": {
          "request_status": { "type": "string", "enum": ["success", "error"] },
          "data": {},
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "sources": { "type": "array", "items": { "type": "string" } },
          "generated_at": { "type": "string", "format": "date-time" },
          "count": { "type": ["integer", "null"] },
          "note": { "type": ["string", "null"] }
        }
      },
      "Incident": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "IRWIN ID (stable identifier)" },
          "name": { "type": "string" },
          "type": { "type": "string", "enum": ["Wildfire", "Prescribed"] },
          "acres": { "type": ["number", "null"] },
          "contained": { "type": ["number", "null"], "description": "Percent contained" },
          "cause": { "type": ["string", "null"] },
          "discovered": { "type": ["string", "null"], "format": "date-time" },
          "state": { "type": ["string", "null"] },
          "county": { "type": ["string", "null"] },
          "complexity": { "type": ["string", "null"] },
          "personnel": { "type": ["integer", "null"] },
          "cost": { "type": ["number", "null"] },
          "lat": { "type": ["number", "null"] },
          "lon": { "type": ["number", "null"] }
        }
      }
    }
  },
  "paths": {
    "/api/v1/stats": {
      "get": {
        "tags": ["Statistics"],
        "summary": "Nationwide wildland fire summary",
        "description": "Active wildland fire count, total acres burning, new fires in the last 24 hours, active Red Flag Warnings, total assigned personnel, total suppression cost to date, fully-contained count, the largest active fire, the human-vs-natural cause split, and impact metrics (active evacuation/civil alerts, open shelters and people sheltered from the National Shelter System, incidents filing ICS-209 reports, and the cited structures-destroyed-since-2005 aggregate).",
        "responses": { "200": { "description": "Summary statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    },
    "/api/v1/stats/by-cause": {
      "get": {
        "tags": ["Statistics"],
        "summary": "Active fires grouped by cause",
        "description": "Count and total acres of active wildland fires grouped by reported fire cause (Natural, Human, Undetermined, Unspecified).",
        "responses": { "200": { "description": "Array of { cause, count, acres }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    },
    "/api/v1/stats/by-state": {
      "get": {
        "tags": ["Statistics"],
        "summary": "Active fires grouped by state",
        "description": "Count and total acres of active wildland fires grouped by point-of-origin state, ordered by acres burning.",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 12 }, "description": "Maximum number of states to return" }],
        "responses": { "200": { "description": "Array of { state, count, acres }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    },
    "/api/v1/fires/active": {
      "get": {
        "tags": ["Fires"],
        "summary": "List active wildfire incidents",
        "parameters": [
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Two-letter state code, e.g. CA" },
          { "name": "minAcres", "in": "query", "schema": { "type": "number" }, "description": "Minimum incident size in acres" },
          { "name": "orderBy", "in": "query", "schema": { "type": "string", "default": "IncidentSize DESC" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 500 } }
        ],
        "responses": { "200": { "description": "Array of incidents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } } } } } }
      }
    },
    "/api/v1/fires/detail": {
      "get": {
        "tags": ["Fires"],
        "summary": "Get one incident by IRWIN ID",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Single incident" }, "404": { "description": "Not found" } }
      }
    },
    "/api/v1/perimeters/current": {
      "get": {
        "tags": ["Perimeters"],
        "summary": "Current fire perimeters (GeoJSON)",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 4000 } }],
        "responses": { "200": { "description": "GeoJSON FeatureCollection of polygons" } }
      }
    },
    "/api/v1/perimeters/history": {
      "get": {
        "tags": ["Perimeters"],
        "summary": "Historical fire perimeters (GeoJSON)",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "integer" } },
          { "name": "sinceYear", "in": "query", "schema": { "type": "integer" } },
          { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "west,south,east,north (WGS84)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 2000 } }
        ],
        "responses": { "200": { "description": "GeoJSON FeatureCollection" } }
      }
    },
    "/api/v1/burn-scars": {
      "get": {
        "tags": ["Burn Scars"],
        "summary": "MTBS burn-scar footprints (GeoJSON)",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "integer" } },
          { "name": "sinceYear", "in": "query", "schema": { "type": "integer" } },
          { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "west,south,east,north (WGS84)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 2000 } }
        ],
        "responses": { "200": { "description": "GeoJSON FeatureCollection with burn-severity thresholds" } }
      }
    },
    "/api/v1/debris-flow": {
      "get": {
        "tags": ["Debris Flow"],
        "summary": "USGS post-fire debris-flow assessments (GeoJSON points)",
        "description": "One point per fire assessed under the USGS Emergency Assessment of Post-Fire Debris-Flow Hazards program, with design-storm rainfall and links to the source data.",
        "parameters": [
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Substring match against the assessment location field" },
          { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "west,south,east,north (WGS84)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 500 } }
        ],
        "responses": { "200": { "description": "GeoJSON FeatureCollection of assessed fires" } }
      }
    },
    "/api/v1/debris-flow/basins": {
      "get": {
        "tags": ["Debris Flow"],
        "summary": "USGS debris-flow basin combined-hazard ratings (GeoJSON polygons)",
        "description": "Per-basin combined-hazard rating (Low/Moderate/High) for a design rainstorm, with debris-flow probability and potential-volume classes. Viewport (bbox) loading recommended.",
        "parameters": [
          { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "west,south,east,north (WGS84)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 1500 } }
        ],
        "responses": { "200": { "description": "GeoJSON FeatureCollection of basin polygons" } }
      }
    },
    "/api/v1/alerts/fire-weather": {
      "get": {
        "tags": ["Alerts"],
        "summary": "Active Red Flag Warnings & Fire Weather Watches (GeoJSON)",
        "parameters": [{ "name": "area", "in": "query", "schema": { "type": "string" }, "description": "Two-letter state code filter" }],
        "responses": { "200": { "description": "GeoJSON FeatureCollection of alert polygons" } }
      }
    },
    "/api/v1/alerts/flood-burn-scar": {
      "get": {
        "tags": ["Alerts"],
        "summary": "Post-fire flood alerts on burn scars (GeoJSON)",
        "description": "Active flood & flash-flood alerts whose text references a burn scar or burn area.",
        "responses": { "200": { "description": "GeoJSON FeatureCollection" } }
      }
    },
    "/api/v1/floods/history": {
      "get": {
        "tags": ["Alerts"],
        "summary": "Archived flood/flash-flood warning polygons (GeoJSON)",
        "description": "Historical NWS Storm Based Warning polygons for a warm season (May–Oct), sourced from the Iowa Environmental Mesonet. Intended to be intersected client-side with MTBS burn scars to reconstruct past post-fire flood events.",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "integer" }, "description": "Flood season year (defaults to previous year)" },
          { "name": "ph", "in": "query", "schema": { "type": "string", "default": "FF" }, "description": "VTEC phenomena code (FF = Flash Flood)" }
        ],
        "responses": { "200": { "description": "GeoJSON FeatureCollection of warning polygons" } }
      }
    },
    "/api/v1/evacuations": {
      "get": {
        "tags": ["Alerts"],
        "summary": "Evacuation & civil-emergency alerts (GeoJSON)",
        "description": "Best-effort national view from NWS civil/fire alerts. There is no single authoritative national evacuation feed — always confirm with local authorities and the PerimeterMap evacuation viewer.",
        "responses": { "200": { "description": "GeoJSON FeatureCollection" } }
      }
    },
    "/api/v1/shelters": {
      "get": {
        "tags": ["Alerts"],
        "summary": "Open emergency / evacuation shelters",
        "description": "Currently open Red Cross / FEMA National Shelter System (NSS) sites, returned both as tidy rows and as a GeoJSON FeatureCollection for mapping. Includes shelter name, operating organization, location, status, evacuation capacity, current population, pet accommodations and the associated incident. Empty when there are no active sheltering operations.",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 2000 }, "description": "Maximum number of shelters to return" }],
        "responses": { "200": { "description": "{ shelters: [...], geojson: FeatureCollection }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    },
    "/api/v1/impacts/annual": {
      "get": {
        "tags": ["Impacts"],
        "summary": "National annual wildfire impacts (reference dataset)",
        "description": "Year-end national totals: wildfires, acres burned and total federal suppression cost (NIFC/NICC), plus the cumulative structures-destroyed-since-2005 aggregate from Headwaters Economics' analysis of interagency ICS-209 / FAMAuth reports. Served as a cached reference dataset rather than a live feed.",
        "responses": { "200": { "description": "{ years: [{ year, fires, acres, suppression_cost }], structures_destroyed_since_2005, total_suppression_cost }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    }
  }
}