{"openapi":"3.1.0","info":{"title":"30YearWeather Historical Weather API","description":"REST API providing 30-year historical weather intelligence for 373+ cities worldwide. Based on NASA POWER satellite data (1991-2024). Designed for AI agents, travel apps, wedding planners, and developers.\n\n## Features\n- 30-year climatological averages for any day\n- Rain probability, temperature ranges, humidity\n- Wedding & event scores\n- Health impact predictions (migraine, joint pain)\n- Marine conditions for coastal cities\n- Climate change trends through 2040\n\n## Use Cases\n- Travel planning AI assistants\n- Wedding date optimization\n- Event planning applications\n- Climate research tools","version":"1.0.0","contact":{"name":"30YearWeather Support","url":"https://30yearweather.com/api-docs","email":"api@30yearweather.com"},"license":{"name":"Free for non-commercial use with attribution","url":"https://30yearweather.com/terms"},"x-logo":{"url":"https://30yearweather.com/icon.png"}},"externalDocs":{"description":"Full API Documentation","url":"https://30yearweather.com/api-docs"},"servers":[{"url":"https://30yearweather.com","description":"Production server"}],"tags":[{"name":"Cities","description":"Get weather intelligence for specific cities"},{"name":"Search","description":"Find destinations matching weather criteria"},{"name":"Daily","description":"Get weather data for specific dates"}],"paths":{"/api/v1/search":{"get":{"operationId":"searchCities","tags":["Search"],"summary":"Search cities by weather criteria","description":"Finds cities that match specific weather requirements for a given month. Perfect for AI agents answering 'Where should I travel in May?' type queries.","parameters":[{"name":"month","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Month of travel (1-12)","example":5},{"name":"min_temp","in":"query","schema":{"type":"number"},"description":"Minimum average daily temperature (Celsius)","example":20},{"name":"max_rain_prob","in":"query","schema":{"type":"number","minimum":0,"maximum":100},"description":"Maximum allowed rain probability (0-100%)","example":30}],"responses":{"200":{"description":"List of matching cities with climate data","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"avg_temp":{"type":"number"},"rain_prob":{"type":"number"}}}}}}}}}},"/api/v1/city/{slug}":{"get":{"operationId":"getCityDetails","tags":["Cities"],"summary":"Get detailed city weather intelligence","description":"Returns comprehensive climate data including monthly averages, best times to visit, safety profiles, and 365-day forecasts based on 30 years of historical data.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"City slug (e.g., prague, tokyo, bali)","example":"prague"},{"name":"minified","in":"query","schema":{"type":"boolean","default":false},"description":"If true, returns summary only without daily data (smaller response for AI agents)"}],"responses":{"200":{"description":"City climate intelligence data","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"name":{"type":"string"},"country":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"}}},"summary":{"type":"object","properties":{"best_months":{"type":"array","items":{"type":"string"}},"avg_temp":{"type":"number"},"avg_rain_prob":{"type":"number"}}},"daily":{"type":"object","description":"366 days of weather data (excluded if minified=true)"}}}}}},"404":{"description":"City not found"}}}},"/api/v1/weather/{city}/{date}":{"get":{"operationId":"getDailyWeather","tags":["Daily"],"summary":"Get weather for a specific date","description":"Returns 30-year historical averages, scores, and health predictions for a specific day. Perfect for event planning and travel date selection.","parameters":[{"name":"city","in":"path","required":true,"schema":{"type":"string"},"description":"City slug","example":"rome"},{"name":"date","in":"path","required":true,"schema":{"type":"string","pattern":"^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$"},"description":"Date in MM-DD format","example":"06-15"}],"responses":{"200":{"description":"Daily weather intelligence","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"stats":{"type":"object","properties":{"temp_max":{"type":"number"},"temp_min":{"type":"number"},"precip_prob":{"type":"number"},"humidity":{"type":"number"},"wind_kmh":{"type":"number"}}},"scores":{"type":"object","properties":{"wedding":{"type":"integer","minimum":0,"maximum":100},"outdoor":{"type":"integer","minimum":0,"maximum":100}}},"health_impact":{"type":"object","properties":{"migraine_risk":{"type":"string","enum":["Low","Medium","High"]},"joint_pain_risk":{"type":"string","enum":["Low","Medium","High"]}}}}}}}},"404":{"description":"City not found"}}}}}}