canonical: https://jentic.com/apis/ambientweather.com/ambientweather # Ambient Weather API The Ambient Weather API exposes data from personal weather stations connected to the Ambient Weather network. Two GET endpoints let an integration list the stations linked to an account and pull historical or near-real-time observations from a specific station by MAC address. Authentication uses paired query-string keys (applicationKey identifying the integration plus apiKey identifying the user) sent against rt.ambientweather.net/v1. Typical consumers are home-automation dashboards, hyperlocal weather services, and research projects that piggyback on the network's hardware. ## For AI agents Lets agents list a user's Ambient Weather stations and pull historical readings (temperature, wind, rain, humidity, UV) from a specific station by MAC address using paired applicationKey and apiKey query parameters. ## Scope Does not handle weather forecasts, severe-weather alerts, or non-Ambient hardware - use for personal Ambient Weather station observations only. ## Capabilities - List every Ambient Weather station registered to a user account along with its MAC address and metadata - Pull historical observations from a single station identified by MAC address over a chosen end-date window - Aggregate readings across multiple personal stations belonging to the same account - Surface station telemetry (indoor and outdoor temperature, humidity, wind speed, gust, rain, UV, solar radiation) into a dashboard - Drive home-automation rules from station-reported wind, rain, and temperature observations ## Use cases ### Hyperlocal Weather Dashboard Owners of Ambient Weather stations can build a personal dashboard that polls GET /devices for their station list, then iterates through GET /devices/{macAddress} to chart temperature, humidity, wind, and rain over the last day. The two-call flow keeps the integration trivial - each call needs only the paired applicationKey and apiKey. Most home dashboards are wired in within an afternoon. Example prompt: Call GET /devices to list stations, then call GET /devices/{macAddress} for the first station and return the latest tempf and humidity values ### Hyperlocal Forecast Augmentation Hyperlocal weather services and research projects can supplement model forecasts with ground-truth observations from Ambient Weather's network of personal stations. A single GET /devices/{macAddress} call returns the station's recent observation history, which the service can ingest alongside other sensor feeds to refine micro-climate predictions for a neighbourhood or property. Example prompt: Call GET /devices/{macAddress} with endDate set to the current ISO timestamp and return the last 12 observation records ### Smart-Home Irrigation and Outdoor Automations Smart-home platforms can use a backyard Ambient Weather station to skip a sprinkler cycle when rain has already fallen or to retract awnings when wind picks up. The agent polls the device endpoint at a fixed interval, reads the rain and windgustmph fields, and triggers the right home rule. The two-endpoint surface keeps the polling loop simple. Example prompt: Poll GET /devices/{macAddress} every 10 minutes and trigger an irrigation skip rule when the dailyrainin value is greater than 0.25 ### AI Agent Weather Sensor Lookups Smart-home or operations agents can query Ambient Weather through Jentic without storing the user's apiKey or the integration's applicationKey. The agent searches Jentic for a station-data intent, loads the operation schema, and Jentic injects both keys at execution time. Useful when the same agent already calls calendar, climate-control, or notification APIs. Example prompt: Search Jentic for 'list my Ambient Weather stations', execute the operation backed by GET /devices, and return the macAddress for the station named 'Backyard' ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /devices | List all stations on the user's account | | GET | /devices/{macAddress} | Get historical observations for a specific station | ## Key resources - **Devices** — List a user's stations and fetch observation history for a specific station MAC address ## Why Jentic - **Setup:** Wiring the Ambient Weather API by hand means passing both the applicationKey and apiKey on every request and respecting its per-key rate limits yourself. Through Jentic you install once, import Ambient Weather from the API Directory, store the key pair once, and your agent calls it. - **Permission scoping:** Ambient Weather puts the device id in the URL path (/devices/{macAddress}), so a rule can pin your agent to one station: it can read observations for that device and nothing else. You choose the operations it may call, so the full device list is not included unless you add it. - **Credential handling:** Your Ambient Weather applicationKey and apiKey are stored once, encrypted, by your own Jentic One instance and injected at execution time. Neither key enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list my weather stations' or 'get station observations', and Jentic returns the matching Ambient Weather operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **OpenWeatherMap** — Model-based current and forecast weather without requiring a personal station - **WeatherAPI** — Global current, forecast, and historical weather from model and station blends - **Weatherbit** — Forecast and air-quality data to pair with on-site station observations - **Visual Crossing Weather** — Long-range historical and forecast weather to extend a station's short observation window ## FAQ ### What authentication does the Ambient Weather API use? Ambient Weather uses a paired-key scheme: applicationKey (issued to the integration) and apiKey (issued to the end user) both sent as query parameters on every request. There is no OAuth flow. Through Jentic, both keys are stored encrypted in the vault and injected at execution time, so the agent never sees them. ### Can I list all the weather stations on my account? Yes. GET /devices returns the array of stations linked to the apiKey, including each station's MAC address, info block, and the latest observations. Use that MAC address to call GET /devices/{macAddress} for historical detail. ### What are the rate limits for the Ambient Weather API? Ambient Weather caps at 1 request per second per applicationKey and apiKey pair. Bursts above that return HTTP 429. Plan polling intervals around this - most home dashboards poll every 30-60 seconds, well under the limit. ### How do I get a station's recent observations through Jentic? Search Jentic for 'get Ambient Weather station observations'. Jentic returns the operation backed by GET /devices/{macAddress}, you load the schema (the only required input is the macAddress), and execute. Jentic injects the applicationKey and apiKey from the vault. Run it through Jentic One, the self-hosted execution layer. ### How far back does the historical observation window go? GET /devices/{macAddress} accepts an endDate parameter and returns up to 288 records ending at that timestamp (one record every 5 minutes, ~24 hours). To pull older history, page backwards by setting endDate to the earliest timestamp from the previous call. ### Does the Ambient Weather API include weather forecasts? No. This API exposes observations from personal weather stations only - there is no forecast endpoint. Pair it with a forecast provider (OpenWeatherMap, WeatherAPI) when you need predictions alongside ground-truth station data. ### Can I limit what my agent is allowed to do with the Ambient Weather API? Yes. Because you run Jentic One yourself, your own rules decide which Ambient Weather operations your agent may call and which credentials it may use. Since the device id sits in the URL path (GET /devices/{macAddress}), you can pin the agent to a single station so it reads observations for that MAC address and nothing else. You also choose whether to expose the station-listing call (GET /devices), so the full account device list stays out of reach unless you add it.