Getting started

Introduction

WeatherAPI.com provides access to weather and geo data via a JSON/XML restful API. It allows developers to create desktop, web and mobile applications using this data very easy.

We provide following data through our API:

Real-time weather
10 day weather forecast
Astronomy
Time zone
Location data
Search or Autocomplete API
NEW: Historical weather

Getting Started

You need to signup and then you can find your API key under your account, and start using API right away!

If you find any features missing or have any suggestions, please contact us.

Authentication

API access to the data is protected by an API key. If at anytime, you find the API key has become vulnerable, please regenerate the key using Regenerate button next to the API key.

Authentication to the WeatherAPI.com API is provided by passing your API key as request parameter through an API .

key parameter

key=YOUR_API_KEY

How to Build

The generated SDK relies on Node Package Manager (NPM) being available to resolve dependencies. If you don't already have NPM installed, please go ahead and follow instructions to install NPM from here. The SDK also requires Node to be installed. If Node isn't already installed, please install it from here

NPM is installed by default when Node is installed

To check if node and npm have been successfully installed, write the following commands in command prompt:

node --version
npm -version

Now use npm to resolve all dependencies by running the following command in the root directory (of the SDK folder):

npm install

This will install all dependencies in the node_modules folder.

Once dependencies are resolved, you will need to move the folder WeatherAPILib in to your node_modules folder.

How to Use

The following section explains how to use the library in a new project.

1. Open Project Folder

Open an IDE/Text Editor for JavaScript like Sublime Text. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Click on File and select Open Folder.

Select the folder of your SDK and click on Select Folder to open it up in Sublime Text. The folder will become visible in the bar on the left.

2. Creating a Test File

Now right click on the folder name and select the New File option to create a new test file. Save it as index.js Now import the generated NodeJS library using the following lines of code:

var lib = require('lib');

Save changes.

3. Running The Test File

To run the index.js file, open up the command prompt and navigate to the Path where the SDK folder resides. Type the following command to run the file:

node index.js

How to Test

These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:

Method 1 (Run all tests)

Navigate to the root directory of the SDK folder from command prompt.
Type mocha --recursive to run all the tests.

Method 2 (Run all tests)

Navigate to the ../test/Controllers/ directory from command prompt.
Type mocha * to run all the tests.

