How to harness Yahoo!’s weather API

In 2006, while working at a design agency in Cardiff, Wales, I conceived of an idea to feature on our website the current weather conditions outside our office. I wanted to make our website fully engaging and to show our visitors and clients what we were experiencing in real life each day, in real time.

After doing some extensive research, I discovered that the best starting point for this is Yahoo!’s Weather API, because it gives weather conditions in a consistent, usable format. At the time, however, the only way to really represent the weather on a website was by using Flash. The development time alone was enough to frighten the idea from the minds of the company’s directors, and it never moved past the conception stage.

Now, six years later, and being the technical director of my own company, I revisited the idea. A search around various websites, blogs and forums revealed that, even six years on, nobody has actually done anything like this, so we would have to create the code to do it. Also, in the six years since the idea was conceived, my ambitions have grown. I no longer just want the website to display the weather outside of our office—I want it to display the weather outside the window of the person viewing the website.

I created a wish list of features—containing live weather updates, sunset and sunrise times, and day and night and even moon cycles—and gave it to our developer Steven to make it so.

Once again, Yahoo’s Weather API proved to be the most consistent, offering very accurate codes for various weather types. With this information, we would be able to create an array that could control our weather display.

<yahoo-weather-codes>
 <code number="0" description="tornado"/>
 <code number="1" description="tropical storm"/>
 <code number="2" description="hurricane"/>
 <code number="3" description="severe thunderstorms"/>
 <code number="4" description="thunderstorms"/>
 <code number="5" description="mixed rain and snow"/>
 <code number="6" description="mixed rain and sleet"/>
 <code number="7" description="mixed snow and sleet"/>
 <code number="8" description="freezing drizzle"/>
 <code number="9" description="drizzle"/>
 <code number="10" description="freezing rain"/>
 <code number="11" description="showers"/>
 <code number="12" description="showers"/>
 <code number="13" description="snow flurries"/>
 <code number="14" description="light snow showers"/>
 <code number="15" description="blowing snow"/>
 <code number="16" description="snow"/>
 <code number="17" description="hail"/>
 <code number="18" description="sleet"/>
 <code number="19" description="dust"/>
 <code number="20" description="foggy"/>
 <code number="21" description="haze"/>
 <code number="22" description="smoky"/>
 <code number="23" description="blustery"/>
 <code number="24" description="windy"/>
 <code number="25" description="cold"/>
 <code number="26" description="cloudy"/>
 <code number="27" description="mostly cloudy (night)"/>
 <code number="28" description="mostly cloudy (day)"/>
 <code number="29" description="partly cloudy (night)"/>
 <code number="30" description="partly cloudy (day)"/>
 <code number="31" description="clear (night)"/>
 <code number="32" description="sunny"/>
 <code number="33" description="fair (night)"/>
 <code number="34" description="fair (day)"/>
 <code number="35" description="mixed rain and hail"/>
 <code number="36" description="hot"/>
 <code number="37" description="isolated thunderstorms"/>
 <code number="38" description="scattered thunderstorms"/>
 <code number="39" description="scattered thunderstorms"/>
 <code number="40" description="scattered showers"/>
 <code number="41" description="heavy snow"/>
 <code number="42" description="scattered snow showers"/>
 <code number="43" description="heavy snow"/>
 <code number="44" description="partly cloudy"/>
 <code number="45" description="thundershowers"/>
 <code number="46" description="snow showers"/>
 <code number="47" description="isolated thundershowers"/>
 <code number="3200" description="not available"/>
</yahoo-weather-codes>

However, as good as Yahoo’s data is, it was only as accurate as the location we were able to feed it from the website, and due to the frailties of Microsoft’s Internet Explorer, we weren’t able to use geolocation to retrieve an accurate location for everyone browsing the website. We therefore had to settle for the next best thing and use the website IPInfoDB to retrieve the nearest capital, or nearest large city, based on the IP address of the user.

Across the US, this usually results in the capital of whichever state the person looking at the website resides in. Here in the UK, it defaults to London, regardless of where in the UK the person is based; hopefully, Microsoft will one day catch up with the rest of browser world and allow us to use geolocation.

