Totami.forecast NPM

#Totami Forecast

The Totami Forecast is a module to make multiple calls to multiple API (http://www.geonames.org/ and http://forecast.io/) with a single call. It also keep certain API call in cache to reduce latency and external API calls.

##How to use it

1 - Create http://www.geonames.org/ and http://forecast.io/ accounts or use your existing http://www.geonames.org/ username and http://forecast.io/ API key.

2 - Install and save it to your project

npm install totami.forecast --save

3 - Set it

var settings = {
	"username": "myGeonamesUsername",
	"key": "myForecastIOapiKey"
};

var Forecast = require('totami.forecast');
var forecast = Forecast(settings);

4 - Make a call

var parameters = {
	"lat": 46.004342,
	"lng": -73.856989
};

forecast(parameters).then(function (result) {
	// Do what you need with the result
}, function (err) {
	// Handle the error
});

##Settings

###key String, Required The http://forecast.io/ API key.

###username String, Required The http://www.geonames.org/ username.

###cache Number, Default = 1800000 In milliseconds, the max age API calls are cached.

###radius Number, Default = 0 Radius to the closest less populated place (0) to the closest more populated place (3). To reduce the external API calls but loose in forecast precision, use the highest value. Possible values are 0, 1 , 2 , 3.

###lang String, Default = "en" Return the result strings in the desired language. Possible values are en (english), fr (french).

###units String, Default = "metric" Return the result units using the specified unit system. Possible values are metric, imperial.

###before Number, Default = 0 Number of day(s) before the specified date of the request to return in the result. These days are returned into the daily property of the result.

###beforeLimit Number, Default = 30 The limit of days the before parameter property can be. If the before parameter property exceed this limit, is value is equal to the beforeLimit property.

###after Number, Default = 7 Number of day(s) after the specified date of the request to return in the result. These days are returned into the daily property of the result.

###afterLimit Number, Default = 30 The limit of days the after parameter property can be. If the after parameter property exceed this limit, is value is equal to the afterLimit property.

##Parameters

###lat Number, Required The latitude of the requested location.

###lng Number, Required The longitude of the requested location.

###lang String, Default = Settings property value Same as the lang property in the settings. If specified, overwrite the settings property value for this call.

###radius Number, Default = Settings property value Same as the radius property in the settings. If specified, overwrite the settings property value for this call.

###date String, Default = "now" Request the forecast for an arbitrary point in the time. Should be a string equal to now (which refer to the present moment in the timezone 0) or a string formatted as follows [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS] (with an optional time zone formatted as Z for GMT time or {+,-}[HH][MM] for an offset in minutes or seconds). For the latter format, if no timezone is present, local time (at the provided latitude and longitude) is assumed. (This string format is a subset of ISO 8601 time. An as example, 2013-05-06T12:53:45 or 2013-05-06T12:53:45-0400.)

###units String, Default = Settings property value Same as the units property in the settings. If specified, overwrite the settings property value for this call.

###before

Number, Default = Settings property value Same as the before property in the settings. If specified, overwrite the settings property value for this call.

###after Number, Default = Settings property value Same as the after property in the settings. If specified, overwrite the settings property value for this call.

##Result

###JSON structure

{
	"location" : Location data point,
	"currently" : Forecast data point,
	"hourly" : {
		1367812800: Forecast data point,
		1367816400: Forecast data point,
		1367820000: Forecast data point,
		... for 24 hours.
	},
	"daily" : {
		1367640000: Forecast data point,
		1367726400: Forecast data point,
		1367812800: Forecast data point,
		... to cover the specified number of days according to the "before" and "after" properties
	}
}

###location property A Location data point of the place closest to the specified latitude and longitude. Remember this place can be different depending of the radius value.

###currently property A Forecast data point containing the current weather conditions at the requested location and the requested date.

###hourly property An object of UNIX time labels containing a Forecast data point of the weather conditions hour-by-hour for the current day (from 00:00:00 to 23:00:00).

###daily property An object of UNIX time labels containing a Forecast data point of the weather conditions day-by-day covering from the days before to the days after the requested date including the requested date.

For example, if the date requested is equal to 2013-05-06T12:00:00-0400, the days before is equal to 2 and the days after is equal to 3, the daily property will contain Forecast data point for the following days. 1367640000, 1367726400, 1367812800, 1367899200, 1367985600 and 1368072000.

###Location data point

####lat Latitude of the closest place according to the radius.

Example: 45.97809.

####lng Longitude of the closest place according to the radius.

Example: -73.89376.

####countryName i18n The name of the country in which the place is.

Example: Canada.

####countryCode The ISO 3166-2 code of the country.

Example: CA.

####distance Units = Kilometers | Miles The distance between the requested location and the closest location.

Example: 4.07785.

####name i18n The name of the place.

Example: Lac-Cristal.

####toponymName The canonical name of the place.

Example: Lac-Cristal.

####adminName i18n The administrative name (state, province, region) of the place.

Example: Quebec.

####timezone TZ identifier of the place.

Example: America/Montreal.

####offset The GMT offset of the place at the requested date.

Example: -4

###Forecast data point

####time The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) at which this forecast data point occurs.

Example: 1367812800

####icon A machine-readable text summary of this forecast data point, suitable for selecting an icon for display. If defined, this property will have one of the following values: clear-day, clear-night, rain, snow, sleet, wind, fog, cloudy, partly-cloudy-day, partly-cloudy-night, hail, thunderstorm, tornado.

Example: partly-cloudy-day

####summary i18n A human-readable text summary of this forecast data point, based on the icon value.

Example: Ciel partiellement nuageux

####sunriseTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the sunrise time.

Example: 1367832957

####sunsetTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the sunset time.

Example: 1367885291

####moonPhase Only in daily A number representing the fractional part of the lunation number of the given day. This can be thought of as the “percentage complete” of the current lunar month: a value of 0 represents a new moon, a value of 0.25 represents a first quarter moon, a value of 0.5 represents a full moon, and a value of 0.75 represents a last quarter moon. (The ranges in between these represent waxing crescent, waxing gibbous, waning gibbous, and waning crescent moons, respectively.)

Example: 0.25

####nearestStormDistance Only in currently, Units = Kilometers | Miles A numerical value representing the distance to the nearest storm. This value is very approximate and should not be used in scenarios requiring accurate results. In particular, a storm distance of zero doesn’t necessarily refer to a storm at the requested location, but rather a storm in the vicinity of that location.

Example: 8.03725

####nearestStormBearing Only in currently A numerical value representing the direction of the nearest storm in degrees, with true north at 0° and progressing clockwise. If nearestStormDistance is zero, then this value will not be defined. The caveats that apply to nearestStormDistance also apply to this value.

Example: 27

####precipIntensity Units = Millimeters/Hour | Inches/Hour A numerical value representing the average expected intensity of precipitation occurring at the given time conditional on probability (that is, assuming any precipitation occurs at all).

Example: 0.017

####precipIntensityMax Only in daily, Units = Millimeters/Hour | Inches/Hour A numerical value representing the maximum expected intensity of precipitation on the given day.

Example: 1.2471

####precipIntensityMaxTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the time at which precipIntensityMax occurs.

Example: 1367834400

####precipProbability A numerical value between 0 and 1 (inclusive) representing the probability of precipitation occuring at the given time.

Example: 0.4

####precipType A string representing the type of precipitation occurring at the given time. If defined, this property will have one of the following values: rain, snow, sleet (which applies to each of freezing rain, ice pellets, and “wintery mix”), or hail. If precipIntensity is zero, then this property will not be defined.

Example: snow

####precipAccumulation Only in daily, Units = Centimeters | Inches The amount of snowfall accumulation expected to occur on the given day. If no accumulation is expected, this property will not be defined.

Example: 1,02

####temperature Only in currently and hourly, Units = Celsius | Fahrenheit A numerical value representing the temperature at the given time in degrees.

Example: 12.93

####temperatureMin Only in daily, Units = Celsius | Fahrenheit A numerical value representing the minimum temperature on the given day in degrees.

Example: 12.34

####temperatureMinTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the time at which temperatureMin occurs.

Example: 1367834400

####temperatureMax Only in daily, Units = Celsius | Fahrenheit A numerical value representing the maximum temperature on the given day in degrees.

Example: 18.03

####temperatureMaxTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the time at which temperatureMinTime occurs.

Example: 1367874000

####apparentTemperature Only in currently and hourly, Units = Celsius | Fahrenheit A numerical value representing the apparent (or “feels like”) temperature at the given time in degrees.

Example: 18.03

####apparentTemperatureMin Only in daily, Units = Celsius | Fahrenheit A numerical value representing the minimum apparent (or “feels like”) temperature on the given day in degrees.

Example: 12.34

####apparentTemperatureMinTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the time at which apparentTemperatureMin occurs.

Example: 1367834400

####apparentTemperatureMax Only in daily, Units = Celsius | Fahrenheit A numerical value representing the maximum apparent (or “feels like”) temperature on the given day in degrees.

Example: 18.03

####apparentTemperatureMaxTime Only in daily The UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) representing the time at which apparentTemperatureMax occurs.

Example: 1367874000

####dewPoint Units = Celsius | Fahrenheit A numerical value representing the dew point at the given time in degrees.

Example: 8.39

####windSpeed Units = Kilometers/Hour | Miles/Hour A numerical value representing the wind speed.

Example: 1.56

####windBearing A numerical value representing the direction that the wind is coming from in degrees, with true north at 0° and progressing clockwise. If windSpeed is zero, then this value will not be defined.

Example: 22

####cloudCover A numerical value between 0 and 1 (inclusive) representing the percentage of sky occluded by clouds. A value of 0 corresponds to clear sky, 0.4 to scattered clouds, 0.75 to broken cloud cover, and 1 to completely overcast skies.

Example: 0.55

####humidity A numerical value between 0 and 1 (inclusive) representing the relative humidity.

Example: 0.93

####visibility Units = Kilometers | Miles A numerical value representing the average visibility. Capped at 10 miles or 16 kilometers.

Example: 13.37

####ozone A numerical value representing the columnar density of total atmospheric ozone at the given time in Dobson units.

Example: 324.62

##Error

ECMAScript Error Object with error message and code properties.

forecast(parameters).then(function (result) {
    // Do what you need with the result
}, function (err) {
	console.log(err.code, err.message);
	// 1000 My error message
});

###Error codes

1000 : This code can have multiple messages and reasons. It appears when an unknown internal error occur

1001 : "You must set 'username' and 'key' in the Forecast settings"

1002 : "You must set 'username' in the Forecast settings"

1003 : "You must set 'key' in the Forecast settings"

1004 : "You must specify 'lat' (latitude) and 'lng' (longitude) in the URL parameters"

1005 : "You must specify 'lat' (latitude) in the URL parameters"

1006 : "You must specify 'lng' (longitude) in the URL parameters"

1007 : "URL parameters 'lat' (latitude) and 'lng' (longitude) must be numbers"

1008 : "URL parameter 'lat' (latitude) must be a number"

1009 : "URL parameter 'lng' (longitude) must be a number"

1010 : "Error with forecast.io service. You must specify a 'key' (API Key) in the URL"

1011 : "Error with forecast.io service. You must specify a 'lat' (latitude) and a 'lng' (longitude) in the URL"

1012 : "Error with forecast.io service. You must specify a 'lat' (latitude) in the URL"

1013 : "Error with forecast.io service. You must specify a 'lng' (longitude) in the URL"

1014 : "Error with forecast.io service. The service did not respond"

1015 : "Error with forecast.io service. The JSON response is not well-formed"

1016 : "Error with forecast.io service. The JSON response doesn't meet the standards"

1017 : "Error with geonames.org service. You must specify a 'username' in the URL"

1018 : "Error with geonames.org service. You must specify a 'lat' (latitude) and a 'lng' (longitude) in the URL"

1019 : "Error with geonames.org service. You must specify a 'lat' (latitude) in the URL"

1020 : "Error with geonames.org service. You must specify a 'lng' (longitude) in the URL"

1021 : "Error with geonames.org service. The service did not respond."

1022 : "Error with geonames.org service. The JSON response is not well-formed"

1023 : "Error with geonames.org service. The JSON response doesn't meet the standards"

Licence

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

lodash memoizee moment node-units q request utils-merge

9 years ago

10 years ago

10 years ago

10 years ago