Weather Underground is a commercial weather service that provides real-time weather information via the Internet. To use Weather Underground, you will need to create an API key here. All Weather Underground requests in this library are sent asynchronously and require a callback function to handle the requested data.
You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.
To include this library in your project, add
#require "Wunderground.class.nut:1.0.0"at the top of your agent code.
Class Usage
Constructor: Wunderground(apiKey, location)
The class’ constructor takes two required parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
| apiKey | string | N/A | A Wunderground API Key |
| location | string | N/A | A location |
The location string can take the form of any of the following:
- Country/City "Australia/Sydney"
- US State/City "CA/Los_Altos"
- Lat,Lon "37.776289,-122.395234"
- Zipcode "94022"
- Airport code "SFO"
const WUNDERGROUND_KEY = "YOUR API KEY";const LOCATION = "CA/Los_Altos";wunderground <- Wunderground(WUNDERGROUND_KEY, LOCATION);Class Methods
getLocation()
The getLocation method returns the location used for your Weather Underground requests.
setLocation(newLocation)
The setLocation() method updates the location used for all Weather Underground requests with the new location that is passed in. The newLocation parameter must use the location formatting rules found in the Class Usage section above.
getConditions(callback)
The getConditions() method sends an asynchronous request to Weather Underground’s current conditions endpoint. The callback function must include three parameters to take the request’s error status, Weather Underground’s response and Weather Underground’s current conditions data. For a full list of conditions included in the response table see Wunderground’s documentation, but for quick reference, here is an example response containing current conditions data (partial list):
{ "temp_c" : 19.1, "temp_f" : 66.3, "feelslike_c" : "19.1", "feelslike_f" : "66.3", "weather" : "Partly Cloudy", "relative_humidity" : "65%", "wind_string" : "From the NNW at 22.0 MPH Gusting to 28.0 MPH", "pressure_mb" : "1013", "pressure_in" : "29.93", "observation_epoch" : "1340843233", "local_epoch" : "1340843234", "display_location" : { "full": "San Francisco, CA" }}Example Code
wunderground.getConditions(function(err, resp, data) { if (err) { server.error(err); return; } server.log("Temp: " + data.temp_c + "°C");});getForecast(callback), getExtendedForecast(callback)
The getForecast() and getExtendedForecast() methods both send an asynchronous request to Weather Underground. getForecast() requests a three-day forecast, and getExtendedForecast() requests a ten-day forecast. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s forecast data. For a full list of fields included in the response table see Weather Underground’s documentation, but for quick reference, here is an example of returned forecast data (partial list):
{ "txt_forecast" : { "forecastday" : [ { "title" : "Tuesday", "fcttext" : "Partly cloudy in the morning, then clear. High of 68F. Breezy. Winds from the West at 10 to 25 mph.", "fcttext_metric" : "Partly cloudy in the morning, then clear. High of 20C. Windy. Winds from the West at 20 to 35 km/h." }, { ... } ] }, "simpleforecast" : { "forecastday" : [ { "date" : { "epoch" : "1340776800" }, "high" : { "fahrenheit" : "68", "celsius" : "20" }, "low" : { "fahrenheit" : "50", "celsius" : "10" }, "conditions" : "Partly Cloudy" }, { ... } ] }}Example Code
wunderground.getForecast(function(err, resp, data) { if (err) { server.error(err); return; } local forecastArray = data.txt_forecast.forecastday; foreach (forecast in forecastArray) { server.log(format("%s. %s", forecast.title, forecast.fcttext)); }});getHourly(callback[, extended])
The getHourly() method sends an asynchronous request to Weather Underground. If the optional extended parameter is set to true, a request for a ten-day hourly forecast will be sent, otherwise the default behavior is (extended set to false) to request a one-day hourly forcast. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s forecast data. For a full list of fields included in the response table see Wunderground's documentation, but for quick reference, here is an example of returned forecast data (partial list):
[ { "temp" : { "english" : "66", "metric" : "19" }, "feelslike" : { "english" : "66", "metric" : "19" }, "condition" : "Clear", "humidity" : "65", "wdir" : { "dir" : "West" }, "wspd" : { "english" : "5", "metric" : "8" }, "FCTTIME" : { "epoch" : "1341338400" } }, { ... }]Example Code:
wunderground.getHourly(function(err, resp, data) { if (err) { server.error(err); return; } foreach (item in data) { server.log(format("%s %s°C", item.condition, item.temp.metric)); }});getYesterday(callback)
The getYesterday() method sends an asynchronous request to Weather Underground. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s historic data. For a full list of fields included in the response table see Wunderground's documentation, but for quick reference, here is an example of returned historic data (partial list):
{ "observations" : [ { "tempi" : "59.0", "tempm" : "15.0", "conds" : "Overcast", "hum" : "81", "pressurei" : "29.90", "pressurem" : "1012.3", "wdire" : "WSW", "wspdi" : "5.8", "wspdm" : "9.3", "date" : { "pretty" : "12:56 AM PDT on July 02, 2012" } }, { ... } ]}Example Code
wunderground.getYesterday(function(err, resp, data) { if (err) { server.error(err); return; } foreach (item in data.observations) { server.log(format("%s %s°C on %s", item.conds, item.tempm, item.date.pretty)); }});getHistory(date, callback)
The getHistory() method sends an asynchronous request to Wunderground for the date that is passed into the date parameter. The date needs to be formated YYYYMMDD. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s historic data. For a full list of fields included in the response table see Wunderground's documentation, but for quick reference, here is an example of returned historic data (partial list):
{ "observations" : [ { "tempi" : "59.0", "tempm" : "15.0", "conds" : "Overcast", "hum" : "81", "pressurei" : "29.90", "pressurem" : "1012.3", "wdire" : "WSW", "wspdi" : "5.8", "wspdm" : "9.3", "date" : { "pretty" : "12:56 AM PDT on July 02, 2012" } }, { ... } ], "dailysummary" : [ { "meantempi" : "52", "meantempm" : "11", "humidity" : "63", "meanpressurei" : "29.88", "meanpressurem" : "1012", "meanwdire" : "ESE" , "meanwindspdi" : "7", "meanwindspdm" : "11", "precipi" : "0.27", "precipm" : "6.86", "date" : { "pretty" : "12:00 PM PDT on April 05, 2006" } } ]}Example Code
wunderground.getHistory(20150704, function(err, resp, data) { if (err) { server.error(err); return; } foreach (item in data.observations) { server.log(format("%s %s°C on %s", item.conds, item.tempm, item.date.pretty)); }});getAstronomy(callback)
The getAstronomy() method sends an asynchronous request to Weather Underground. The callback is passed three parameters (error, Wunderground's response, Wunderground's moon phase data). The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s astro data. For a full list of fields included in the response table see Wunderground’s documentation, but for quick reference, here is an example of returned astro data (partial list):
{ "percentIlluminated" : "81", "ageOfMoon" : "10", "current_time" : { "hour" : "9", "minute" : "56" }, "sunrise" : { "hour" : "7", "minute" : "01" }, "sunset" : { "hour" : "16", "minute" : "56" }}Example Code
wunderground.getAstronomy(function(err, resp, data) { if (err) { server.error(err); return; } server.log(format("Sunrise is at %s:%s", data.sunrise.hour, data.sunrise.minute)); server.log(format("Sunset is at %s:%s", data.sunset.hour, data.sunset.minute));});getAlmanac(callback)
The getAlmanac() method sends an asyncronus request to Weather Underground. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s almanac data. For a full list of fields included in the response table see Wunderground’s documentation, but for quick reference, here is an example of returned almanac data (partial list):
{ "airport_code" : "KSFO", "temp_high" : { "normal" : { "F" : "71", "C" : "22" }, "high" : { "F" : "89", "C" : "31" }, "recordyear" : "1970" }, "temp_low" : { "normal" : { "F" : "54", "C" : "12" }, "high" : { "F" : "48", "C" : "8" }, "recordyear" : "1953" }}Example Code
wunderground.getAlmanac(function(err, resp, data) { if (err) { server.error(err); return; } server.log(format("High Temperature Record is %s°C set in %s", data.temp_high.record.C, data.temp_high.recordyear)); server.log(format("Low Temperature Record is %s°C set in %s", data.temp_low.record.C, data.temp_low.recordyear));});getGeoLookup(callback)
The getGeoLookup() method sends an asynchronous request to Weather Underground. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s geolookup data. For a full list of fields included in the response table see Wunderground’s documentation, but for quick reference, here is an example of returned geolookup data (partial list):
{ "city" : "San Francisco", "state" : "CA", "country_name" : "USA", "zip" : "94101", "lat" : "37.77500916", "lon" : "-122.41825867", "nearby_weather_stations" : { "airport" : { "station" : [ { "city" : "San Francisco", "state" : "CA", "country" : "USA", "icao" : "KSFO", "lat" : "37.61999893", "lon" : "-122.37000275" }, { ... } ] }, "pws" : { "station" : [ { "neighborhood" : "SOMA - Near Van Ness", "city" :"San Francisco", "state" : "CA", "country" : "USA", "id" : "KCASANFR58", "distance_mi" : 0, "distance_km" : 0 }, { ... } ] } }}Example Code
wunderground.getGeoLookup(function(err, resp, data) { if (err) { server.error(err); return; } server.log(format("Nearby Airport Weather Stations for %s, %s are:", data.city, data.state)); foreach (airport in data.nearby_weather_stations.airport.station) { server.log(format("%s in %s, %s", airport.icao, airport.city, airport.state)); }});getCurrentHurricanes(callback)
The getCurrentHurricanes() method sends an asynchronous request to Weather Underground. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s hurricane data. For a full list of fields included in the response table see Wunderground’s documentation, but for quick reference, here is an example of returned hurricane data (partial list):
[ { "stormInfo" : { "stormName" : "Daniel", "stormName_Nice" : "Hurricane Daniel", "stormNumber" : "ep201204" }, "Current" : { "SaffirSimpsonCategory" : 1, "Category" : "Hurricane", "lat" : 15.4, "lon" : -130.7, "WindSpeed" : { "Mph" : 75, "Kph" : 120 }, "WindGust" : { "Mph" : 90, "Kph" : 120 }, "Fspeed" : { "Mph" : 16, "Kph" : 25 }, "Movement" : { "Text" : "W", "Degrees" : "275" }, "Time" : { "epoch" : "1341867600" } }, "forecast" : [ { "ForecastHour" : "12H", "SaffirSimpsonCategory" : 0, "Category" : "Tropical Strom", "lat" : 15.5, "lon" : -133.0, "WindSpeed" : { "Mph" : 65, "Kph" : 100 }, "Time" : { "epoch" : "1341900000" } }, { ... } ], "ExtendedForecast" : [ { "ForecastHour" : "4DAY", "SaffirSimpsonCategory" : 0, "Category" : "Tropical Strom", "lat" : 15.8, "lon" : 139.3, "WindSpeed" : { "Mph" : 65, "Kph" : 25 }, "Time" : { "epoch" : "1342159200" } }, { ... } ], "track" : [ { "SaffirSimpsonCategory" : 1, "Category" : "Hurricane", "lat" : 15.2, "lon" : -129.4, "WindSpeed" : { "Mph" : 75, "Kph" : 120 }, "Time" : { "epoch" : "1341835200" } }, { ... } ], }, { ... } ]Example Code
wunderground.getCurrentHurricanes(function(err, resp, data) { if (err) { server.error(err); return; } foreach (storm in data) { server.log("Name: " + storm.stormInfo.stormName); server.log(format("Current Category: %i %s", storm.Current.SaffirSimpsonCategory, storm.Current.Category)); }});getTides(callback)
The getTides() method sends an asynchronous request to Weather Underground. The callback function must include three parameters: error state, Weather Underground’s response and Weather Underground’s tide data. For a full list of fields included in the response table see Wunderground’s documentation, but for quick reference, here is an example of returned tide data (partial list):
{ "tideInfo" : [ { "tideSite" : "Newport Beach, Newport Bay Entrance, Corona del Mar, California", "lat" : "33.6033", "lon" : "-117.883" }, { ... } ], "tideSummary" : [ { "date" : { "epoch" : "1341579657" }, "data" : { "height" : "-0.79 ft", "type" : "Low Tide" } }, { ... } ], "tideSummaryStats" : [ { "maxheight" : 6.870000, "minheight" : -1.450000 }, { ... } ]}Example Code
wunderground.getTides(function(err, resp, d) { if (err) { server.error(err); return; } foreach (item in d.tideInfo) { server.log(format("Tide Summary for %s:", item.tideSite)); } foreach(summary in d.tideSummary) { server.log(format("Tide type: %s, Tide height: %s", summary.data.type , summary.data.height)); }});Release History
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
License
Wunderground is licensed under MIT License.
