AmbientWeather.net API Documentation
This repository holds the underlying markup for the API Official Documentation. If you see room for improvement feel free to issue a pull request.
This repo also houses the Wiki
For example, if I issue this request:
Request:
http get https://api.ambientweather.net/v1/devices/<Device MAC Address>?apiKey=<API Key>&applicationKey=<Application Key>&endDate=<unix timestamp>&limit=<n>
Response:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
...
Via: 1.1 vegur
X-Powered-By: Express
[
{
"baromabsin": 24.53,
"baromrelin": 29.73,
"dailyrainin": 0,
"date": "2018-02-09T17:10:00.000Z",
"dateutc": 1518196200000,
"dewPoint": 25.50795428285515,
"feelsLike": 27,
"hourlyrainin": 0,
"humidity": 94,
"humidityin": 27,
"lastRain": "2018-02-02T16:59:00.000Z",
"maxdailygust": 13.6,
"monthlyrainin": 0.01,
"solarradiation": 49.79,
"tempf": 27,
"tempinf": 61,
"totalrainin": 0.34,
"uv": 0,
"weeklyrainin": 0,
"winddir": 49,
"windgustmph": 2.2,
"windspeedmph": 2
},
...
]Is this something that is driven by the preferences we set up in our ambientweather.net dashboard?
I am looking at the list of possible device parameters and notice two fields, battin and battout. What are these? Are they the batteries in the outside unit and the batteries in the inside unit on the console? Most of the other fields have a sparse definition but you can tell what they are, but these are a mystery.
Hi, would be possible to add a new operation to the api to retrieve Max and Minimum daily temperatures?
I recently built a simple R package to access the Ambient Weather API. I hope you'll consider including it in the API documentation under "Helper Libraries".
Thanks!
The /devices/:macAddress endpoint returns an array of json objects that each look like this:
{
"dateutc": 1608940500000,
"tempinf": 73.8,
<...snip...>
"loc": "ambient-prod-2020-52",
"date": "2020-12-25T23:55:00.000Z"
}
The /devices end point returns an array containing objects that look like this:
[
{
"macAddress": <...snip...>
"lastData": {
"dateutc": 1609301160000,
"tempinf": 72,
<...snip...>
"lastRain": "2020-12-29T08:46:00.000Z",
"tz": "America/Los_Angeles",
"date": "2020-12-30T04:06:00.000Z"
},
"info": {
"name": "Foo",
"coords": {
"coords": {
"lon": -123.456,
"lat": 12.3456
},
"address": "Foo St",
"location": "Foo City",
"elevation": 50.000000,
"geo": {
"type": "Point",
"coordinates": [
-123.456,
12.3456
]
}
}
}
}
]
There are a few inconsistencies here and I'd love to understand them better (and maybe get them fixed, if they're oversights).
"loc": "ambient-prod-2020-52", which is included in the objects returned by /devices/:macAddress, but not in the objects returned by /devices?"tz": "America/Los_Angeles" (for example) missing from the objects returned by /devices/:macAddress? IMO it should be included in each object, since each object has a timezone.Seems that the problem returned (see #47)
The batt_lightning field seems to send 0 for GOOD battery, and 1 for BAD battery.
Also, we need to document the following:
lightning_day
lightning_distance
lightning_hour
lightning_time
I'm attempting to connect to the Realtime API in a Python package (using python-socketio). When I attempt a simple connection:
sio = socketio.AsyncClient()
await sio.connect('https://api.ambientweather.net/?api=1&applicationKey=<MY_APP_KEY>')...I get the follow stacktrace:
INFO:engineio.client:Attempting polling connection to https://api.ambientweather.net/socket.io/?api=1&applicationKey=<MY_APP_KEY>&transport=polling&EIO=3
INFO:engineio.client:Polling connection accepted with {'sid': '<GENERATED_SID>', 'upgrades': ['websocket'], 'pingInterval': 25000, 'pingTimeout': 5000}
INFO:socketio.client:Engine.IO connection established
INFO:engineio.client:Attempting WebSocket upgrade to wss://api.ambientweather.net/socket.io/?api=1&applicationKey=<MY_APP_KEY>&transport=websocket&EIO=3
DEBUG:websockets.protocol:client - state = CONNECTING
DEBUG:websockets.protocol:client - event = connection_made(<asyncio.sslproto._SSLProtocolTransport object at 0x109ef8128>)
DEBUG:websockets.protocol:client ! failing WebSocket connection in the CONNECTING state: 1006 [no reason]
DEBUG:websockets.protocol:client x closing TCP connection
DEBUG:websockets.protocol:client - event = connection_lost(None)
DEBUG:websockets.protocol:client - state = CLOSED
DEBUG:websockets.protocol:client x code = 1006, reason = [no reason]
WARNING:engineio.client:WebSocket upgrade failed: connection error
INFO:engineio.client:Sending packet PING data None
INFO:engineio.client:Sending polling GET request to https://api.ambientweather.net/socket.io/?api=1&applicationKey=<MY_APP_KEY>&transport=polling&EIO=3&sid=<GENERATED_SID>
The CONNECTING failure happens fairly immediately.
Not asking anyone to debug the Python library, per se, but I'm at a loss as to how I debug this further. 1006 isn't giving me much to work off of. Any thoughts on where I can go?
I am seeing inconsistent battery status when using the API vs. local (Meteobridge) and Dashboard polling
Summary:
All other parameters returned from the API are as expected. Is this an API issue or is the documentation correct?
Thanks in-advance.
When I do a query device data request, I also get back a "maxdailygust" value, which I don't think is in the list.
What is the meaning of each field:
dailyrainin - Daily Rain, in
24hourrainin - 24 Hour Rain, in
weeklyrainin - Weekly Rain, in
monthlyrainin - Monthly Rain, in
yearlyrainin - Yearly Rain, in
eventrainin - Event Rain, in
How is dailyrainin different from 24hourrainin? When are they reset?
Is weeklyrainin since XXX time on the previous Sunday? If so, what is that XXX time that it gets reset?
Is monthlyrainin since XXX time on the first day of the current month? If so, what is that XXX time that it gets reset?
... same for yearlyrainin ...
And... eventrainin... what does it represent? When does it get reset?
In my production data using the REST interface, using the devices/MacAddress endpoint:
Within one result set, sometimes the property LastRain (dateTime) is present for a data interval, and sometimes that field/property is completely absent.
Is this intentional, or a bug?
If it's intentional: I can code around it.... are there any other fields that are not always given?
Thanks
aioambient has traditionally used api.ambientweather.net for the REST API. This evening, I noticed that the library started returning this stacktrace:
Cannot connect to host api.ambientweather.net:443 ssl:default [nodename nor servname provided, or not known]
Should this URL no longer be used? Is dash2.ambientweather.net still the better URL to use?
Hi, apologies if this isn't the pace I should ask but I don't know where else to ask.
I am aware of the current API features and I am also aware that I can locally save data from my WS2000 station via SD card. I am wondering if there is any other way either using the API or a separate page on the Ambient Weather site that will allow me to download or query for historical/archived weather data? Obviously it is being archived to some database because you can see it all on the charts and graphs page, but I was wondering how difficult that would be able to implement into the current API if possible.
Home Assistant currently has an integration that uses the Ambient Weather REST API. In its original design, it required users to provide both an application key and an API key. Recently, when one of our users reached out to Ambient, he had this interaction:
Ambient weather does not want to provide app keys and has told me the developer of this should have hard coded the app key in to this.
I referred them to the HA documentation and the following was the response:
"Unfortunately, he is wrong. It is one app with many users, not many apps with many users. Thus, he needs to supply you with the app key unique to his application."
Although we understand the principle (the application key identifies the application and the API key identifies the user), we can't use this approach. We are an open source, GitHub-hosted project; if we hardcode an application key into our integration, it will be available for the entire world to see. Although an API key is still required to use the API, enterprising Google users could simply hunt around, find our application key, pair it with their own API key, and go to town.
Would you be willing to collaborate with us on a different authentication mechanism that accomplishes your purposes, but also adequately supports the fact that we are public and open source? Or, if a "more correct" mechanism already exists, could you point us to it?
Thanks!
I have a WS-2902D and just added a PM25 outdoor sensor.
The sensor is reporting properly on website and API, I can see the ug/m3 pollutant concentration value, however there is no AQI derived from PM25 data.
If I download the CSV, I get PM2.5 Outdoor and PM2.5 Outdoor 24 Hour Average
In the API, I receive pm25 and pm25_24h
However per documentation here, I should also be receiving aqi_pm25 and aqi_pm25_24h
Hello,
I've seen a couple of other people ask if they could have their own libraries added to the Ambient Weather API documentation over at Apiary Docs and I was wondering if it would be alright if I did the same.
I wrote a .NET 5 library for retrieving information from the Ambient Weather service, which can be found here: https://github.com/ChaseDRedmon/Cirrus
Could the library be added to the documentation with the other libraries that are listed there?
The API seems to always send batt_co2 status as "1". What does this mean? It is documented in no place I can find. Also, there are batteries in the sensing unit, do they have a status that can be sensed and reported on? It would be a big help to know these things before having to go up the tower to get the unit. Please update documentation when the interface changes.
Ambient weather devices do not seem to send this as a value to custom endpoints with the Ambient Weather API style communication. Is this field calculated server side? If so, what is the formula for calculation? Thanks!
Please document all the units of measure conversions used to display on weather consoles, for example:
Let's say I have the following configured in my ambientweathetr.net dashboard. The keys shown below are made up (obviously) for the purposes of this example.
appKey = XYZ
apiKey1 = ABC
apiKey2 = DEF
In my current environment, I have two instances of my app, one for production and one for test.
I'm seeing the following behavior.
The Test app id running with appKey and apiKey1. It is successfully receiving data events through the real-time api.
When I start the Production app with appKey and apiKey2, it starts to receive data events through its real-time api connection; however, the Test app stops receiving data events (sometimes immediately and sometimes after a few minutes). If I restart the Test app, it starts to receive data events again, but the Production app stops receiving data events.
Is this the way it's supposed to work? I thought the app key could be shared across multiple app instances. Or, does each instance of the app need to have its own api key AND app key?
When querying the API, I'm getting a tempf of 69.3, but in the console i'm getting 80. I've verified i'm calling the same device. Additionally, from time to time i get "{"error":"unknown-error"}".
How is battin reported if using a meteobridge? The API docs only specify the outside settings.
https://github.com/ambient-weather/api-docs/wiki/Device-Data-Specs
Was looking back at the API docs as I work on expanding the Rust crate for it, and I noticed that it doesn't seem like it pulled in the recent addition of the Rust crate from the GitHub repo.
Not sure if it's a mistake possibly on my end with how I added the Rust helper crate entry, or maybe it just hasn't been updated yet. Regardless, did want to report it though. If it's an error on my part, let me know and I can see about figuring out what I did wrong with the entry.
When you elect to share a dashboard publicly, you get a URL that looks like this:
https://ambientweather.net/dashboard/ID
It would really help the Home Assistant use case if that ID could somehow be returned via the API (REST or websocket). Ideally, there would also be some way to detect whether that ID was still publicly available or if it had been turned private again.
Thoughts? Doable?
aqi_pm25_in, aqi_pm25_in_24h are not listed here
both appear(?) to be ints?
The documentation says we can subscribe to several API keys at once. What happens if we send a very long list of API keys (say 500)?
Looking at the device data soecs here...
https://github.com/ambient-weather/api-docs/wiki/Device-Data-Specs
When using Gson's fromJson method to parse the device data JSON, the class fields must have the same name as the name in the JSON. In the case of 24hourrain, Java class fields cannot start with a number.
Calls to the devices endpoint are not working. This started some time on August 2.
When calling the v1 devices endpoint (https://api.ambientweather.net/v1/devices?applicationKey=XXXX&apiKey=YYYY) with valid app and api keys, I'm getting this response.
{"error":"unknown-error"}
My Java code is throwing an exception.
java.util.concurrent.ExecutionException: org.eclipse.jetty.client.HttpResponseException: HTTP protocol violation: Authentication challenge without WWW-Authenticate header
@owise1 Did something change in the API? This had been working for many months.
Also, last night around 3:15 AM EDT, the real-time API stopped sending events. This also had been working many months.
@bachya Are you seeing something similar in HA?
I was experiencing frequent failures with the homeassistant ambient_station component, so I downloaded the ambientweatheR code. It was giving me "An unexpected TLS packet was received" errors. I suspected an SSL-type problem, so I replaced https with http in the URLs, and it worked. And continues to work consistently. So I did the same with the ambient_station component, which then uses ws: instead of wss:, and it seems to be working consistently ever since. With SSL, the problem could be at my end, of course, but many homeassistant users are experiencing problems with ambient_station right now, so I'm wondering if there's an SSL certificate or similar problem on one of the Ambient Weather API servers.
Hello,
I am working on implementing a Ruby SDK for the Ambient Weather API, and I have a question about the device data model.
I was reviewing some documentation in the project wiki which indicates that some fields may not be present in the resulting JSON depending on whether a given device supports it. Would you consider returning a complete object (e.g., all possible fields that may be supported) and null out values that are not available for the given device? I wonder if it may make it easier for consumers of the API to deserialize the JSON payload into a consistent model. What are your thoughts?
Thank you.
For the past 8 to 10 weeks I get these errors:
2021-10-03 17:10:10 ERROR (MainThread) [homeassistant.components.ambient_station] packet queue is empty, aborting
2021-10-03 17:11:37 ERROR (MainThread) [homeassistant.components.ambient_station] packet queue is empty, aborting
2021-10-03 17:13:03 ERROR (MainThread) [homeassistant.components.ambient_station] packet queue is empty, aborting
2021-10-03 17:14:30 ERROR (MainThread) [homeassistant.components.ambient_station] packet queue is empty, aborting
I'm trying to use the realtime API via Socket.IO (for https://github.com/wadetregaskis/SwiftWeather) and I am able to connect but I never receive any response to anything I send. I do receive pings from the server, so something is actually active on the other end, but the "subscribe" command appears to just be silently ignored by the server…?
The documentation here in this repo isn't all that helpful since it refers specifically and exclusively to a random Node.js library, without actually documenting the protocol in any meaningful way. So I don't really know what the argument to "subscribe" is supposed to be at the Socket.IO layer let-alone the wire layer. The source of https://github.com/owise1/ambient-weather-api seems to imply that something like the string '{ "apiKeys": ["xyz"] }' should work, being the JSON serialisation of a nominal object with an apiKeys property etc. But it doesn't. Nor does any conceivable variation on serialisation format (e.g. single-quotes instead of double-quotes, no quotes, etc). Nor if I send the serialised form as a binary event. Etc.
While debugging a problem with a non-Davis weather station, I discovered that the station was posting yearly rain as "totalrainin" in the JSON instead of the documented "yearlyrainin". I also found that station also reported "weeklyrainin", "eventrainin", and ""lastRain" values.
The (likely Davis-specific) variables of "windgustdir", "winddir_avg2m", "windspdmph_avg2m", "winddir_avg10m", and "windspdmph_avg10m" were also missing from that station.
Could the docs on apiary and the GitHub docs be updated to include ALL the possible fields returned from a device query AND an indication of any variables that are only specific to a particular weather station?
Is it possible to get the battery status in the data event JSON object for the WS-1400-IP series weather stations?
{
"baromabsin": 29.73,
"baromrelin": 30.15,
"dailyrainin": 0,
"date": "2018-12-06T19:59:00.000Z",
"dateutc": 1544126340000,
"dewPoint": 22.31,
"feelsLike": 39.9,
"hourlyrainin": 0,
"humidity": 49,
"humidityin": 24,
"lastRain": "2018-12-02T10:47:00.000Z",
"macAddress": "00:0E:C6:20:0B:BF",
"maxdailygust": 12.53,
"monthlyrainin": 0.47,
"solarradiation": 81.2,
"tempf": 39.9,
"tempinf": 65.3,
"totalrainin": 14.81,
"uv": 1,
"weeklyrainin": 0.19,
"winddir": 180,
"windgustmph": 0,
"windspeedmph": 0,
"yearlyrainin": 14.81
}
Today, the API returns "hourlyrainin - Hourly Rain Rate, in/hr", i.e. the hourly rate of rain fall (c.f. https://github.com/ambient-weather/api-docs/wiki/Device-Data-Specs).
In order to construct an APRS packet with weather data, people use the 'r' rain identifier, which is defined as "last hour" or "Rain per last 60 minutes", i.e. the total rainfall in the last hour. aprs.fi properly does interpret the 'r' rain identifier as "inches during last 1 hour". To my knowledge, there is no rain identifier for the rate of rain in the last hour (c.f. http://www.aprs.org/aprs11/spec-wx.txt)
Obviously, rate and total are two different things, so in order to correctly send the "inches during last 1 hour" via APRS, the API should provide a additional "hourlyrainin" which is "inches during last 1 hour", along with the existing "hourlyrainin - Hourly Rain Rate, in/hr".
How difficult would it be to add the Lat/Lon of the given device/station? It would seem most users update this when they install their station. It would be convenient for the API to expose this and serve it back. Thoughts?
I'm implementing a service to integrate Ambient Weather into the openHAB home automation platform.
I've got it working pretty well, and I'm currently getting data events for my WS-1400-IP and the WS-8482.
However, every 3 minutes or so, I see a disconnect followed by a reconnect. I'm not sure what's causing this. To deal with it, I'm sending a subscribe command every time the reconnect happens. While not a major problem to do this, it does seem pretty inefficient.
I'm using the Java socket.io client software from here.
https://github.com/socketio/socket.io-client-java
Home Assistant users of the Ambient Weather integration are reporting that the underlying library (python-engineio, as part of aioambient) sometimes returns packet queue is empty, aborting error messages.
Some research on what this means:
So packet queue is empty, aborting is a product of the underlying python-engineio package and is triggered when empty payloads are sent and I believe when the ongoing PING / PONG between server and client is missed on the server-side.
As such, it looks like the main problem you're dealing with is the client is disconnecting because the server isn't able to PONG back to the client and the client eventually gives up and disconnects.
Not sure how to tie things together, but wanted to share in case there's something that needs tuning in the realtime API.
Hello,
I'm working on a .NET implementation of the Ambient Weather API (located here: https://github.com/ChaseDRedmon/Weathered/tree/release/Weathered.API). Right now the wrapper isn't complete or anything, but I have a couple of questions regarding the Ambient Weather API.
Most of the libraries that I see are wrappers around the endpoint itself and I wanted to try and go a little bit further and include some helper methods allowing the user to selectively query certain time ranges, querying the partial/full history of a device, getting rolling averages for metrics, etc.
One question that I have is on what date was this API created? Or what is the earliest date that any weather station began submitting information to the service? Is Ambient Weather API 5 years old? Or 10 years old?
I'm trying to implement a binary search algorithm that would find the first date that a weather station came online and began publishing data to the service, so that if a user wanted to fetch the first month of data for their weather station, they could. The API seems to be design to walk backwards from the current date to a previous date. Finding the last 6 months of data is easy to do by walking backwards each day for 6 months. But finding the first x number of months is trickier because you may not know what date the weather station began sending information.
Knowing the first date that the Ambient Weather API began collecting information from personal weather stations would help me optimize this search algorithm a little bit more.
Or, If it's not too much to ask, do you think it would be possible to add a new field to the info object of the Device Data endpoint? (This endpoint here: https://api.ambientweather.net/v1/devices?applicationKey=&apiKey= that returns the metadata for all devices listed under the API Key)
It would be neat to have a firstSeenDate field in the info object for a weather station, like below.
"info": {
"name": "My Weather Station",
"firstSeenDate": <insert first seen/event date in UTC for this respective PWS>
"coords": {
"coords": {
"lat": <Snip>,
"lon": -<Snip>
},
"address": "<Snip>",
"location": "<Snip>",
"elevation": <Snip>,
"geo": {
"type": "Point",
"coordinates": [
-0.00,
0.00
]
}
}
}
Cheers.
In the Device Data Specs we have the following that a device "might" send:
Looking at the API documentation, I don't see an example returning any of these parameters. In my case, my station (hooked up via Meteobridge) reports battery health just fine.
Does the API handle battery health yet, or is this a case where my Meteobridge isn't reporting the data to Ambient?
Thx!
Hello,
Starting today, numerous members of the Home Assistant integration started having connection issues: home-assistant/core#90181
Did something in the API change?
Sorry for opening all these issues...
Is there a comprehensive list of the station types (and associated JSON elements) supported on ambientweather.net? In my openHAB smarthome integration project, I'd like to support more stations than the two I currently own (WS-1400-IP and WS-8482).
Alternatively, is there a test API key that I could use that has a variety of stations associated with it?
Also, for the real-time API, is it possible for the subscribed JSON object to include an identifier ID of the weather station model? I would like to use this to auto-discover the different station types associated with a subscription.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.