Weather Underground

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.

Latest Version: 1.0.0

Class Usage

Constructor: Wunderground(apiKey, location)

Class Methods

getLocation()

setLocation(newLocation)

getConditions(callback)

Example Code

getForecast(callback), getExtendedForecast(callback)

Example Code

getHourly(callback[, extended])

Example Code:

getYesterday(callback)

Example Code

getHistory(date, callback)

Example Code

getAstronomy(callback)

Example Code

getAlmanac(callback)

Example Code

getGeoLookup(callback)

Example Code

getCurrentHurricanes(callback)

Example Code

getTides(callback)

Example Code

Release History

License