By using the IP address of the user and entering that into IPInfoDB, we were able to extrapolate the country, state or province, and the city or town of the person viewing the website. Feeding this into the Yahoo API gave us the current weather for that particular location.

The sunset and sunrise times are accurate each day and are calculated on the fly based on longitude and latitude, also derived from Yahoo’s Weather API.

Finally, there is the moon phase, which, even though it is based on just the date as a variable, proved to be the most complicated calculation of all.

Let it snow, let snow, let it snow…

That’s the theory. Now, for how it was done.

The first step was to split the weather types retrieved from Yahoo! into an array that we could use to control the effects on the website. Each of Yahoo’s 47 different weather types has its own array, which we divided into four numbers. The first set of numbers dictates the cloud coverage, ranging from a clear day to dark heavy clouds. The second number is for the rain, ranging from no rain to severe rainfall. The third number is for various additional weather types, such as snow and lightning. Finally, the fourth number is for what our designer Steven calls the “gravy effects,” such as fog, dust and mist.

$weatherarray[0]=array('tornado',3,3,5,3);
$weatherarray[1]=array('tropical storm',3,3,5,3);
$weatherarray[2]=array('hurricane',3,2,4,3);
$weatherarray[3]=array('severe thunderstorms',3,3,5,3);
$weatherarray[4]=array('thunderstorms',3,2,5,2);
$weatherarray[5]=array('mixed rain and snow',2,1,1,0);
$weatherarray[6]=array('mixed rain and sleet',2,1,1,0);
$weatherarray[7]=array('mixed snow and sleet',2,1,2,0);
$weatherarray[8]=array('freezing drizzle',1,1,1,0);
$weatherarray[9]=array('drizzle',1,1,0,0);
$weatherarray[10]=array('freezing rain',1,2,1,0);
$weatherarray[11]=array('showers',2,2,0,0);
$weatherarray[12]=array('showers',2,2,0,0);
$weatherarray[13]=array('snow flurries',1,0,2,1);
$weatherarray[14]=array('light snow showers',1,0,2,1);
$weatherarray[15]=array('blowing snow',1,0,2,2);
$weatherarray[16]=array('snow',1,0,2,0);
$weatherarray[17]=array('hail',1,0,4,0);
$weatherarray[18]=array('sleet',1,1,4,0);
$weatherarray[19]=array('dust',0,0,0,5);
$weatherarray[20]=array('foggy',0,0,0,4);
$weatherarray[21]=array('haze',0,0,0,5);
$weatherarray[22]=array('smoky',0,0,0,5);
$weatherarray[23]=array('blustery',1,0,0,2);
$weatherarray[24]=array('windy',1,0,0,2);
$weatherarray[25]=array('cold',1,0,0,0);
$weatherarray[26]=array('cloudy',2,0,0,0);
$weatherarray[27]=array('mostly cloudy (night)',1,0,0,0);
$weatherarray[28]=array('mostly cloudy (day)',1,0,0,0);
$weatherarray[29]=array('partly cloudy (night)',1,0,0,0);
$weatherarray[30]=array('partly cloudy (day)',1,0,0,0);
$weatherarray[31]=array('clear (night)',0,0,0,0);
$weatherarray[32]=array('sunny',0,0,0,0);
$weatherarray[33]=array('fair (night)',0,0,0,0);
$weatherarray[34]=array('fair (day)',0,0,0,0);
$weatherarray[35]=array('mixed rain and hail',1,1,4,1);
$weatherarray[36]=array('hot',0,0,0,0);
$weatherarray[37]=array('isolated thunderstorms',3,2,5,2);
$weatherarray[38]=array('scattered thunderstorms',3,2,5,2);
$weatherarray[39]=array('scattered thunderstorms',3,2,5,2);
$weatherarray[40]=array('scattered showers',3,2,0,2);
$weatherarray[41]=array('heavy snow',1,0,3,0);
$weatherarray[42]=array('scattered snow showers',1,0,2,0);
$weatherarray[43]=array('heavy snow',1,0,3,0);
$weatherarray[44]=array('partly cloudy',1,0,0,0);
$weatherarray[45]=array('thundershowers',3,2,5,2);
$weatherarray[46]=array('snow showers',1,0,2,0);
$weatherarray[47]=array('isolated thundershowers',3,2,5,2);
$weatherarray[3200]=array('not available',0,0,0,0);

