EasyWeather

the weather engine


EasyWeather is a lightweight and versatile jQuery plugin displaying weather information for any location. Its compact size and numerous options make it perfectly suitable for providing local weather information in portals, websites, blogs and apps.

Step 1

To install EasyWeather you need to unzip the download package and then include the following scripts and stylesheet files in the head section of your page:

<head>

<!-- jQuery dependency -->
<script type="text/javascript" src="EasyWeather/scripts/jquery-1.7.2.min.js"></script>

<!-- EasyWeather files -->
<link href="EasyWeather/css/easy-weather.css" rel="stylesheet" type="text/css">
<script type="text/javascript" src="EasyWeather/scripts/easy-weather-keys.js"></script>
<script type="text/javascript" src="EasyWeather/scripts/easy-weather.js"></script>

</head>

Step 2

In the body section of your page place a div element that will contain the widget and append the javascript instruction that will generate the weather widget:

<div class="ew"></div>
<script>
	$('.ew').EasyWeather();
</script>

Check the starter page out.
You are done! :)

Step 3 - optional

If you want to take fully advantage of EasyWeather's engine capabilities, you may decide to use more than one weather service. To do so, you will need to specify a personal API key for each service you intend to use.

1. Choose and sign-up to weather services

Choose one (or more) of the following weather services and follow the sign-up process on the weather service website to obtain a personal API key:

2. Place weather services API keys

Once you obtained one or more API keys, locate the easy-weather-keys.js file and replace the text 'YOUR KEY GOES HERE' with the corresponding key:

...
var EasyWeather = { 
	Keys: {
		wwo: { key: function() { return '123ABC'; } },
		owm: { key: function() { return '456DEF'; } },
		wug: { key: function() { return 'YOUR KEY GOES HERE'; } },
		ham: { key: function() { return 'YOUR KEY GOES HERE'; }, secret_key: function() { return 'YOUR KEY GOES HERE'; } },
		ipinf: { key: function() { return 'YOUR KEY GOES HERE'; } }
	}
};
...

then remove the unused keys and make sure last item does not end with a comma ,:

