# mukoko weather > AI-powered weather intelligence platform for Zimbabwe. Real-time weather data, 7-day forecasts, frost alerts, and AI-generated contextual advice for farming, mining, travel, and daily life across 90+ Zimbabwe locations. Built by Nyuchi Africa (PVT) Ltd. mukoko weather provides hyperlocal weather data for Zimbabwe, a country underserved by global weather platforms. The AI assistant "Shamwari Weather" generates contextual advice tailored to user activities (farming, mining, travel, tourism, sports, casual) using the Ubuntu philosophy of community and interconnectedness. ## Company - **Nyuchi Africa (PVT) Ltd** is the parent company - **Nyuchi Web Services** is the technology/development arm - **Mukoko Africa** is a division of Nyuchi Africa - **mukoko weather** is a Mukoko Africa product - Contact: support@mukoko.com, hi@mukoko.com, legal@nyuchi.com - Social: Twitter @mukokoafrica, Instagram @mukoko.africa - GitHub: nyuchitech/mukoko-weather ## Live Site - Main: https://weather.mukoko.com - Harare: https://weather.mukoko.com/harare - Bulawayo: https://weather.mukoko.com/bulawayo - Victoria Falls: https://weather.mukoko.com/victoria-falls ## Pages - `/` redirects to `/harare` - `/[location]` dynamic weather pages for 90+ locations - `/[location]/atmosphere` 24-hour atmospheric detail charts for a location - `/[location]/forecast` hourly and daily forecast charts with sunrise/sunset - `/history` historical weather data dashboard with charts and statistics - `/help` help and frequently asked questions - `/about` about mukoko weather, Nyuchi Africa, and data sources - `/status` real-time health status of weather services - `/privacy` privacy policy - `/terms` terms of service - `/embed` documentation for embedding weather widgets on other sites ## Weather Data ### Providers Tomorrow.io is the primary weather data provider. If the Tomorrow.io API key is missing, rate-limited, or the request fails, the system falls back to Open-Meteo. The `X-Weather-Provider` response header indicates which provider served the data. - **Tomorrow.io** (primary): Real-time forecasts, hourly and daily data, free tier (500 calls/day, 25/hour) - **Open-Meteo** (fallback): Free weather API, 7-day forecasts, no authentication required ### Data Points Current conditions include: temperature, feels-like temperature, humidity, wind speed and direction, pressure, UV index, cloud cover, weather code, and whether it is day or night. Hourly forecasts (24 hours) include: temperature, feels-like, precipitation probability, weather code, wind speed, humidity, is-day flag. Daily forecasts (7 days) include: high/low temperature, feels-like high/low, precipitation probability, weather code, wind speed, sunrise, sunset. ### Frost Alerts The system detects frost risk when temperatures fall to 3 degrees Celsius or below between 10pm and 8am. Frost alerts are categorised as "warning" (temp <= 0C) or "advisory" (temp <= 3C). These are critical for Zimbabwe's farming sector. ### Caching Weather data is cached in MongoDB with a 15-minute TTL. AI summaries use tiered TTL: 30 minutes for major cities, 60 minutes for mid-tier locations, 120 minutes for smaller locations. Historical weather data is recorded automatically on every fresh API fetch with unlimited retention. ## AI Summaries Generated by Anthropic Claude via `POST /api/ai`. The AI persona is "Shamwari Weather" which follows the Ubuntu philosophy of community and provides Zimbabwe-specific context. Summaries are markdown-formatted with bold text, bullet points, and no headings. They cover current conditions, forecast outlook, and activity-specific advice. If the Anthropic API key is not configured, a basic weather summary fallback is generated without AI. ## Activities 20 activities across 6 categories provide personalised weather advice: ### Farming - crop-farming: Crop Farming (planting, irrigation, harvest conditions) - livestock: Livestock Management (heat stress, grazing, water needs) - irrigation: Irrigation Planning (scheduling, water management) ### Mining - open-pit: Open Pit Mining (heat exposure, dust, slope stability) - underground: Underground Mining (ventilation, flooding, access road conditions) - exploration: Mineral Exploration (fieldwork, sample collection) ### Travel - road-travel: Road Travel (driving conditions, visibility) - cross-border: Cross-Border Travel (border post conditions) - public-transport: Public Transport (commuter conditions) ### Tourism - safari: Safari & Wildlife (game viewing, photography light) - hiking: Hiking & Walking (trail conditions, altitude weather) - photography: Photography (golden hour, cloud interest, visibility) ### Sports - running: Running & Jogging (heat index, air quality) - cycling: Cycling (wind, rain, road conditions) - swimming: Swimming (outdoor pool/lake temperature) ### Casual - gardening: Gardening (soil moisture, frost risk) - outdoor-dining: Outdoor Dining (comfort, rain probability) - commuting: Daily Commute (morning conditions, umbrella needed) - laundry: Laundry Drying (sun, wind, rain probability) - events: Outdoor Events (wedding, sport, gathering conditions) ## Zimbabwe Locations 90+ locations across all 10 provinces. Each location has GPS coordinates, elevation, province, and category tags. ### Provinces - Harare (capital) - Bulawayo - Manicaland (eastern highlands) - Mashonaland Central - Mashonaland East - Mashonaland West - Masvingo (south) - Matabeleland North - Matabeleland South - Midlands ### Major Cities - Harare (capital, elevation 1490m) - Bulawayo (second largest, 1348m) - Victoria Falls (tourism hub, 915m) - Mutare (eastern gateway, 1073m) - Gweru (central, 1422m) - Masvingo (historical, 1095m) - Kwekwe (mining, 1214m) - Kadoma (mining, 1152m) - Chitungwiza (satellite city, 1463m) - Chinhoyi (caves tourism, 1143m) ### National Parks - Hwange National Park (largest, big five) - Mana Pools (UNESCO World Heritage, Zambezi floodplain) - Gonarezhou (south-east wilderness) - Nyanga National Park (eastern highlands, highest point) - Chimanimani National Park (mountain hiking) - Matusadona (Lake Kariba shore) - Chizarira (remote wilderness) - Zambezi National Park (Victoria Falls area) - Matopos (UNESCO, rock art) ### Key Tourism Sites - Great Zimbabwe (ancient ruins, UNESCO) - Lake Kariba (dam, fishing, houseboats) - Nyanga (mountain resort area) - Chimanimani (hiking) ### Mining Centres - Hwange Colliery (coal) - Zimplats/Ngezi (platinum) - Mimosa Mine (platinum) - Unki Mine (platinum) - Murowa Diamond (diamonds) - Marange (diamonds) - Renco Mine (gold) - Bikita Minerals (lithium) - Trojan Mine (nickel) - Kamativi (tin) ### Farming Regions - Mazowe (citrus, tobacco) - Triangle/Hippo Valley (sugar cane, lowveld) - Marondera (mixed farming, education) - Shamva (farming, gold mining) - Centenary (tobacco) - Gokwe (cotton) - Karoi (tobacco corridor) ### Border Posts - Beitbridge (South Africa border, busiest) - Chirundu (Zambia, one-stop border) - Forbes/Mutare (Mozambique) - Nyamapanda (Mozambique, north) - Plumtree (Botswana) - Kazungula (Zambia/Botswana, near Victoria Falls) - Kanyemba (Mozambique, remote) ## Zimbabwe Seasons Zimbabwe has four distinct seasons: - **Masika** (rainy season): November to March. Hot, humid, afternoon thunderstorms. - **Munakamwe** (post-rainy): March to May. Cooling, occasional rain. - **Chirimo** (cool dry): May to August. Cold nights, frost risk in highveld. - **Zhizha** (hot dry): August to November. Hot, dry, building to first rains. ## API Routes - `GET /api/weather?lat=&lon=` proxies weather data from Tomorrow.io or Open-Meteo, with MongoDB caching - `POST /api/ai` generates AI weather summaries via Claude, cached with tiered TTL - `GET /api/geo?lat=&lon=` finds nearest location to coordinates - `GET /api/history?location=&days=` returns historical weather data - `GET /api/status` returns health checks for MongoDB, weather APIs, and caches - `POST /api/db-init` one-time database setup (requires `x-init-secret` header in production) ## Technical Stack - Next.js 16 (App Router, TypeScript) - Chart.js 4 + react-chartjs-2 (Canvas 2D rendering) - Tailwind CSS 4 with CSS custom properties - Zustand 5 (state management with persist middleware) - MongoDB Atlas 7 (caching, AI summaries, history, locations) - Anthropic Claude SDK (server-side AI) - Vitest (testing, 480+ tests) - Deployed on Vercel ## Embed Widget External sites can embed mukoko weather widgets. Three display modes: "current" (current conditions), "forecast" (7-day), "badge" (compact). Self-contained CSS module, no Tailwind dependency. Documentation at /embed.