In order to keep the already heavy code and imagery to a minimum, we chose to recycle the same images wherever possible. For example, there is only one rain graphic, and it is controlled based on the information from Yahoo!. If the rain graphic is required to be light, it is set with a lower opacity to make it lighter:

switch ( $effect1) {
 case 0:
 $weathercode.= 'jQuery('#rain').css("opacity", "0.0");';
 break;
 case 1:
 $weathercode.= 'jQuery('#rain').css("opacity", "0.10");';
 break;
 case 2:
 $weathercode.= 'jQuery('#rain').css("opacity", "0.30");';
 break;
 case 3:
 $weathercode.= 'jQuery('#rain').css("opacity", "0.50");';
 break;
}

Beware the moon

We stumbled, rather luckily, upon the calculations for the moon cycle on Stephen A. Zarkos’ blog. In keeping with our desire to keep images to a minimum, the moon phase was done with a pixel sheet showing 10 different phases of the moon. Using Zarkos’ calculations, the following code selects the correct part of the pixel sheet to display, ensuring that the correct moon cycle is always shown on our website.

background-position: <?php echo $moonbgimagepos; ?>px 0;

Watch the sunset in real time

The final part of the project, and the most visually exciting, is the real-time sunset and sunrise. As mentioned, this uses the longitude and latitude of the nearest capital city of the person viewing the website to extrapolate the sunset and sunrise times for them. This means that someone looking at the website in Los Angeles will see the sun rise and set three hours after someone looking at the same website in New York.

The sunset and sunrise consist of three separate skyline effects that dissolve into each other in sequence. For the sunset, the day scene slowly dissolves into an orange scene, before dissolving into a night scene. While this is happening, a sun graphic (which is always present above the browser fold) begins to descend and “set.” This whole process takes exactly 300 seconds.

The sunset time (derived from the longitude and latitude) is converted into a Unix timestamp, which is then stored as a variable. The current time is also turned into a Unix timestamp, and the difference between the two times is used for a jQuery timeout function. This is what creates the transition between the day and night themes.

jQuery('#daytime').fadeOut(200000, 'linear', function() {
 jQuery('#sill').fadeOut(100000, 'linear', function() {});
 jQuery('#sunset').fadeOut(100000, 'linear', function() {});
}); 

The standard weather effects, whatever they may be, continue to play out while the sun is setting and rising. This can lead to some quite beautiful transitions, especially when it’s raining very hard.

You can see the code in action on the Engage Web site.

Our forecast for tomorrow

As this is a system we have developed ourselves, we’re continually looking at ways to improve it and we have two features we looked to add since the weather system was launched in August this year.

The first is something we have just added; a cookie based location setting, whereby the visitor to the website can make their weather display more accurate by entering their town, city or zip code in order to retrieve specific weather information for their area. This was actually very easy to do as Yahoo’s weather API accepts zip codes and cities as inputs, and it saves a call to iponfodb.com. We have tested this with various cities from around the world, from as far afield as Northern Canada to the Antipodes Islands off the coast of New Zealand – so you see can what the weather is like anywhere in the world.

The second feature we’ll be introducing in the New Year is a control box so visitors can implement the weather effects as they see fit, so the combinations of different weather types can be seen regardless of the actual weather. For example, visitors will be able to increase the intensity of the rain from 0% to 100% in 10% increments. This will also include a trigger for the sunset and sunrise, so everyone can play at being Ed Harris from The Truman Show and create a sunrise whenever they like.

Have you used Yahoo!’s Weather API? What did you build with it? Let us know in the comments below.

Featured image/thumbnail, weather image via Shutterstock.

Darren Jamieson

Darren Jamieson is the technical director at Engage Web, an SEO agency based in Cheshire, UK. Darren has more than a decade of experience in the industry, having started as the web and new media designer for GAME in 2000. He's an avid Transformers fan, even having his own comic published by Metrodome, and owns several Transformers websites.