...
var EasyWeather = { 
	Keys: {
		wwo: { key: function() { return '123ABC'; } },
		owm: { key: function() { return '456DEF'; } },
		ipinf: { key: function() { return '789GHI'; } }
};
...

Now the widget will be able to retrieve weather information from many weather services.

The samples page features a complete collection of widgets showing how to configure EasyWeather.

This is the list of supported weather providers:

Name Code Requires account Free plan Throttled by API Nb of forecast days Language support
Yahoo! Weather yhw no yes no 4 no
World Weather Online wwo yes yes yes 5 no
Open Weather Map owm yes yes yes 7 yes
Wunderground.com wug yes yes yes 10 no
HAMweather ham yes yes yes 10 no
Forecast.io fio yes yes (free first 1000
API calls/day)
yes 7 no

And below the list of geolocation providers:

Name Code Requires account Free plan
geoPlugin geopl No Yes
freegeoip.net fgip No Yes
Telize GeoIP tlz No Yes
ipinfo.io ipinf Yes Yes

 

EasyWeather is an amazing plugin that unifies different weather sources in one tiny widget. It currently works with 5 weather providers but it is designed to work with an unlimited number of sources. It implements a cascading fallback mechanism ensuring data is retrieved even if a provider is down or the consumer itself is throttled by a service. If the first provider fails to return the requested information, EasyWeather will contact the next one to maximise the availability of the service. EasyWeather's engine uses the same mechanism to detect users location and it currently supports 4 different geolocation services.

Below a full list of options you can use to configure this plugin:

Property Type Description Example
providerId string Set the weather data provider. It accepts one of the following values: 'yhw', 'wwo', 'owm', 'wug', 'ham' - default: 'yhw'.
var ew = $('.ew').EasyWeather({ 
	providerId: 'ham' 
});
providerSequence boolean Enable/disable the retries sequence mechanism for retrieving weather data - default: true.

Remarks
This fallback mechanism will work only if there is at least one weather API account set.

var ew = $('.ew').EasyWeather({ 
	providerSequence: false 
});
providerSequenceIds string Define the list of providers to sequentially fallback to in case of weather API call failure, default: 'yhw|wwo|owm|ham|wug'.

Remarks
If you decide to use only some of the weather API providers then it is better performance-wise to remove the unused providers.

var ew = $('.ew').EasyWeather({ 
	providerSequenceIds: 'ham|yhw|wug' 
});
geoProviderId string Set the geolocation provider. It accepts one of the following values: 'geopl', 'fgip', 'maxmd' - default: 'geopl'.
var ew = $('.ew').EasyWeather({
	geoProviderId: 'maxmd'
});
geoProviderSequence boolean Enable/disable the retries sequence mechanism for geolocating user - default: true.

Remarks
This fallback mechanism will work only if there is at least one geolocation API account set.

var ew = $('.ew').EasyWeather({
	geoProviderSequence: false
});
geoProviderSequenceIds string Define the list of geolocation providers to sequentially fallback to in case of API call failure, default: 'geopl|fgip|maxmd'.

Remarks
If you decide to use only some of the geolocation API services then it is better performance-wise to remove the unused providers.

var ew = $('.ew').EasyWeather({
	geoProviderSequenceIds: 'fgip|maxmd'
});
language string Set the language of the weather information - Default: null

Remarks
Only the Open Weather Map service supports languages: en English - en, ru Russian - ru, it Italian - it, sp Spanish - sp, ua Ukrainian - ua, de German - de, pt Portuguese - pt, ro Romanian - ro, pl Polish - pl, fi Finnish - fi, nl Dutch - nl, fr French - fr, bg Bulgarian - bg, se Swedish - se, zh_tw Chinese Traditional - zh_tw, zh_cn Chinese Simplified - zh_cn, tr Turkish - tr, cz Czech - cz,

var ew = $('.ew').EasyWeather({
	providerId: 'owm',
	language: 'sp'
});
location string Set the weather's information location. If not set the widget will auto-detect the location of the user - default: 'auto'.
var ew = $('.ew').EasyWeather({
	location: 'Manila'
});
enableGeolocation boolean Enable/disable the browser's HTML 5 geolocation feature for detecting the user's location - default: false.
var ew = $('.ew').EasyWeather({
	enableGeolocation: true
});
localStorage boolean If set true the weather information will be stored in the browser's localStorage - default: true

Remarks
If disabled the script fallbacks to a cookie based storage

var ew = $('.ew').EasyWeather({
	localStorage: false
});
cacheDuration number Set the duration of the cached information - default: 3600000 (1 hour in msecs)

Remarks
In order to reduce the API calls, the script caches the weather information locally and it will perform a call again only when the stored information has expired.

var ew = $('.ew').EasyWeather({
	cacheDuration: 1800000 //30 mins in msecs
});
weekDays array Specify the list of week days - default: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']

Remarks
Sunday must be the first day of the week as it is the first day of the days collection in javascript (0 index). forecasts must be on.

var ew = $('.ew').EasyWeather({
	forecasts: true,
	weekDays: ['Dom', 'Lun', 'Mar', 'Mer', 'Gio', 'Ven', 'Sab']
});
todayLabel string Specify the text for the 'Today' label under the weather icon - default: 'Today'
var ew = $('.ew').EasyWeather({
	todayLabel: 'Oggi'
});
orientation string Set the orientation of the widget when the forecasts are displayed - default: 'vertical'.

Remarks
Two possible values: 'vertical' and 'horizontal'. forecasts must be on.

var ew = $('.ew').EasyWeather({
	forecasts: true,
	orientation: 'horizontal'
});
template object Set the template object to be used by the script.

Remarks
The default template object contains 2 properties: current, forecast. The custom template object may override the current or forecast properties. Below a complete list of placeholders for the current condition template: {icn}, {desc}, {date}, {Condition.provider_link}, {lnkforecasts}, {temp}, {minmax}, {Condition.description}, {Condition.humidity}, {Condition.precipitation}, {Condition.wind}, {Condition.pressure}, {Condition.visibility}, {forecastsdisplay}, {forecasts}, {cssprfx}
and the placeholders for forecast template: {icn}, {icndesc}, {date}, {minmax}, {desc}, {cssprfx}

var ew = $('.ew').EasyWeather({
	template: {
		current: '<div>{temp}: {desc}</div>'
	}
});
header boolean Show/hide the header element displaying the location - default: true
var ew = $('.ew').EasyWeather({ 
	header: false
});
refreshLink boolean Show/hide the refresh button located at the bottom right corner of the widget - default: true.
var ew = $('.ew').EasyWeather({
	refreshLink: false
});
enableSearch boolean Enable/disable the custom location search - default: false

Remarks
If enabled it turns the searchBox option on.

var ew = $('.ew').EasyWeather({
	enableSearch: true
});
nbSearchResults number Specify the number of results for a searched location. The maximum number of results depends on the provider.

Remarks
enableSearch has to be true.

var ew = $('.ew').EasyWeather({
	enableSearch: true,
	nbSearchResults: 10
});
forecasts boolean Enable/disable the forecasts section - default: false
var ew = $('.ew').EasyWeather({
	forecasts: true
});
forecastsLink boolean Show/hide the forecasts link expanding/collapsing the forecasts section - default: false.

Remarks
forecasts has to be enabled.

var ew = $('.ew').EasyWeather({
	forecasts: true,
	forecastsLink: true
});
nbForecastDays number Define the number of days for the forecasts. The maximum number of days depends on the provider.

Remarks
Check the Providers list to know what is the maximum number of days for the forecasts. forecasts has to be enabled.

var ew = $('.ew').EasyWeather({
	forecasts: true,
	nbForecastDays: 5
});
tempUnit string Specify the unit, Celsius or Fahrenheit, for the temperature - default: 'C'.

Remarks
Two possible values 'C' and 'F'. showUnit has to be enabled.

var ew = $('.ew').EasyWeather({
	tempUnit: 'F'
});
showUnit boolean Show/hide the temperature unit next to the temperature - default: true
var ew = $('.ew').EasyWeather({
	showUnit: false
});
windSpeedUnit string Set the unit for the wind speed - default: 'Kmph'.

Remarks
Two possible values 'Kmph' and 'Miles'. showDetails has to be enabled.

var ew = $('.ew').EasyWeather({
	showDetails: true,
	windSpeedUnit: 'Miles'
});
showCountry boolean Display the country next to the city in the header or search text-box when location is resolved - default: true
var ew = $('.ew').EasyWeather({
	showCountry: false
});
showRegion boolean Display the region/state next to the city in the header or search text-box when location is resolved - default: false
var ew = $('.ew').EasyWeather({
	showRegion: true
});
showMinMax boolean Enable/disable the max/min temparatures for the day - default: true
var ew = $('.ew').EasyWeather({
	showMinMax: false
});
showDescription boolean Enable/disable the weather description under the current temperature (ex: 'clear sky') - default: true
var ew = $('.ew').EasyWeather({
	showDescription: false
});
showDetails boolean Enable/disable the detailed information for the current condition - default: false
var ew = $('.ew').EasyWeather({
	showDetails: true
});
details string Define the information to be displayed in the current condition details - default: 'humidity|precipitation|wind|pressure|visibility'

Remarks
The value has to be a '|' separated list and the order of the items is ignored. showDetails has to be enabled.

var ew = $('.ew').EasyWeather({
	showDetails: true,
	details: 'humidity|wind'
});
detailLabels object Specify the labels for the condition details - default:
{
	humidity: 'Humidity: ',
	precipitation: 'Precipitation: ',
	wind: 'Wind: ',
	pressure: 'Pressure: ',
	visibility: 'Visibility: '
}
var ew = $('.ew').EasyWeather({
	showDetails: true,
	details: 'humidity|wind',
	detailLabels: { 
		humidity: 'Humidité: ',
		wind: 'Vent: '
	} 
});
width string Set the widget's width (ex: '100px' or 'auto') - default: null
var ew = $('.ew').EasyWeather({
	width: '185px'
});
height string Set the widget's height (ex: '100px' or 'auto') - default: null
var ew = $('.ew').EasyWeather({
	height: '120px'
});
basePath string Define the script's base path - default: 'EasyWeather/'
var ew = $('.ew').EasyWeather({
	basePath: 'MyPath/EasyWeather/'
});
theme string Set the widget's theme - default: 'ew-light-blue'

Remarks
Available themes: ew-dark-grey, ew-yellow, ew-green, ew-purple, ew-teal, ew-skyblue, ew-orange, ew-dark-purple, ew-brown, ew-transparent.

var ew = $('.ew').EasyWeather({
	theme: 'ew-brown'
});
cssContainer string Define the CSS class applied to the element containing the whole widget - default: 'ew-container'
var ew = $('.ew').EasyWeather({
	cssContainer: 'my-css-class-here'
});
cssForm string Define the CSS class applied to the form element - default: 'ew-form'.

Remarks
Ignored if enableSearch option is off.

var ew = $('.ew').EasyWeather({
	cssForm: 'my-css-class-here'
});
cssInput string Define the CSS class applied to the serch text-box element - default: 'ew-input'.

Remarks
Ignored if enableSearch option is off.

var ew = $('.ew').EasyWeather({
	cssInput: 'my-css-class-here'
});
cssHeader string Define the CSS class applied to the header element (location label) - default: 'ew-header'.

Remarks
Depends on the header option, if enableSearch is true then it will be ignored.

var ew = $('.ew').EasyWeather({
	cssHeader: 'my-css-class-here'
});
cssContent string Define the CSS class applied to the element containing the weather information (icon + temp) - default: 'ew-content'
var ew = $('.ew').EasyWeather({
	cssContent: 'my-css-class-here'
});
Property Type Description Example
create callback Triggered after the weather widget is successfully generated in the DOM. The context within the callback is the EasyWeather instance. Initialize EasyWeather with the create callback specified:
var ew = $('.ew').EasyWeather({
	create: function() {
		console.log(this);
	}
 });
Bind an event listener to the ew.create event:
$('.ew').on('ew.create', function(e) {
	$(this).css({ border: '3px solid blue' });
});
load callback Triggered when the weather information is successfully displayed. The context within the callback is the EasyWeather instance. Initialize EasyWeather with the load callback specified:
var ew = $('.ew').EasyWeather({
	load: function() {
		console.log(this);
	}
});
Bind an event listener to the ew.load event:
$('.ew').on('ew.load', function(e, data) {
	console.log(e, data);
});
locate callback Fired when the requested location or current user's position is successfully resolved. The context within the callback is the EasyWeather instance.

Remarks
It receives a data literal object which is the location response object or the position object returned by the browser's native geolocation feature.

Initialize EasyWeather with the locate callback specified:
var ew = $('.ew').EasyWeather({
	locate: function(data) {
		console.log(data);
	}
});
Bind an event listener to the ew.locate event:
$('.ew').on('ew.locate', function(e, data) {
	console.log(e, data);
});
search callback Called after a search is completed. The context within the callback is the EasyWeather instance.

Remarks
It receives a data literal object which is the search response object.

Initialize EasyWeather with the search callback specified:
var ew = $('.ew').EasyWeather({
	search: function(data) {
		console.log(data);
	}
});
Bind an event listener to the ew.search event:
$('.ew').on('ew.search', function(e, data) {
	console.log(e, data);
});
error callback Called whenever an API call fails. The context within the callback is the EasyWeather instance. Initialize EasyWeather with the error callback specified:
var ew = $('.ew').EasyWeather({
	error: function() { 
		$(this).css({ border: '3px solid red' });
	}
});
Bind an event listener to the ew.error event:
$('.ew').on('ew.error', function(e, msg) {
	console.log(e, msg);
});
fnLocate delegate Use this delegate to resolve the user's location with an alternative service. The context within this method is the EasyWeather instance.
var ew = $('.ew').EasyWeather({
	fnLocate: function () {
		// Your logic here: AJAX call to alternative endpoint
		this.showSpinner();
    	var o = this,
    		url =  (location.protocol.indexOf('file') != -1 ? 'http:' : location.protocol) + 
    				'//j.maxmind.com/app/geoip.js',
    		loc, city, country;
 
    			$.getScript(url, function() {
		            city = geoip_city(),
		            country = geoip_country_name(),
		            loc =  city + (o.config().showCountry ? ', ' + country : '');
		            o.setLocation(loc, true);
		        });
	}	
});
fnLoad delegate Use this delegate to load weather information with your own custom logic. The context within this method is the EasyWeather instance.
var ew = $('.ew').EasyWeather({
	fnLoad: function () {
		var location = this.location;
		// Your logic here: AJAX call to alternative endpoint
	}
});
fnSearch delegate Use this delegate to perform the location search. The context within this method is the EasyWeather instance.
var ew = $('.ew').EasyWeather({
	fnSearch: function () {
		var location = this.getAskedLocation();
		// Your logic here: AJAX call to alternative endpoint
	}
});
fnSetIconUrl delegate Use this delegate to set your own weather icon URL instead of the API one. It receives the current condition object as parameter: fnSetIconUrl: function(o){}
var ew = $('.ew').EasyWeather({
	fnSetIconUrl: function(o){
		var code = o.code;
		return '/img/weather/'+ code + '.png';
	}
});
Property Type Description Example
config() method It returns the configuration object
var ew = $('.ew').EasyWeather();
console.log(ew[0].config());
provider() method It returns the current weather provider object.
var ew = $('.ew').EasyWeather();
console.log(ew[0].provider());
getWeatherProviderIds() method It returns the list of weather providers.
var ew = $('.ew').EasyWeather();
console.log(ew[0].getWeatherProviderIds());
geoProvider() method It returns the current geolocation provider.
var ew = $('.ew').EasyWeather();
console.log(ew[0].geoProvider());
getGeoProviderIds() method It returns the list of geolocation providers.
var ew = $('.ew').EasyWeather();
console.log(ew[0].getGeoProviderIds());
setWeatherProvider( id ) method It sets the supplied id as the current weather provider.

Remarks
providerSequence must be true.

var ew = $('.ew').EasyWeather();
ew[0].setWeatherProvider('wug');
setGeoProvider( id ) method It sets the supplied id as the current geolocation provider.

Remarks
geoProviderSequence must be true.

var ew = $('.ew').EasyWeather();
ew[0].setGeoProvider('maxmd');
load() method It loads the weather information and displays it.

Remarks
If the requested information is already cached and not expired yet, it will retrieve the data from the cache (localStorage or cookie).

var ew = $('.ew').EasyWeather();
ew[0].load();
locate() method It resolves the current location, displays it in the header or search text-box and finally loads the weather information.

Remarks
If the requested information is already cached and not expired yet, it will retrieve the data from the cache (localStorage or cookie).

var ew = $('.ew').EasyWeather();
ew[0].locate();
refresh( resetOriginalProvider ) method It refreshes the current geolocation and weather information and stores it in the cache again.

Remarks
If resetOriginalProvider true, it resets the original weather provider if it was previously changed.

var ew = $('.ew').EasyWeather();
ew[0].refresh();
getWeatherData() method It returns the current parsed weather object.
var ew = $('.ew').EasyWeather();
console.log(ew[0].getWeatherData());
getLocation() method It returns the current parsed location or the requested location if a location was previously specified.
var ew = $('.ew').EasyWeather();
console.log(ew[0].getLocation());
setLocation( location, loadInfo ) method It sets the supplied location and loads the weather information if loadInfo argument is true.
var ew = $('.ew').EasyWeather();
ew[0].setLocation('New York', true);
displayLocation( location ) method It displays the supplied text in the header or search text-box element.
var ew = $('.ew').EasyWeather();
ew[0].displayLocation('Hello world!');
getStoredItemName( location, isForecasts ) method It returns the name of the current stored information.

Remarks
If the optional location argument is supplied, it will return the item name for the specified location. If the isForecasts is true it returns the name of the forecasts data.

var ew = $('.ew').EasyWeather();
console.log(ew[0].getStoredItemName());
getValidStoredItem( name, requestTime ) method It returns a valid cached item, that is cached data not expired yet.

Remarks
Both name and requestTime are mandatory. requestTime is the current date time in milliseconds and it is used to compare it against the time stamp of the stored item. If the difference is greater than the cache duration, then the item is considered expired and a null value is returned by the method.

var ew = $('.ew').EasyWeather();
var name = ew[0].getStoredItemName();
var item = ew[0].getValidStoredItem(name, new Date().getTime());
console.log(item);
storeItem( name, data, timestamp ) method Stores the supplied data object in the cache (localStorage or cookie).

Remarks
name is the key of the weather data and it is mandatory. data is the weather object to be stored as a JSON string. timestamp is date time of the current data, it is optional. If not supplied in will set the current date time.

var ew = $('.ew').EasyWeather();
var name = ew[0].getStoredItemName();
var data = { data: {} };
ew[0].storeItem(name, data);
removeStoredItem( name ) method Removes from the cache the data object corresponding to the supplied name.
var ew = $('.ew').EasyWeather();
var name = ew[0].getStoredItemName();
ew[0].removeStoredItem(name);
clearCache() method It clears the cached information for the current location.
var ew = $('.ew').EasyWeather();
console.log(ew[0].clearCache());
clearAllCache() method It clears all the information cached by the app.
var ew = $('.ew').EasyWeather();
console.log(ew[0].clearAllCache());
getTemplate( type ) method It returns the HTML string of the requested template.

Remarks
type can have 2 possible values: current and forecast.

var ew = $('.ew').EasyWeather();
console.log(ew[0].getTemplate('forecast'));
getWeekDay( date ) method It returns the weekday string for a given date.

Remarks
date must be a date object. The returned day string comes from the days defined in the weekDays option.

var ew = $('.ew').EasyWeather();
console.log(ew[0].getWeekDay(new Date()));
showError( message ) method It show the error message defined by message.

Remarks
The error message replaces the whole weather content.

var ew = $('.ew').EasyWeather();
ew[0].showError('Hello world!');
showSpinner(message, container) method It shows the loader image with the supplied message.

Remarks
container is optional and it defines the jQuery element containing the spinner and the message.

var ew = $('.ew').EasyWeather();
ew[0].showSpinner('Hello world!');
cont property It references the jQuery element containing the weather information.
var ew = $('.ew').EasyWeather();
console.log(ew[0].cont);
header property It references the jQuery element containing the header content.
var ew = $('.ew').EasyWeather();
console.log(ew[0].header);