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 code has dependencies over external libraries like UniRest. These dependencies are defined in the composer.json file that comes with the SDK. To resolve these dependencies, we use the Composer package manager which requires PHP greater than 5.3.2 installed in your system. Visit https://getcomposer.org/download/ to download the installer file for Composer and run it in your system. Open command prompt and type composer --version. This should display the current version of the Composer installed if the installation was successful.

Using command line, navigate to the directory containing the generated files (including composer.json) for the SDK.
Run the command composer install. This should install all the required dependencies and create the vendor directory in your project directory.

[For Windows Users Only] Configuring CURL Certificate Path in php.ini

CURL used to include a list of accepted CAs, but no longer bundles ANY CA certs. So by default it will reject all SSL certificates as unverifiable. You will have to get your CA's cert and point curl at it. The steps are as follows:

Download the certificate bundle (.pem file) from https://curl.haxx.se/docs/caextract.html on to your system.
Add curl.cainfo = "PATH_TO/cacert.pem" to your php.ini file located in your php installation. “PATH_TO” must be an absolute path containing the .pem file.

[curl]
; A default value for the CURLOPT_CAINFO option. This is required to be an
; absolute path.
;curl.cainfo =

How to Use

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

1. Open Project in an IDE

Open an IDE for PHP like PhpStorm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Click on Open in PhpStorm to browse to your generated SDK directory and then click OK.

2. Add a new Test Project

Create a new directory by right clicking on the solution name as shown below:

Name the directory as "test"

Add a PHP file to this project

Name it "testSDK"

Depending on your project setup, you might need to include composer's autoloader in your PHP code to enable auto loading of classes.

require_once "../vendor/autoload.php";

It is important that the path inside require_once correctly points to the file autoload.php inside the vendor directory created during dependency installations.

After this you can add code to initialize the client library and acquire the instance of a Controller class. Sample code to initialize the client library and using controller methods is given in the subsequent sections.

3. Run the Test Project

To run your project you must set the Interpreter for your project. Interpreter is the PHP engine installed on your computer.

Open Settings from File menu.

Select PHP from within Languages & Frameworks

Browse for Interpreters near the Interpreter option and choose your interpreter.

Once the interpreter is selected, click OK

To run your project, right click on your PHP file inside your Test project and click on Run

How to Test

Unit tests in this SDK can be run using PHPUnit.

First install the dependencies using composer including the require-dev dependencies.
Run vendor\bin\phpunit --verbose from commandline to execute tests. If you have installed PHPUnit globally, run tests using phpunit --verbose instead.

You can change the PHPUnit test configuration in the phpunit.xml file.

Initialization

Authentication

In order to setup authentication and initialization of the API client, you need the following information.

Parameter	Description
key	TODO: add a description

API client can be initialized as following.

$key = 'key';

$client = new WeatherAPILib\WeatherAPIClient($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.

$aPIs = $client->getAPIs();

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 = null)

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

$q = 'q';
$lang = 'lang';

$result = $aPIs->getRealtimeWeather($q, $lang);

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 = null,
        $unixdt = null,
        $hour = null,
        $lang = null)

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

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

$result = $aPIs->getForecastWeather($q, $days, $dt, $unixdt, $hour, $lang);

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 = null,
        $endDt = null,
        $unixendDt = null,
        $hour = null,
        $lang = null)

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

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

$result = $aPIs->getHistoryWeather($q, $dt, $unixdt, $endDt, $unixendDt, $hour, $lang);

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)

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

$q = 'q';

$result = $aPIs->searchAutocompleteWeather($q);

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)

Parameters

Parameter	Tags	Description
q	`Required`	Pass IP address.

Example Usage

$q = 'q';

$result = $aPIs->getIpLookup($q);

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)

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

$q = 'q';

$result = $aPIs->getTimeZone($q);

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)

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

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

$result = $aPIs->getAstronomy($q, $dt);

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

mikemcmullan/weatherapi-PHP

Getting started

Introduction

Getting Started

Authentication

key parameter

How to Build

[For Windows Users Only] Configuring CURL Certificate Path in php.ini

How to Use

1. Open Project in an IDE

2. Add a new Test Project

3. Run the Test Project

How to Test

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