Method 3 (Run specific controller's tests)

Navigate to the ../test/Controllers/ directory from command prompt.
Type mocha Weather APIController to run all the tests in that controller file.

To increase mocha's default timeout, you can change the TEST_TIMEOUT parameter's value in TestBootstrap.js.

Initialization

Authentication

In order to setup authentication in the API client, you need the following information.

Parameter	Description
key	TODO: add a description

API client can be initialized as following:

const lib = require('lib');

// Configuration parameters and credentials
lib.Configuration.key = "key";

Class Reference

List of Controllers

APIsController

APIsController

Get singleton instance

The singleton instance of the APIsController class can be accessed from the API Client.

var controller = lib.APIsController;

getRealtimeWeather

Current weather or realtime weather API method allows a user to get up to date current weather information in json and xml. The data is returned as a Current Object.Current object contains current or realtime weather information for a given city.

function getRealtimeWeather(q, lang, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass US Zipcode, UK Postcode, Canada Postalcode, IP address, Latitude/Longitude (decimal degree) or city name. Visit request parameter section to learn more.
lang	`Optional`	Returns 'condition:text' field in API in the desired language. Visit request parameter section to check 'lang-code'.

Example Usage

    var q = 'q';
    var lang = 'lang';

    controller.getRealtimeWeather(q, lang, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

getForecastWeather

Forecast weather API method returns upto next 10 day weather forecast and weather alert as json. The data is returned as a Forecast Object.
Forecast object contains astronomy data, day weather forecast and hourly interval weather information for a given city.

function getForecastWeather(q, days, dt, unixdt, hour, lang, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass US Zipcode, UK Postcode, Canada Postalcode, IP address, Latitude/Longitude (decimal degree) or city name. Visit request parameter section to learn more.
days	`Required`	Number of days of weather forecast. Value ranges from 1 to 10
dt	`Optional`	Date should be between today and next 10 day in yyyy-MM-dd format
unixdt	`Optional`	Please either pass 'dt' or 'unixdt' and not both in same request. unixdt should be between today and next 10 day in Unix format
hour	`Optional`	Must be in 24 hour. For example 5 pm should be hour=17, 6 am as hour=6
lang	`Optional`	Returns 'condition:text' field in API in the desired language. Visit request parameter section to check 'lang-code'.

Example Usage

    var q = 'q';
    var days = 19;
    var dt = date("D M d, Y G:i");
    var unixdt = 19;
    var hour = 19;
    var lang = 'lang';

    controller.getForecastWeather(q, days, dt, unixdt, hour, lang, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

getHistoryWeather

History weather API method returns historical weather for a date on or after 1st Jan, 2015 as json. The data is returned as a Forecast Object.

function getHistoryWeather(q, dt, unixdt, endDt, unixendDt, hour, lang, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass US Zipcode, UK Postcode, Canada Postalcode, IP address, Latitude/Longitude (decimal degree) or city name. Visit request parameter section to learn more.
dt	`Required`	Date on or after 1st Jan, 2015 in yyyy-MM-dd format
unixdt	`Optional`	Please either pass 'dt' or 'unixdt' and not both in same request. unixdt should be on or after 1st Jan, 2015 in Unix format
endDt	`Optional`	Date on or after 1st Jan, 2015 in yyyy-MM-dd format'end_dt' should be greater than 'dt' parameter and difference should not be more than 30 days between the two dates.
unixendDt	`Optional`	Date on or after 1st Jan, 2015 in Unix Timestamp format unixend_dt has same restriction as 'end_dt' parameter. Please either pass 'end_dt' or 'unixend_dt' and not both in same request. e.g.: unixend_dt=1490227200
hour	`Optional`	Must be in 24 hour. For example 5 pm should be hour=17, 6 am as hour=6
lang	`Optional`	Returns 'condition:text' field in API in the desired language. Visit request parameter section to check 'lang-code'.

Example Usage

    var q = 'q';
    var dt = date("D M d, Y G:i");
    var unixdt = 19;
    var endDt = date("D M d, Y G:i");
    var unixendDt = 19;
    var hour = 19;
    var lang = 'lang';

    controller.getHistoryWeather(q, dt, unixdt, endDt, unixendDt, hour, lang, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

searchAutocompleteWeather

WeatherAPI.com Search or Autocomplete API returns matching cities and towns as an array of Location object.

function searchAutocompleteWeather(q, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass US Zipcode, UK Postcode, Canada Postalcode, IP address, Latitude/Longitude (decimal degree) or city name. Visit request parameter section to learn more.

Example Usage

    var q = 'q';

    controller.searchAutocompleteWeather(q, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

getIpLookup

IP Lookup API method allows a user to get up to date information for an IP address.

function getIpLookup(q, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass IP address.

Example Usage

    var q = 'q';

    controller.getIpLookup(q, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

getTimeZone

Return Location Object

function getTimeZone(q, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass US Zipcode, UK Postcode, Canada Postalcode, IP address, Latitude/Longitude (decimal degree) or city name. Visit request parameter section to learn more.

Example Usage

    var q = 'q';

    controller.getTimeZone(q, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

getAstronomy

Return Location and Astronomy Object

function getAstronomy(q, dt, callback)

Parameters

Parameter	Tags	Description
q	`Required`	Pass US Zipcode, UK Postcode, Canada Postalcode, IP address, Latitude/Longitude (decimal degree) or city name. Visit request parameter section to learn more.
dt	`Required`	Date on or after 1st Jan, 2015 in yyyy-MM-dd format

Example Usage

    var q = 'q';
    var dt = date("D M d, Y G:i");

    controller.getAstronomy(q, dt, function(error, response, context) {

    
    });

Errors

Error Code	Error Description
400	Error code 1003: Parameter 'q' not provided.Error code 1005: API request url is invalid.Error code 1006: No location found matching parameter 'q'Error code 9999: Internal application error.
401	Error code 1002: API key not provided.Error code 2006: API key provided is invalid
403	Error code 2007: API key has exceeded calls per month quota. Error code 2008: API key has been disabled.

Back to List of Controllers

Getting started

Introduction

Getting Started

Authentication

key parameter

How to Build

How to Use

1. Open Project Folder

2. Creating a Test File

3. Running The Test File

How to Test

Method 1 (Run all tests)

Method 2 (Run all tests)

Method 3 (Run specific controller's tests)

Initialization

Authentication

Class Reference

List of Controllers

APIsController

Get singleton instance

getRealtimeWeather

Parameters

Example Usage

Errors

getForecastWeather

Parameters

Example Usage

Errors

getHistoryWeather

Parameters

Example Usage

Errors

searchAutocompleteWeather

Parameters

Example Usage

Errors

getIpLookup

Parameters

Example Usage

Errors

getTimeZone

Parameters

Example Usage

Errors

getAstronomy

Parameters

Example Usage

Errors

About