{"openapi":"3.0.3","info":{"title":"Weathio - Japan Weather API","version":"2.0.0","description":"Japan weather data API powered by JMA (Japan Meteorological Agency) official data.\n\n## Features\n- Current weather conditions for all Japanese regions\n- 7-day weather forecasts (daily and hourly)\n- Weather alerts and warnings (heavy rain, storm, flood, etc.)\n- Historical weather data retrieval\n- Location search by prefecture, region, or keyword\n- Bilingual support (Japanese/English)\n- Metric and imperial unit systems\n- AMeDAS observation data (~1,300 stations, 10-min cadence)\n\n## Data Source\nOfficial JMA (Japan Meteorological Agency) data, updated hourly for forecasts\nand every 10 minutes for AMeDAS observations (polled every 3 minutes so the\nfreshest snapshot lands within ~3 min of JMA publishing it).\n\n## Rate Limits\n- Free: 100 req/day\n- Standard: 10,000 req/day\n- Professional: 100,000 req/day\n","contact":{"name":"Weathio Support","email":"support@weathio.org"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.weathio.org","description":"Production server"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"Current","description":"Current weather conditions and real-time observations"},{"name":"Forecast","description":"Weather forecasts up to 7 days (daily and hourly)"},{"name":"Historical","description":"Historical weather data retrieval"},{"name":"Alerts","description":"Weather alerts, warnings, and emergency notifications"},{"name":"Locations","description":"Location search and region information"}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"getHealth","tags":["System"],"security":[],"responses":{"200":{"description":"Service healthy"}}}},"/api/info":{"get":{"summary":"Get the live API info banner (data sources, freshness, scope).","description":"Returns the human-readable API info banner: backing JMA data sources,\nupdate cadence (forecasts hourly, AMeDAS every 10 minutes), supported\nregions, and current rate limit tiers. Use as a once-per-session\ncapability check.\n","operationId":"getApiInfo","tags":["System"],"security":[],"responses":{"200":{"description":"API info banner"}}}},"/v1/metadata/enums":{"get":{"summary":"List every enum used by the Weathio API.","description":"Returns the directory of enums (region codes, weather codes, alert\nlevels, index types) with localised labels. Use when building UIs\nthat mirror the API's vocabulary.\n","operationId":"listEnums","tags":["Metadata"],"security":[],"responses":{"200":{"description":"Enum metadata"}}}},"/v1/metadata/enums/{name}":{"get":{"summary":"Get one Weathio enum (region_code, weather_code, alert_level) by name.","operationId":"getEnum","tags":["Metadata"],"description":"Returns localised values for one enum. See `listEnums` for available\nenum names.\n","security":[],"parameters":[{"name":"name","in":"path","required":true,"example":"region_code","schema":{"type":"string"}}],"responses":{"200":{"description":"Enum values"}}}},"/api/v1/weather/overview":{"get":{"summary":"Get a nationwide Japanese weather overview (current snapshot).","description":"Returns the current nationwide JMA weather overview — major region\nsummaries, active alerts, and notable weather phenomena. Refreshed\nhourly from JMA. Use as a single-shot \"what's the weather today?\"\nfeed.\n","operationId":"getWeatherOverview","tags":["Weather"],"security":[],"responses":{"200":{"description":"Nationwide weather overview"}}}},"/api/v1/weather/forecast":{"get":{"summary":"Get the 7-day national-level Japanese weather forecast.","description":"Returns the 7-day daily forecast at national/regional level (high/low\ntemperature, precipitation probability, weather condition). Use for\nnational-scale reporting; for region-specific use `getWeatherByRegion`.\n","operationId":"getWeatherForecast","tags":["Weather"],"security":[],"responses":{"200":{"description":"7-day forecast"}}}},"/api/v1/weather/warnings":{"get":{"summary":"List active JMA weather warnings & advisories.","description":"Returns the current set of JMA-issued weather warnings (heavy rain,\nflood, storm, snow, etc.) and advisories nationwide, with affected\nregions and severity. Source: JMA bosai feed, refreshed every few\nminutes.\n","operationId":"getWeatherWarnings","tags":["Alerts"],"security":[],"responses":{"200":{"description":"Active warnings & advisories"}}}},"/api/v1/weather/region/{regionCode}":{"get":{"summary":"Get current weather + 7-day forecast for one Japanese region.","description":"Returns the current weather and full 7-day forecast for a JMA region\n(use `region_code` enum for valid IDs — typically 6-digit JMA area\ncodes). Includes hourly detail for the next 24 hours.\n","operationId":"getWeatherByRegion","tags":["Weather"],"security":[],"parameters":[{"name":"regionCode","in":"path","required":true,"description":"JMA region code (use `listEnums` → `region_code`).","example":"130000","schema":{"type":"string"}}],"responses":{"200":{"description":"Region weather + forecast"},"404":{"description":"Unknown region code"}}}},"/api/v1/weather/cloud-layers":{"get":{"summary":"Get vertical cloud-layer profile (low / mid / high coverage %).","description":"Returns the predicted cloud-coverage percentages by altitude layer\n(low ~0-2km, mid ~2-7km, high >7km) for a coordinate. Useful for\nastrophotography, aviation, and irradiance modelling.\n","operationId":"getCloudLayers","tags":["Weather"],"security":[],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","format":"double","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":true,"schema":{"type":"number","format":"double","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Cloud-layer profile"}}}},"/api/v1/weather/daily-forecast":{"get":{"summary":"Get a daily weather forecast at a coordinate (10-day window).","description":"Returns daily-resolution forecast (high/low temperature,\nprecipitation, condition) over the next ~10 days at the requested\n(lat, lon). Distinct from the regional `getWeatherForecast` —\ncoordinate-precise.\n","operationId":"getDailyForecast","tags":["Weather"],"security":[],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","format":"double","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":true,"schema":{"type":"number","format":"double","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Daily forecast at the point"}}}},"/api/v1/weather/hourly":{"get":{"summary":"Get an hourly weather forecast at a coordinate.","description":"Returns hourly-resolution forecast for the requested (lat, lon)\nincluding temperature, humidity, wind, precipitation, weather code\nand cloud cover. Backed by Open-Meteo so it works globally — JMA\ndoes not provide hourly forecasts at the variable level. Cached\nfor 1 hour.\n","operationId":"getHourlyForecast","tags":["Weather"],"security":[],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","format":"double","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":true,"schema":{"type":"number","format":"double","minimum":-180,"maximum":180}},{"name":"hours","in":"query","required":false,"description":"Number of forward hours to return (default 72, max 168).","schema":{"type":"integer","minimum":1,"maximum":168,"default":72}}],"responses":{"200":{"description":"Hourly forecast at the point"},"400":{"description":"Invalid lat/lon/hours"},"503":{"description":"Upstream Open-Meteo unavailable"}}}},"/api/v1/indices/":{"get":{"summary":"List all weather-derived lifestyle indices for a location.","description":"Returns Weathio's curated lifestyle/comfort indices in one call —\nlaundry-drying, heat-stroke, futon-airing, oden, nabe, ice-cream,\nbeer, nikuman, jogging, etc. Each is a 0-100 score with advice.\nRefreshed hourly with the underlying weather forecast.\n","operationId":"listIndices","tags":["Indices"],"security":[],"parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number","format":"double"}},{"name":"lon","in":"query","required":false,"schema":{"type":"number","format":"double"}}],"responses":{"200":{"description":"All lifestyle indices"}}}},"/api/v1/indices/laundry":{"get":{"summary":"Laundry-drying index (0–100) at a coordinate.","description":"Returns the laundry-drying score combining humidity, sunshine,\ntemperature, and precipitation forecast. Includes advice text.\n","operationId":"getLaundryIndex","tags":["Indices"],"security":[],"responses":{"200":{"description":"Laundry index"}}}},"/api/v1/indices/heat-stroke":{"get":{"summary":"Heat-stroke risk index (WBGT-based) at a coordinate.","description":"Returns the heat-stroke risk based on Wet-Bulb Globe Temperature\n(WBGT). Critical during Japanese summer; provides activity advice\nthresholds.\n","operationId":"getHeatStrokeIndex","tags":["Indices"],"security":[],"responses":{"200":{"description":"Heat-stroke risk score"}}}},"/api/v1/indices/futon":{"get":{"summary":"Futon-airing suitability index for the day.","operationId":"getFutonIndex","description":"Returns the score for whether today is suitable for airing futons\noutdoors (combines humidity, sunshine, pollen, dust). Includes\nmorning vs afternoon recommendations.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Futon-airing index"}}}},"/api/v1/indices/oden":{"get":{"summary":"Oden (winter hot-pot) suitability index — temperature-driven.","operationId":"getOdenIndex","description":"Returns whether today's weather makes oden weather. Index based on\ntemperature drop, wind chill, humidity. Whimsical lifestyle index.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Oden index"}}}},"/api/v1/indices/nabe":{"get":{"summary":"Nabe (hot-pot) suitability index for the day.","operationId":"getNabeIndex","description":"Like `getOdenIndex` but for the broader nabe category. Indicates\nwhether today's weather invites hot-pot dining.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Nabe index"}}}},"/api/v1/indices/ice-cream":{"get":{"summary":"Ice-cream consumption-temperature index.","operationId":"getIceCreamIndex","description":"Returns the ice-cream index — high when temperature/humidity drive\nice-cream demand. Used by retail and forecast clients.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Ice-cream index"}}}},"/api/v1/indices/beer":{"get":{"summary":"Beer-suitability index (warm-evening driver).","operationId":"getBeerIndex","description":"Returns the beer index — high when warm temperature, low humidity,\nand clear evening conditions encourage beer consumption.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Beer index"}}}},"/api/v1/indices/nikuman":{"get":{"summary":"Nikuman (steamed bun) suitability index — cold-weather driver.","operationId":"getNikumanIndex","description":"Returns the nikuman (steamed bun) index — high when cold and humid\nweather drives demand for warm hand-held steamed buns.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Nikuman index"}}}},"/api/v1/indices/jogging":{"get":{"summary":"Outdoor-jogging suitability index for the next 24 hours.","operationId":"getJoggingIndex","description":"Returns the jogging-suitability score combining temperature, wind,\nhumidity, precipitation, air quality, and UV. Provides best-time\nrecommendation for a jog.\n","tags":["Indices"],"security":[],"responses":{"200":{"description":"Jogging index"}}}},"/api/v1/amedas/latest":{"get":{"summary":"Latest AMeDAS observation for a single station.","description":"Returns the most recent observation row for the requested AMeDAS\nstation (temperature, humidity, wind, precipitation, pressure).\nAMeDAS is the JMA's high-density automated weather network — JMA\npublishes new observations every 10 minutes; the collector polls every\n3 minutes so a fresh snapshot is visible within ~3 min of publication.\n\nUse `listAmedasStations` first to discover valid `station_id` values.\n","operationId":"getLatestAmedas","tags":["AMeDAS"],"security":[],"parameters":[{"name":"station_id","in":"query","required":true,"description":"AMeDAS station ID (5-digit, e.g. '44132' = 東京).","example":"44132","schema":{"type":"string"}}],"responses":{"200":{"description":"Latest AMeDAS observation"},"404":{"description":"No observation row in amedas_history for this station yet"}}}},"/api/v1/amedas/stations":{"get":{"summary":"List AMeDAS stations with metadata.","description":"Returns the AMeDAS station catalogue (ID, name, prefecture, lat/lon,\nelevation, available metrics). Use to discover valid `station_id`\nvalues for `getAmedasHistory`.\n","operationId":"listAmedasStations","tags":["AMeDAS"],"security":[],"parameters":[{"name":"prefecture","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"AMeDAS station catalogue"}}}},"/api/v1/amedas/history/{station_id}":{"get":{"summary":"Recent AMeDAS history for a station (last N hours, 10-min cadence).","description":"Returns recent observation history for a single AMeDAS station at\nnative 10-minute cadence. Default 24h (≈144 rows), max 168h (1 week).\nFor longer windows, use `getAmedasHistorical`.\n\n**Status:** the underlying D1 store is still being back-filled from\nthe R2 data lake (multi-year accumulation in progress). Response may\nreturn `source: AMEDAS_PARAMETRIC_FALLBACK` until the back-fill catches\nup. The endpoint will be promoted to public-stable once a full year of\nobservations is queryable; until then treat coverage as best-effort.\n","operationId":"getAmedasHistory","tags":["AMeDAS"],"security":[],"parameters":[{"name":"station_id","in":"path","required":true,"description":"AMeDAS station ID (use `listAmedasStations` to discover).","example":"44132","schema":{"type":"string"}},{"name":"hours","in":"query","required":false,"description":"Look-back window in hours (1–168, default 24).","schema":{"type":"integer","default":24,"minimum":1,"maximum":168}}],"responses":{"200":{"description":"Recent AMeDAS history (rows ordered newest-first)"}}}},"/api/v1/amedas/historical/{station_id}":{"get":{"summary":"Bounded-range AMeDAS observations for a station (paginated).","description":"Returns AMeDAS history bounded by an explicit ISO-8601 start/end range,\nwith cursor-style pagination (`limit`/`offset`). Hard cap of 10,000 rows\nper page. Use for climatology / trend studies once enough history has\naccumulated.\n\n**Status:** the underlying D1 store is still being back-filled from\nthe R2 data lake (`weathio-amedas-raw`, accumulating since 2025-09).\nThe intended steady state is **multi-year retention** queryable here;\nuntil back-fill completes, requests outside the populated window will\nreturn `source: AMEDAS_PARAMETRIC_FALLBACK` rather than an error.\n","operationId":"getAmedasHistorical","tags":["AMeDAS"],"security":[],"parameters":[{"name":"station_id","in":"path","required":true,"description":"AMeDAS station ID.","example":"44132","schema":{"type":"string"}},{"name":"start","in":"query","required":true,"description":"Window start (ISO-8601 timestamp, inclusive).","schema":{"type":"string","format":"date-time"}},{"name":"end","in":"query","required":true,"description":"Window end (ISO-8601 timestamp, inclusive).","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Max rows per page (1–10000, default 1000).","schema":{"type":"integer","default":1000,"minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"description":"Rows to skip (for pagination).","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Long-term AMeDAS history"}}}}},"components":{"schemas":{"CurrentWeather":{"type":"object","required":["location_id","timestamp","temperature","humidity","weather_condition"],"properties":{"location_id":{"type":"string","description":"地域ID","example":"130000"},"timestamp":{"type":"string","format":"date-time","description":"データ取得時刻"},"temperature":{"type":"number","description":"気温","example":25.5},"feels_like":{"type":"number","description":"体感温度","example":28.2},"humidity":{"type":"integer","description":"湿度（%）","minimum":0,"maximum":100,"example":65},"pressure":{"type":"number","description":"気圧（hPa）","example":1013.25},"wind_speed":{"type":"number","description":"風速（m/s）","example":3.5},"wind_direction":{"type":"integer","description":"風向（度）","minimum":0,"maximum":359,"example":180},"visibility":{"type":"number","description":"視程（km）","example":10},"weather_condition":{"$ref":"#/components/schemas/WeatherCondition"},"precipitation":{"type":"number","description":"降水量（mm/h）","example":0},"uv_index":{"type":"integer","description":"UV指数","minimum":0,"maximum":11,"example":7}}},"WeatherCondition":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string","description":"気象コード","example":"200"},"description":{"type":"string","description":"天気の説明","example":"晴れ"},"icon":{"type":"string","description":"アイコンコード","example":"01d"}}},"Forecast":{"type":"object","required":["location_id","daily"],"properties":{"location_id":{"type":"string","description":"地域ID"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/DailyForecast"}},"hourly":{"type":"array","items":{"$ref":"#/components/schemas/HourlyForecast"}}}},"DailyForecast":{"type":"object","required":["date","temperature_max","temperature_min","weather_condition","precipitation_probability"],"properties":{"date":{"type":"string","format":"date","description":"日付"},"temperature_max":{"type":"number","description":"最高気温"},"temperature_min":{"type":"number","description":"最低気温"},"weather_condition":{"$ref":"#/components/schemas/WeatherCondition"},"precipitation_probability":{"type":"integer","description":"降水確率（%）","minimum":0,"maximum":100},"precipitation_amount":{"type":"number","description":"予想降水量（mm）"},"wind_speed_max":{"type":"number","description":"最大風速（m/s）"},"humidity_avg":{"type":"integer","description":"平均湿度（%）"}}},"HourlyForecast":{"type":"object","required":["datetime","temperature","weather_condition","precipitation_probability"],"properties":{"datetime":{"type":"string","format":"date-time","description":"日時"},"temperature":{"type":"number","description":"気温"},"weather_condition":{"$ref":"#/components/schemas/WeatherCondition"},"precipitation_probability":{"type":"integer","description":"降水確率（%）"},"precipitation_amount":{"type":"number","description":"予想降水量（mm）"},"wind_speed":{"type":"number","description":"風速（m/s）"},"wind_direction":{"type":"integer","description":"風向（度）"},"humidity":{"type":"integer","description":"湿度（%）"}}},"WeatherAlert":{"type":"object","required":["id","type","level","title","issued_at","valid_until"],"properties":{"id":{"type":"string","description":"警報ID"},"type":{"type":"string","enum":["heavy_rain","storm","flood","landslide","high_wave","storm_surge","blizzard","heavy_snow","avalanche"],"description":"警報種別"},"level":{"type":"string","enum":["warning","advisory","emergency"],"description":"警報レベル"},"title":{"type":"string","description":"警報タイトル"},"description":{"type":"string","description":"詳細説明"},"issued_at":{"type":"string","format":"date-time","description":"発表時刻"},"valid_until":{"type":"string","format":"date-time","description":"有効期限"},"affected_areas":{"type":"array","items":{"type":"string"},"description":"影響地域"}}},"HistoricalData":{"type":"object","required":["date","temperature_max","temperature_min","precipitation"],"properties":{"date":{"type":"string","format":"date","description":"日付"},"temperature_max":{"type":"number","description":"最高気温"},"temperature_min":{"type":"number","description":"最低気温"},"temperature_avg":{"type":"number","description":"平均気温"},"precipitation":{"type":"number","description":"降水量（mm）"},"sunshine_hours":{"type":"number","description":"日照時間（時間）"},"humidity_avg":{"type":"integer","description":"平均湿度（%）"},"wind_speed_avg":{"type":"number","description":"平均風速（m/s）"}}},"Location":{"type":"object","required":["id","name","prefecture"],"properties":{"id":{"type":"string","description":"地域ID","example":"130000"},"name":{"type":"string","description":"地域名","example":"東京"},"prefecture":{"type":"string","description":"都道府県","example":"東京都"},"region":{"type":"string","description":"地方","example":"関東"}}},"LocationDetail":{"allOf":[{"$ref":"#/components/schemas/Location"},{"type":"object","properties":{"latitude":{"type":"number","description":"緯度","example":35.6762},"longitude":{"type":"number","description":"経度","example":139.6503},"elevation":{"type":"number","description":"標高（m）","example":40},"timezone":{"type":"string","description":"タイムゾーン","example":"Asia/Tokyo"},"observation_station":{"type":"string","description":"観測所名","example":"東京"}}}]},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"エラーコード"},"message":{"type":"string","description":"エラーメッセージ"},"details":{"type":"object","description":"詳細情報"}}}},"parameters":{"LocationId":{"name":"locationId","in":"path","required":true,"description":"地域ID（JMAコード）","schema":{"type":"string","example":"130000"}},"Units":{"name":"units","in":"query","description":"単位系","schema":{"type":"string","enum":["metric","imperial"],"default":"metric"}},"Language":{"name":"lang","in":"query","description":"言語","schema":{"type":"string","enum":["ja","en"],"default":"ja"}},"Days":{"name":"days","in":"query","description":"予報日数","schema":{"type":"integer","minimum":1,"maximum":7,"default":3}},"Hourly":{"name":"hourly","in":"query","description":"時間別予報を含む","schema":{"type":"boolean","default":false}},"AlertLevel":{"name":"level","in":"query","description":"警報レベルでフィルタ","schema":{"type":"string","enum":["warning","advisory","emergency"]}}},"responses":{"BadRequest":{"description":"不正なリクエスト","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INVALID_PARAMETER","message":"Invalid location ID format"}}}},"NotFound":{"description":"リソースが見つかりません","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"NOT_FOUND","message":"Location not found"}}}},"TooManyRequests":{"description":"レート制限超過","headers":{"X-RateLimit-Limit":{"description":"レート制限数","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"残りリクエスト数","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"リセット時刻（Unix timestamp）","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API Key認証"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT Bearer Token認証"}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}]}