{"openapi":"3.1.0","info":{"title":"Geothermia API","version":"1.0.0","description":"Geothermal Power Analysis API - Comprehensive geothermal energy assessment including\nhot spring impact, temperature gradient analysis, direct use applications, and economic analysis.\n","contact":{"name":"Harmonias Support","url":"https://harmonias.org/support"},"license":{"name":"Proprietary","url":"https://harmonias.org/license"}},"servers":[{"url":"https://geothermia.harmonias.org","description":"Production"}],"tags":[{"name":"Geothermal Analysis","description":"Geothermal power potential and impact assessment"},{"name":"Resource Assessment","description":"Temperature gradient and hot spring analysis"},{"name":"Direct Use","description":"Direct heat applications and cascade utilization"},{"name":"Economics","description":"Financial analysis and ROI calculations"},{"name":"System","description":"Health checks and API information"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health Check","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"healthy":{"summary":"Normal healthy status","value":{"status":"healthy","service":"geothermia","version":"1.0.0","timestamp":"2024-01-15T10:30:00Z"}},"degraded":{"summary":"Degraded performance","value":{"status":"degraded","service":"geothermia","version":"1.0.0","timestamp":"2024-01-15T10:30:00Z","warnings":["High database latency","Cache miss rate elevated"]}}}}}}},"security":[]}},"/api/v1/info":{"get":{"tags":["System"],"summary":"API Information","operationId":"getApiInfo","responses":{"200":{"description":"API information and available endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInfo"},"examples":{"fullApiInfo":{"summary":"Complete API information","value":{"name":"Geothermia API","version":"1.0.0","description":"Geothermal Power Analysis API - Comprehensive geothermal energy assessment","endpoints":[{"path":"/api/v1/geothermal/potential","method":"POST","description":"Calculate geothermal potential"},{"path":"/api/v1/geothermal/hot-spring-impact","method":"POST","description":"Assess hot spring impact"},{"path":"/api/v1/geothermal/temperature-gradient","method":"POST","description":"Analyze temperature gradient"},{"path":"/api/v1/geothermal/direct-use","method":"POST","description":"Analyze direct heat applications"},{"path":"/api/v1/economics/roi-analysis","method":"POST","description":"Economic ROI analysis"}],"rateLimits":{"free":{"requestsPerHour":100,"requestsPerDay":1000},"basic":{"requestsPerHour":500,"requestsPerDay":10000},"pro":{"requestsPerHour":5000,"requestsPerDay":100000}}}},"basicInfo":{"summary":"Minimal API information","value":{"name":"Geothermia API","version":"1.0.0","description":"Geothermal energy analysis and economic assessment"}}}}}}}}},"/api/v1/disclaimer":{"get":{"tags":["System"],"summary":"API Disclaimer","operationId":"getDisclaimer","responses":{"200":{"description":"Important disclaimers and limitations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disclaimer"},"examples":{"fullDisclaimer":{"summary":"Complete disclaimer information","value":{"service":"Geothermia API","disclaimer":"This API provides geothermal energy analysis based on geological models and historical data. Results are estimates and should be validated by professional geological surveys and feasibility studies.","limitations":["Temperature gradient estimates have ±15-20°C uncertainty","Hot spring impact assessments require on-site hydrological surveys","Economic analyses use simplified models and average costs","Drilling depths and costs vary significantly by geology","Regulatory and environmental permits not included in analysis","Results do not constitute professional engineering advice"],"recommendations":["Consult certified geothermal engineers for project planning","Conduct thorough geological surveys before drilling","Engage with local hot spring stakeholders early","Obtain proper environmental impact assessments"]}},"shortDisclaimer":{"summary":"Brief disclaimer","value":{"service":"Geothermia API","disclaimer":"Geothermal analysis estimates for planning purposes only. Professional validation required.","limitations":["Results are estimates with inherent uncertainty","Does not replace professional engineering services"]}}}}}}}}},"/api/v1/geothermal/potential":{"post":{"tags":["Geothermal Analysis"],"summary":"Calculate Geothermal Potential","operationId":"calculateGeothermalPotential","description":"Analyzes geothermal power generation potential based on location, scale,\nsystem type, and resource characteristics.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeothermalPotentialInput"},"examples":{"flashSteam":{"summary":"Flash steam plant in volcanic region","value":{"location":{"lat":32.75,"lon":130.75,"prefecture":"Kumamoto"},"scale":"utility","type":"flash_steam","resources":{"temperature":250,"depth":2000,"flowRate":100}}},"binaryCycle":{"summary":"Binary cycle for lower temperature","value":{"location":{"lat":33.25,"lon":131.5,"prefecture":"Oita"},"scale":"community","type":"binary_cycle","resources":{"temperature":120,"depth":1500,"flowRate":50}}}}}}},"responses":{"200":{"description":"Geothermal potential analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeothermalPotentialResponse"},"examples":{"success":{"summary":"Successful analysis","value":{"success":true,"basic":{"capacity":{"value":50,"unit":"MW"},"capacityFactor":0.92,"feasibility":{"overall":"highly_feasible","score":0.88},"environmental":{"riskLevel":"moderate","riskScore":0.45,"hotSpringConflict":"possible"},"comparison":{"microReactorEquivalent":0.5,"advantages":["baseload_capability","low_emissions","long_lifespan"]}},"tier":"free"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: location, scale, type, resources"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid API key","message":"The provided API key is invalid or inactive"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"example":{"error":"Rate limit exceeded","message":"Rate limit exceeded. Resets at 2024-01-15T11:00:00Z","resetAt":"2024-01-15T11:00:00Z","tier":"free"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/geothermal/hot-spring-impact":{"post":{"tags":["Resource Assessment"],"summary":"Assess Hot Spring Impact","operationId":"assessHotSpringImpact","description":"Assesses potential impact on nearby hot springs and recommends mitigation measures.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HotSpringImpactInput"},"examples":{"moderateRisk":{"summary":"Moderate risk scenario - Beppu area","value":{"location":{"lat":33.25,"lon":131.5,"prefecture":"Oita"},"drillingDepth":2000,"extractionRate":100}},"highRisk":{"summary":"High risk scenario - Near famous hot spring","value":{"location":{"lat":34.67,"lon":135.83,"prefecture":"Hyogo"},"drillingDepth":2500,"extractionRate":150,"nearbyHotSprings":[{"name":"Arima Onsen","distance":1.2,"importance":"high"}]}}}}}},"responses":{"200":{"description":"Hot spring impact assessment results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HotSpringImpactResponse"},"example":{"success":true,"data":{"impactLevel":"moderate","affectedSprings":3,"riskScore":0.55,"mitigation":[{"type":"reinjection","effectiveness":"high","cost":5000000},{"type":"monitoring","effectiveness":"medium","cost":500000},{"type":"compensation","effectiveness":"low","cost":2000000}]},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: location, drillingDepth, extractionRate"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/geothermal/temperature-gradient":{"post":{"tags":["Resource Assessment"],"summary":"Analyze Temperature Gradient","operationId":"analyzeTemperatureGradient","description":"Analyzes temperature gradient and estimates drilling depth requirements.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemperatureGradientInput"},"examples":{"deepDrilling":{"summary":"Deep drilling in volcanic region","value":{"location":{"lat":32.75,"lon":130.75,"prefecture":"Kumamoto"},"targetDepth":3000}},"shallowHighGradient":{"summary":"Shallow drilling in high heat flow area","value":{"location":{"lat":38.25,"lon":140.83,"prefecture":"Iwate"},"targetDepth":1500,"expectedGradient":60}}}}}},"responses":{"200":{"description":"Temperature gradient analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemperatureGradientResponse"},"example":{"success":true,"data":{"gradient":45,"estimatedTemperature":185,"drillingCost":25000000,"recommendedDepth":2500,"uncertaintyRange":{"min":160,"max":210}},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: location, targetDepth"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/geothermal/direct-use":{"post":{"tags":["Direct Use"],"summary":"Analyze Direct Heat Applications","operationId":"analyzeDirectUse","description":"Analyzes direct heat applications and cascade utilization potential.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectUseInput"},"examples":{"cascadeUtilization":{"summary":"Cascade utilization for multiple applications","value":{"resourceSpecs":{"temperature":90,"flowRate":50},"applications":["district_heating","greenhouse","aquaculture"]}},"snowMelting":{"summary":"Snow melting system for northern region","value":{"resourceSpecs":{"temperature":60,"flowRate":80},"applications":["snow_melting","district_heating"],"location":{"lat":43.06,"lon":141.35,"prefecture":"Hokkaido"}}}}}}},"responses":{"200":{"description":"Direct use analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectUseResponse"},"example":{"success":true,"data":{"cascadeUtilization":[{"application":"district_heating","inletTemp":90,"outletTemp":50,"efficiency":0.85,"capacity":25},{"application":"greenhouse","inletTemp":50,"outletTemp":35,"efficiency":0.78,"capacity":12},{"application":"aquaculture","inletTemp":35,"outletTemp":25,"efficiency":0.65,"capacity":5}],"totalEfficiency":0.92,"economics":{"annualSavings":5000000,"payback":6.5,"carbonOffset":2500}},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: resourceSpecs, applications"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/economics/roi-analysis":{"post":{"tags":["Economics"],"summary":"Economic ROI Analysis","operationId":"analyzeROI","description":"Calculates return on investment, payback period, and financial\nmetrics for geothermal projects.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROIAnalysisInput"},"examples":{"utilityScale":{"summary":"Utility-scale flash steam plant (50 MW)","value":{"capacity":50,"installationCost":200000000,"maintenanceCostPerYear":3000000,"electricityPrice":12,"capacityFactor":0.92,"projectLifespan":30}},"smallBinaryCycle":{"summary":"Small binary cycle plant (5 MW)","value":{"capacity":5,"installationCost":25000000,"maintenanceCostPerYear":500000,"electricityPrice":15,"capacityFactor":0.85,"projectLifespan":25,"incentives":{"feedInTariff":18,"subsidyPercentage":0.2}}}}}}},"responses":{"200":{"description":"ROI analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROIAnalysisResponse"},"example":{"success":true,"data":{"roi":0.125,"paybackPeriod":9.5,"npv":80000000,"irr":0.098,"lcoe":0.045}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Missing required fields: capacity, installationCost, maintenanceCostPerYear"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/data-sources":{"get":{"summary":"Get data-sources","description":"Auto-generated stub. Schema/responses/parameters TBD.\nVerify path matches the actual mounted URL (sub-router prefix may be missing).\n","x-stub":true,"responses":{"200":{"description":"Successful response (schema TBD)"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key in format: Bearer <api_key>"}},"schemas":{"GeothermalType":{"type":"string","enum":["flash_steam","dry_steam","binary_cycle","enhanced_geothermal"],"description":"Type of geothermal power system"},"PlantScale":{"type":"string","enum":["small","community","industrial","utility"],"description":"Scale of the power plant"},"RiskLevel":{"type":"string","enum":["very_low","low","moderate","high","very_high"],"description":"Risk assessment level"},"FeasibilityRating":{"type":"string","enum":["not_feasible","marginally_feasible","feasible","highly_feasible"],"description":"Project feasibility rating"},"HotSpringImpactLevel":{"type":"string","enum":["none","minimal","moderate","significant","severe"],"description":"Hot spring impact level"},"DirectUseApplication":{"type":"string","enum":["district_heating","greenhouse","aquaculture","industrial_process","spa","snow_melting","drying"],"description":"Direct use application type"},"MitigationType":{"type":"string","enum":["reinjection","monitoring","compensation","buffer_zone","flow_control"],"description":"Mitigation measure type"},"MeasurementUnit":{"type":"string","enum":["kW","MW","celsius","meters","l/s","km","tCO2"],"description":"Unit of measurement"},"Location":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"prefecture":{"type":"string"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"service":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"ApiInfo":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"endpoints":{"type":"array","items":{"type":"object"}},"rateLimits":{"type":"object"}}},"Disclaimer":{"type":"object","properties":{"service":{"type":"string"},"disclaimer":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"success":{"type":"boolean","default":false}}},"RateLimitError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"resetAt":{"type":"string","format":"date-time"},"tier":{"type":"string","enum":["free","basic","pro"]}}},"GeothermalPotentialInput":{"type":"object","required":["location","scale","type","resources"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"scale":{"$ref":"#/components/schemas/PlantScale"},"type":{"$ref":"#/components/schemas/GeothermalType"},"resources":{"type":"object","required":["temperature","depth","flowRate"],"properties":{"temperature":{"type":"number","description":"Resource temperature in Celsius"},"depth":{"type":"number","description":"Depth in meters"},"flowRate":{"type":"number","description":"Flow rate in l/s"}}}}},"HotSpringImpactInput":{"type":"object","required":["location","drillingDepth","extractionRate"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"drillingDepth":{"type":"number","description":"Drilling depth in meters"},"extractionRate":{"type":"number","description":"Extraction rate in l/s"}}},"TemperatureGradientInput":{"type":"object","required":["location","targetDepth"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"targetDepth":{"type":"number","description":"Target depth in meters"}}},"DirectUseInput":{"type":"object","required":["resourceSpecs","applications"],"properties":{"resourceSpecs":{"type":"object","required":["temperature","flowRate"],"properties":{"temperature":{"type":"number"},"flowRate":{"type":"number"}}},"applications":{"type":"array","items":{"$ref":"#/components/schemas/DirectUseApplication"}}}},"ROIAnalysisInput":{"type":"object","required":["capacity","installationCost","maintenanceCostPerYear"],"properties":{"capacity":{"type":"number"},"installationCost":{"type":"number"},"maintenanceCostPerYear":{"type":"number"},"electricityPrice":{"type":"number"},"capacityFactor":{"type":"number"},"projectLifespan":{"type":"integer"}}},"GeothermalPotentialResponse":{"type":"object","properties":{"success":{"type":"boolean"},"basic":{"type":"object"},"detailed":{"type":"object"},"tier":{"type":"string","enum":["free","basic","pro"]}}},"HotSpringImpactResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"tier":{"type":"string"}}},"TemperatureGradientResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"tier":{"type":"string"}}},"DirectUseResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"tier":{"type":"string"}}},"ROIAnalysisResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"roi":{"type":"number"},"paybackPeriod":{"type":"number"},"npv":{"type":"number"},"irr":{"type":"number"},"lcoe":{"type":"number"}}}}}}},"security":[{"ApiKeyAuth":[]}]}