Fuzzy-search the 45 curated Australian locations.

The curated set covers all 8 state/territory capitals plus 37 major regional centres (every AU population centre over ~25k). Anything outside the curated set still resolves via place-name geocoding or postcode lookup — see list_curated() for the full set.

Examples: results = await search_locations("sydney") # → [{id: 'sydney', name: 'Sydney', state: 'NSW', ...}]

results = await search_locations("nsw")
# → Newcastle, Wollongong, Sydney (all NSW locations)

When to use: - Discover the location ID for a city you know by name - Find all supported locations in a state - Verify whether a place is in the curated set before calling get_weather

Returns: List of LocationSummary (id, name, state, description), ranked by relevance.

Return metadata for an Australian location — name, lat/lng, timezone, elevation, and (for curated locations) the nearest BOM station ID.

Accepts a wide range of input shapes for compatibility — see the location parameter description. The returned id is None for non-curated lookups (geocoded place names, raw coordinates) and a snake_case curated key when the input matched the curated set.

Examples: await describe_location("sydney") # → curated path await describe_location("Sydney") # → curated path (case-insensitive) await describe_location("NSW") # → state capital (Sydney) await describe_location("Margaret River") # → geocoded (Western Australia) await describe_location("-33.87,151.21") # → raw coordinates

When to use: - Before calling get_weather, to confirm coordinates and timezone - To cross-reference with BOM's own observation network (for curated) - To verify how the server resolved an ambiguous customer input

Returns: LocationDetail with id (or None), name, state, lat/lng, timezone, elevation, nearest BOM station ID (curated only), the Open-Meteo URL, and the CC-BY attribution.

Return the current weather observation for any Australian location.

Wraps Open-Meteo's /forecast endpoint with current=... parameters and a 15-minute cache TTL (matches Open-Meteo's own update cadence). Use for "what's the weather right now?" — warm-cache latency < 100 ms.

Examples: resp = await latest("sydney") # curated, fast path resp = await latest("Sydney") # case-insensitive resp = await latest("Byron Bay") # geocoded resp = await latest("NSW") # state → Sydney resp = await latest("-33.87,151.21") # raw coordinates

The response's location_resolution field tells the agent how the input was interpreted ('curated', 'state_alias', 'geocoded', 'raw_coordinates', or 'fuzzy_curated').

When to use: - "What's the weather right now in ?" — canonical use case - Multi-city current-conditions dashboards (call once per place) - Anchoring agent conversations to live weather context

Returns: WeatherResponse with current populated, plus location metadata, resolution source, source_url, CC-BY attribution, and server_version.

Query weather over a date range. Routes to historical archive or forecast endpoint automatically based on the date range.

Routing logic: - end_date in the past (>= 5 days ago) → historical archive (1940+) - start_date in the future → forecast (today + 16 days max) - range straddles today → forecast with past_days set

Examples: # Historical: how was Sydney summer 2020? resp = await get_weather( "sydney", start_date="2020-01-01", end_date="2020-01-31", granularity="daily", ) # → 31 DailyAggregate rows with temp_max, temp_min, precip per day

# 7-day forecast for Melbourne, hourly detail
resp = await get_weather(
    "melbourne",
    start_date="2026-05-12",
    end_date="2026-05-19",
    granularity="hourly",
)
# → 168 hourly WeatherObservation rows

# Just today (omit both dates)
resp = await get_weather("brisbane")
# → today's daily aggregate

When to use: - Time-series queries (forecast over the next week, or historical comparison) - Multi-day weather analysis - Climate research and historical look-backs (decade-scale via archive)

Returns: WeatherResponse with either daily or hourly populated depending on granularity. Period bounds populated from actual returned data.

Return current air-quality readings for any Australian location.

Sourced from Open-Meteo's air-quality API, which merges Copernicus CAMS European + global air-composition models. Returns PM2.5, PM10, ozone, nitrogen dioxide, sulphur dioxide, carbon monoxide (all µg/m³), plus the European and US AQI indices with plain-English labels.

Especially useful during AU bushfire season (Oct–Mar) when smoke can push PM2.5 above safe levels across whole regions.

Examples: # Current Sydney air quality resp = await air_quality("sydney") # resp.current.pm2_5_ugm3 == 8.8 # resp.current.european_aqi == 21 # resp.current.european_aqi_label == 'Good' # resp.current.us_aqi == 39 # resp.current.us_aqi_label == 'Good'

# Bushfire smoke check for the Blue Mountains
resp = await air_quality("-33.7,150.3")

# Brisbane CBD via postcode
resp = await air_quality("4000")

When to use: - "Is the air clean enough to go for a run in ?" - Bushfire smoke or burn-off impact checks - Asthma / allergy planning - Long-term air quality monitoring (call periodically and chart)

Returns: AirQualityResponse with current populated (pollutants + AQI scales), plus location metadata, source_url, attribution, and server_version.

Compare current weather across multiple Australian locations in one call.

Fans out concurrently via asyncio.gather, so all locations come back in roughly the time of a single call (after the cache is warm). Each location is independently resolved (curated / state / postcode / geocode / etc.) and independently fetched. If one location fails (e.g. geocoder can't find it), that row gets an error field while the rest still return.

Examples: # Capital-city dashboard resp = await compare_locations(["sydney","melbourne","brisbane","perth"]) for row in resp.locations: print(row.location_name, row.current.temperature_c)

# Tropical north today
resp = await compare_locations(["Cairns","Darwin","Townsville","Broome"])

# Mixed input shapes work
resp = await compare_locations(["sydney","NSW","2026","-33.87,151.21"])

When to use: - "Compare weather in " — the canonical use case - Build a multi-region dashboard in one tool call - Plan a holiday across regions

Returns: ComparisonResponse with one ComparisonRow per input location. Successful rows have current populated; failed rows have error.

List the 45 curated Australian location IDs supported by this MCP.

The curated set covers all 8 state/territory capitals plus 37 major regional centres. Any Australian place name outside this set still works via the place-name geocoder; the curated entries just get fast-path lookup (no network call) and appear in search_locations.

Coverage by state: - 8 capitals: sydney, melbourne, brisbane, perth, adelaide, hobart, darwin, canberra - NSW regional (10): newcastle, wollongong, tamworth, wagga_wagga, albury, orange, bathurst, dubbo, coffs_harbour, port_macquarie - VIC regional (6): geelong, ballarat, bendigo, mildura, shepparton, warrnambool - QLD regional (9): gold_coast, sunshine_coast, cairns, townsville, mackay, toowoomba, rockhampton, bundaberg, hervey_bay - WA regional (5): broome, bunbury, geraldton, albany, kalgoorlie - SA regional (2): mount_gambier, whyalla - TAS regional (3): launceston, devonport, burnie - NT regional (2): alice_springs, katherine

When to use: - You want to enumerate which locations have first-class support - You're building a UI / dashboard that needs the supported set up front - You want to plan a multi-location dashboard call

Returns: Sorted list of location IDs (currently 45). Adding a location is a YAML edit in src/au_weather_mcp/data/curated/locations.yaml.