{ "openapi": "3.1.1", "info": { "title": "Disaster Prep Builder API", "version": "1.0.0", "summary": "Build an emergency supply list for your household from official Ready.gov or BBK guidance.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://disasterprepbuilder.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Build an emergency supply list for your household from official Ready.gov or BBK guidance.", "description": "Enter your household (adults, children, infants, pets), the number of days and the hazards you face. The tool calculates water and food quantities from the official guideline you choose (Ready.gov in the US or the German BBK), builds a grouped checklist with hazard-specific additions quoted from the sources, and estimates cost only if you enter your own prices.\n\nMethodology:\n- Ready.gov: water = 1 US gallon (3.785 L) per person per day \"for several days, for drinking and sanitation\". Ready.gov names no fixed number of days; this tool defaults to 3 days unless you enter another value.\n- BBK: water = 2 liters per person per day (0.5 L of it for cooking); default 10 days (\"möglichst 10 Tage\"), with 3 days as a useful first step.\n- Water total = (adults + children + infants) × liters per person per day × days. Heat selected: an upper figure of 2 × that amount is shown (Ready.gov: \"In very hot temperatures, water needs can double\").\n- Food energy = (adults × kcal per adult + children × kcal per child) × days. Defaults: 2,200 kcal per adult (basis of the German BLE stock calculator) and 1,500 kcal per child (tool assumption).\n- Counted items: flashlights = number of people (Ready.gov: \"flashlights for every household member\"); sleeping bag or warm blanket for each person (Ready.gov); spare battery sets = flashlights + 1 radio (tool assumption).\n- Checklist groups and hazard additions are quoted from the chosen guideline and the Ready.gov hazard pages; items without a quantity in the source are listed without one.\n- Cost = quantity × your unit price, only for items you price; no prices are assumed.\n\nFollow instructions from local authorities. Medical and infant needs vary; ask your doctor or pharmacist.", "tags": [ "high-value" ], "x-mcp-tool": "disaster_prep_builder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisasterPrepBuilderInput" }, "examples": { "example1": { "summary": "US family of four, power outage + winter storm", "value": { "guideline": "readygov", "adults": 2, "children": 2, "dogs": 1, "hazards": [ "power-outage", "winter-storm" ], "currency": "USD" } }, "example2": { "summary": "German couple with infant, 10 days, with prices", "value": { "guideline": "bbk", "adults": 2, "infants": 1, "hazards": [ "power-outage", "flood", "heat" ], "medicalNeeds": true, "currency": "EUR", "budget": 150, "unitPrices": [ { "item": "water-liter", "price": 0.3 }, { "item": "food-1000kcal", "price": 1.2 }, { "item": "flashlight", "price": 8 }, { "item": "radio", "price": 25 } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisasterPrepBuilderResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "DisasterPrepBuilderInput": { "type": "object", "additionalProperties": false, "properties": { "guideline": { "title": "Guideline", "type": "string", "enum": [ "readygov", "bbk" ], "default": "readygov" }, "adults": { "title": "Adults (and teenagers)", "type": "integer", "minimum": 0, "maximum": 50, "default": 2 }, "children": { "title": "Children", "type": "integer", "minimum": 0, "maximum": 50, "default": 0 }, "infants": { "title": "Infants", "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "dogs": { "title": "Dogs", "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "cats": { "title": "Cats", "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "days": { "title": "Days of supply", "description": "Empty = guideline default (BBK: 10 days; Ready.gov says \"several days\", this tool uses 3).", "type": "integer", "minimum": 1, "maximum": 90, "x-unit": "days" }, "hazards": { "title": "Hazards to prepare for", "type": "array", "items": { "type": "string", "enum": [ "power-outage", "flood", "heat", "winter-storm", "earthquake", "wildfire", "pandemic" ] }, "default": [ "power-outage" ] }, "medicalNeeds": { "title": "Someone needs regular medication or medical devices", "type": "boolean", "default": false }, "kcalPerAdultDay": { "title": "Food energy per adult per day", "description": "2,200 kcal is the basis of the German BLE stock calculator; Ready.gov gives no calorie figure.", "type": "number", "minimum": 500, "maximum": 6000, "default": 2200, "x-unit": "kcal" }, "kcalPerChildDay": { "title": "Food energy per child per day", "description": "Tool assumption; adjust to your children's ages.", "type": "number", "minimum": 300, "maximum": 4000, "default": 1500, "x-unit": "kcal" }, "dogWaterLitersPerDay": { "title": "Water per dog per day (optional)", "description": "The sources give no amount; ask your vet. Leave empty to list pet water without a quantity.", "type": "number", "minimum": 0, "maximum": 20, "x-unit": "L" }, "catWaterLitersPerDay": { "title": "Water per cat per day (optional)", "type": "number", "minimum": 0, "maximum": 5, "x-unit": "L" }, "currency": { "title": "Currency", "type": "string", "maxLength": 8, "default": "EUR" }, "budget": { "title": "Budget (optional)", "type": "number", "minimum": 0 }, "unitPrices": { "title": "Your unit prices (optional)", "description": "Costs are only estimated for items you price here.", "type": "array", "maxItems": 7, "items": { "type": "object", "additionalProperties": false, "properties": { "item": { "title": "Item", "type": "string", "enum": [ "water-liter", "food-1000kcal", "flashlight", "battery-set", "radio", "first-aid-kit", "sleeping-bag-blanket" ] }, "price": { "title": "Price per unit", "type": "number", "minimum": 0 } }, "required": [ "item", "price" ] } } }, "required": [ "adults" ] }, "DisasterPrepBuilderResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "guideline", "days", "people", "waterLiters", "waterLitersPerPersonPerDay", "waterLitersHotWeather", "petWaterLiters", "foodKcal", "quantities", "checklist", "hazardAdditions", "cost" ], "properties": { "guideline": { "type": "string", "enum": [ "readygov", "bbk" ] }, "days": { "type": "integer" }, "people": { "type": "integer" }, "waterLitersPerPersonPerDay": { "type": "number" }, "waterLiters": { "type": "number", "description": "people × liters per person per day × days." }, "waterLitersHotWeather": { "type": [ "number", "null" ], "description": "Double the water figure (Ready.gov: in very hot temperatures water needs can double); only when heat is selected." }, "petWaterLiters": { "type": [ "number", "null" ], "description": "Only if pet water per day was entered." }, "foodKcal": { "type": "number", "description": "(adults × kcal/adult + children × kcal/child) × days; infants excluded (formula/baby food listed separately)." }, "quantities": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "item", "quantity", "unit", "basis" ], "properties": { "item": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "basis": { "type": "string" } } } }, "checklist": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "group", "items", "source" ], "properties": { "group": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" } } } }, "hazardAdditions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "hazard", "items", "source" ], "properties": { "hazard": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" } } } }, "cost": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "currency", "lines", "total", "budget", "withinBudget" ], "properties": { "currency": { "type": "string" }, "total": { "type": "number" }, "budget": { "type": [ "number", "null" ] }, "withinBudget": { "type": [ "boolean", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "item", "quantity", "unitPrice", "cost" ], "properties": { "item": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "cost": { "type": "number" } } } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }