readme.md

OpenWeather

About

OpenWeather is a Laravel package simplifying working with the free Open Weather Map APIs.

OpenWeather takes care of making requests to various free Open Weather Map APIs and returns well-structured easy to use weather data including conditions, temperatures, humidity, pressure, wind, location, and timestamp data.

Take a look at the Example Usage section output below for a typical structured response.

Supported APIs

The package supports the following free Open Weather Map APIs:

• Current Weather
• 4 Day 3 Hour Forecast
• Onecall Forecast
• 5 Day Historical

Free API Limitations

• 60 calls/minute up to 1,000,000 calls/month
• 1000 calls/day when using Onecall requests

Requirements

• A valid Open Weather Maps API Key (AppID).

Install

Use composer to install the package

$ composer require dnsimmons/openweather

For Laravel >= 5.5 the package is auto-discovered.

For older Laravel versions prior to 5.5 add the service provider to your config/app.php along with an alias:

'providers' => [
	...
    Dnsimmons\OpenWeather\OpenWeatherServiceProvider::class,
];

'aliases' => [
	...
    'OpenWeather' => Dnsimmons\OpenWeather\OpenWeather::class,	
];

Publish the required package configuration file using the artisan command:

$ php artisan vendor:publish

Edit the .env file in your Laravel instance add the following environment variables and add your OpenWeather API key:

OPENWEATHER_API_KEY="your-api-key"
OPENWEATHER_API_LANG="en"
OPENWEATHER_API_DATE_FORMAT="m/d/Y"
OPENWEATHER_API_TIME_FORMAT="h:i A"
OPENWEATHER_API_DAY_FORMAT="l"

Example Usage

In the example below we fetch the current weather by postal code.

$weather = new OpenWeather();
$current = $weather->getCurrentWeatherByPostal('02111');
print_r($current);

Output

Array
(
    [formats] => Array
        (
            [lang] => en
            [date] => m/d/Y
            [day] => l
            [time] => h:i A
            [units] => imperial
        )

    [datetime] => Array
        (
            [timestamp] => 1593387767
            [timestamp_sunrise] => 1593335394
            [timestamp_sunset] => 1593390304
            [formatted_date] => 06/28/2020
            [formatted_day] => Sunday
            [formatted_time] => 11:42 PM
            [formatted_sunrise] => 09:09 AM
            [formatted_sunset] => 12:25 AM
        )

    [location] => Array
        (
            [id] => 4930956
            [name] => Boston
            [country] => US
            [latitude] => 42.36
            [longitude] => -71.06
        )

    [condition] => Array
        (
            [id]   => 801
            [name] => Rain
            [desc] => light rain
            [icon] => https://openweathermap.org/img/w/10d.png
        )

    [wind] => Array
        (
            [speed] => 11.5
            [deg] => 113
            [direction] => SE
        )

    [forecast] => Array
        (
            [temp] => 67
            [temp_min] => 64
            [temp_max] => 68
            [pressure] => 1007
            [humidity] => 88
        )

)

Methods

All methods return an array on success and FALSE on failure.

Current Weather Methods

getCurrentWeatherByCityName(string $city, string $units)

Params

• City Name (example: Boston)
• Units (imperial (default), metric, or kelvin)

getCurrentWeatherByCityId(int $id, string $units)

Params

• City ID
• Units (imperial (default), metric, or kelvin)

getCurrentWeatherByCoords(string $latitude, string $longitude, string $units)

Params

• Latitude
• Longitude
• Units (imperial (default), metric, or kelvin)

getCurrentWeatherByPostal(string $postal, string $units)

Params

• US Postal Code
• Units (imperial (default), metric, or kelvin)

4 Day 3 Hour Forecast Methods

getForecastWeatherByCityName(string $city, string $units)

Params

• City Name (example: Boston)
• Units (imperial (default), metric, or kelvin)

getForecastWeatherByCityId(int $id, string $units)

Params

• City ID
• Units (imperial (default), metric, or kelvin)

getForecastWeatherByCoords(string $latitude, string $longitude, string $units)

Params

• Latitude
• Longitude
• Units (imperial (default), metric, or kelvin)

getForecastWeatherByPostal(string $postal, string $units)

Params

• US Postal Code
• Units (imperial (default), metric, or kelvin)

Onecall Request Methods

getOnecallWeatherByCoords(string $latitude, string $longitude, string $units, string $exclude)

Params

• Latitude
• Longitude
• Units (imperial (default), metric, or kelvin)
• Exclude (optional comma separated values: current,hourly,daily)

Onecall Historical Request Methods

getHistoricalWeatherByCoords(string $latitude, string $longitude, string $date, string $units)

Params

• Latitude
• Longitude
• Date (example: 7/12/2020)
• Units (imperial (default), metric, or kelvin)