README.md

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.