Developers & Public API

Base URL

All endpoints are relative to the production origin:

https://weather.mukoko.com

Current weather (embed)

GET /api/embed/current — a compact current-conditions payload built for widgets. Pass a slug or lat & lon. With no parameters it returns weather for the visitor's own location, derived from their IP.

# Visitor's local weather (IP-based)
curl "https://weather.mukoko.com/api/embed/current"

# A specific location by slug
curl "https://weather.mukoko.com/api/embed/current?slug=harare"

# Explicit coordinates
curl "https://weather.mukoko.com/api/embed/current?lat=-17.83&lon=31.05"

Response shape:

{
  "location": { "name": "Harare", "province": "Harare",
                "slug": "harare", "country": "ZW" },
  "current":  { "temp": 24, "feelsLike": 23, "code": 2,
                "condition": "Partly cloudy", "high": 27, "low": 14,
                "humidity": 55, "windSpeed": 9, "windDirection": "SE",
                "isDay": true },
  "daily": [ { "date": "2026-06-30", "day": "Today", "code": 2,
               "condition": "Partly cloudy", "high": 27, "low": 14,
               "precipitationProbability": 0 } /* up to 7 */ ],
  "source": "ip",
  "attribution": { "name": "mukoko weather",
                   "url": "https://weather.mukoko.com/harare" }
}

Full forecast

GET /api/py/weather?lat=&lon= — the complete forecast: current conditions plus 24-hour hourly and 7-day daily arrays. Add &models= (a comma list of gfs_seamless,ecmwf_ifs04,icon_seamless,meteofrance_seamless) for a Windy-style multi-model comparison. A next-hour precipitation nowcast (minutely, four 15-minute steps) is attached automatically when available.

# Full forecast for Harare
curl "https://weather.mukoko.com/api/py/weather?lat=-17.83&lon=31.05"

# With a multi-model comparison
curl "https://weather.mukoko.com/api/py/weather?lat=-17.83&lon=31.05&models=gfs_seamless,ecmwf_ifs04"

The response carries headers that tell you which provider served what: X-Weather-Provider (origin of the hourly/daily forecast — tomorrow / open-meteo / fallback) and X-Current-Source (origin of the current block, which may be stationkit when a nearby weather station is in range).

Nearest location (geo lookup)

GET /api/py/geo?lat=&lon= — resolves coordinates to the nearest known location (name, slug, province, country). Handy for turning a device GPS fix into a place.

curl "https://weather.mukoko.com/api/py/geo?lat=-17.83&lon=31.05"

Location lookup & search

GET /api/py/locations?slug= fetches a single location by slug. GET /api/py/search?q= runs a text search across supported locations.

# Look up a location by slug
curl "https://weather.mukoko.com/api/py/locations?slug=harare"

# Search locations by name
curl "https://weather.mukoko.com/api/py/search?q=nairobi"

Air quality

GET /api/py/airquality?lat=&lon= — the EPA-standard Air Quality Index (0–500) plus a seven-pollutant breakdown (PM2.5, PM10, O₃, NO₂, SO₂, CO, NH₃).

curl "https://weather.mukoko.com/api/py/airquality?lat=-17.83&lon=31.05"

Nearest airports

GET /api/py/airports/nearest?lat=&lon=&count= — the N nearest ICAO airports, each with its code, name, and distance in kilometres, sorted closest-first. count defaults to 5 (max 20).

curl "https://weather.mukoko.com/api/py/airports/nearest?lat=-17.83&lon=31.05&count=3"

AI endpoints

mukoko also runs AI-powered weather summaries and a Shamwari-branded chatbot backend. These are rate-limited and evolve quickly, so we don't document their internals here.

API keys (optional)

You never need a key for the public endpoints above. API keys are an optional extra for registered developers who want higher rate limits and named attribution for their traffic. Creating a key requires signing in.