# OpenWeatherMap Tool Node

> Agent tool for fetching current weather or 5-day/3-hour forecast from OpenWeatherMap

**URL:** https://caywork.com/learn/docs/node/openweathermap-tool-node

## Content

This node exposes a single tool that queries OpenWeatherMap endpoints ("weather" for current conditions and "forecast" for 5 day / 3 hour forecasts).

### Actions

- **Builds request** to OpenWeatherMap base URL with params: appid (from secure store), units, lang, and either q (city) or lat & lon.
- **Parses JSON** response and returns it on success.
- **Handles errors** by returning structured error objects containing an error message and optional status or details.

### Inputs (fields)

- city: optional string — City name (e.g., "London"). Either city or lat/lon required.
- lat: optional float — Latitude for coordinate-based lookup.
- lon: optional float — Longitude for coordinate-based lookup.
- units: string (default "metric") — Units: "metric", "imperial", or "standard".
- endpoint: string (default "weather") — OpenWeatherMap endpoint: "weather" (current) or "forecast" (5 day / 3 hour).
- lang: string (default "en") — Language code for descriptions (e.g., "en").
- timeout: int (default 10) — HTTP request timeout in seconds.

### Outputs

- Returns parsed OpenWeatherMap JSON response on success.
- On failure returns a dict with an "error" key and additional fields like "status_code" or "details" when available.

### Behavior and Constraints

- **Coordinate precedence:** when lat and lon are provided they take precedence over city.
- **Endpoint validation:** only "weather" and "forecast" are accepted.
- **JSON parsing:** attempts to decode JSON and returns a descriptive error if decoding fails.

### Error Handling

- Invalid endpoint or missing location parameters return structured error objects.
- Failure to retrieve the API key returns a clear error.
- Non-200 responses from the API are returned as structured errors including status code and response body where available.
- Network or request exceptions return an error with details.