soplakanets / node-forecastio

A node.js client for Forecast.io API

forecastio

A node.js client library for Forecast.io API.

For explanation and more detailed info about endpoints and response format see Forecast.IO API documentation

Installation

npm install forecastio

Usage

Say you need a forecast for London, UK:

var ForecastIo = require('forecastio');

var forecastIo = new ForecastIo('<apiKey>');
forecastIo.forecast('51.506', '-0.127').then(function(data) {
  console.log(JSON.stringify(data, null, 2));
});

"Time Machine" Requests

Forecast.io also supports Time Machine requests. Quoting official documentation you can make request for "60 years in the past to 10 years in the future" for "many places". Example:

// What was the weather like in London on January 1st 2008?
forecastIo.timeMachine('51.506', '-0.127', '2008-01-01T00:00:01Z').then(function(data) {
  console.log(JSON.stringify(data, null, 2));
});

API Options

Both #forecast() and #timeMachine() methods support passing additional options. Below are some examples, for all options consult Options section of Forecast.IO API documentation.

Example of requesting ad forecast in Si(metric) units with only 'daily' fields:

var options = {
  units: 'si',
  exclude: 'currently,hourly,flags'
};
forecastIo.forecast('49.844', '24.028', options).then(function(data) {
  console.log(JSON.stringify(data, null, 2));
});

Another example, a "Time Machine" request in UK units and localized in Italian:

var options = {
  units: 'uk',
  lang:  'it'
};
forecastIo.timeMachine('49.844', '24.028', '2008-01-01T00:00:01Z', options).then(function(data) {
  console.log(JSON.stringify(data, null, 2));
});

Request Timeout

To set timeout for requests pass a timeout option to constructor, example:

var forecastIo = new ForecastIo('<apiKey>', {timeout: 30*1000});

As a result all API request made with with this forecastIo instance will have a timeout of 30 seconds.

Timeout option accepts time in milliseconds. If request will not finish in time - a callback will be fired with a timeout error.

TODO

• Logging (for debugging at least)
• Smarter API methods (accept Date object in #timeMachine() and convert it to string, for example)

Contributing

• Fork the repo & commit changes

• Make sure tests are not failing:

  $ env FORECASTIO_API_KEY=your_api_key npm test

• Create a pull request

Changelog

2.0.0

• Dropped support for node < 4.x
• Fixed deprecation warnings for dependencies.

1.0.2

• Fixed deprecation warnings.

1.0.0

• Promises (For compatibility callbacks are still supported).

0.2.0

• Added timeout option

0.1.2

• More informative error messages.

node-forecastio's Issues

Add an "include" option to optional options

As a convenience it would be nice to have an "include" option rather than just "exclude"

Accepting Date

Thanks for the library.
myDate.toISOString().replace(/00.000Z/g, '01Z') works for passing JS Date Object to timeMachine. (By some reason forecast.io doesn't like 00.000Z second format and it took me a good amount of time to figure it out). Happy to submit PR.