README

Laravel OpenWeather API (openweather-laravel-api) is a Laravel package to connect Open Weather Map APIs ( https://openweathermap.org/api ) and access free API services (current weather, weather forecast, weather history) easily.

Supported APIs

Requirements

Installation

Install the package through Composer. On the command line:

composer require rakibdevs/openweather-laravel-api

Configuration

If Laravel > 7, no need to add provider

Add the following to your providers array in config/app.php:

'providers' => [
    // ...
    RakibDevs\Weather\WeatherServiceProvider::class,
],
'aliases' => [
    //...
    'Weather' => RakibDevs\Weather\Weather::class,	
];

Add API key and desired language in .env

OPENWEATHER_API_KEY=
OPENWEATHER_API_LANG=en

If your existing .env uses the older misspelled OPENWAETHER_API_KEY / OPENWAETHER_API_LANG, those are still honored as a fallback, so no change is required to keep working.

Publish the required package configuration file using the artisan command:

	$ php artisan vendor:publish

Edit the config/openweather.php file and modify the api_key value with your Open Weather Map api key.

	return [
	    'api_key' 	        => env('OPENWEATHER_API_KEY', ''),
    	    'onecall_api_version' => '2.5',
            'historical_api_version' => '2.5',
            'forecast_api_version' => '2.5',
            'pollution_api_version' => '2.5',   // legacy misspelled 'polution_api_version' is still honored
            'geo_api_version' => '1.0',
	    'lang' 		=> env('OPENWEATHER_API_LANG', 'en'),
	    'date_format'       => 'm/d/Y',
	    'time_format'       => 'h:i A',
	    'day_format'        => 'l',
	    'temp_format'       => 'c',        // c for celcius, f for farenheit, k for kelvin
	    'cache_enabled'     => env('OPENWEATHER_CACHE_ENABLED', false),
	    'cache_ttl'         => env('OPENWEATHER_CACHE_TTL', 600),  // seconds
	];

Now you can configure API version from config as One Call API is upgraded to version 3.0. Please set available api version in config.

Usage

Here you can see some example of just how simple this package is to use.

use RakibDevs\Weather\Weather;

$wt = new Weather();

$info = $wt->getCurrentByCity('dhaka');    // Get current weather by city name

Using the Facade (optional)

The package auto-registers a Weather facade, so you can also call it statically:

use RakibDevs\Weather\Facades\Weather;

$info = Weather::getCurrentByCity('dhaka');

Or resolve it from the container / via dependency injection:

$info = app('weather')->getCurrentByCity('dhaka');

Per-call options (optional)

Override units or language for a single request without touching the config. These setters are fluent and reset automatically after each request:

// c = metric, f = imperial, k = standard
$info = $wt->units('f')->lang('bn')->getCurrentByCity('dhaka');

Response caching (optional)

Enable caching in config/openweather.php (or via .env) to reduce API calls. It is off by default, so existing behavior is unchanged:

OPENWEATHER_CACHE_ENABLED=true
OPENWEATHER_CACHE_TTL=600

Fluent response (optional)

By default every method returns the raw stdClass response (unchanged). Call ->fluent() to get a WeatherResponse wrapper instead — it keeps the familiar property access ($res->main->temp still works) and adds dot-notation access, conversions and helpers. The flag applies to a single request and then resets:

$res = $wt->fluent()->getCurrentByCity('dhaka');

// backward-compatible property access still works
$res->main->temp;

// dot-notation access with default
$res->get('main.temp');
$res->get('weather.0.description', 'n/a');
$res->has('wind.gust');

// convenience getters (current-weather shape)
$res->temperature();     // main.temp
$res->feelsLike();       // main.feels_like
$res->humidity();        // main.humidity
$res->windSpeed();       // wind.speed
$res->condition();       // weather.0.main
$res->description();     // weather.0.description
$res->city();            // name
$res->country();         // sys.country
$res->icon();            // weather.0.icon
$res->iconUrl();         // https://openweathermap.org/img/wn/04d@2x.png

// conversions & collections
$res->toArray();
$res->toJson();
$res->raw();                       // the original stdClass, untouched
$res->collect('list');             // Illuminate\Support\Collection (for list responses)

// ArrayAccess (dot notation supported)
$res['main.temp'];

->fluent() composes with the other setters, e.g. $wt->fluent()->units('f')->getCurrentByCity('dhaka').

Current weather

Access current weather data for any location on Earth including over 200,000 cities! OpenWeather collect and process weather data from different sources such as global and local weather models, satellites, radars and vast network of weather stations

// By city name
$info = $wt->getCurrentByCity('dhaka'); 

// By city ID - download list of city id here http://bulk.openweathermap.org/sample/
$info = $wt->getCurrentByCity(1185241); 

// By Zip Code - string with country code 
$info = $wt->getCurrentByZip('94040,us');  // If no country code specified, us will be default

// By coordinates : latitude and longitude
$info = $wt->getCurrentByCord(23.7104, 90.4074);

Output:

{
  "coord": {
    "lon": 90.4074
    "lat": 23.7104
  }
  "weather":[
    0 => { 
      "id": 721
      "main": "Haze"
      "description": "haze"
      "icon": "50d"
    }
  ]
  "base": "stations"
  "main": {
    "temp": 26
    "feels_like": 25.42
    "temp_min": 26
    "temp_max": 26
    "pressure": 1009
    "humidity": 57
  }
  "visibility": 3500
  "wind": {
    "speed": 4.12
    "deg": 280
  }
  "clouds": {
    "all": 85
  }
  "dt": "01/09/2021 04:16 PM"
  "sys": {
    "type": 1
    "id": 9145
    "country": "BD"
    "sunrise": "01/09/2021 06:42 AM"
    "sunset": "01/09/2021 05:28 PM"
  }
  "timezone": 21600
  "id": 1185241
  "name": "Dhaka"
  "cod": 200
}

One Call API

Make just one API call and get all your essential weather data for a specific location with OpenWeather One Call API.

// By coordinates : latitude and longitude
$info = $wt->getOneCallByCord(23.7104, 90.4074);

4 Day 3 Hour Forecast

4 day forecast is available at any location or city. It includes weather forecast data with 3-hour step.

// By city name
$info = $wt->get3HourlyByCity('dhaka'); 

// By city ID - download list of city id here http://bulk.openweathermap.org/sample/
$info = $wt->get3HourlyByCity(1185241); 

// By Zip Code - string with country code 
$info = $wt->get3HourlyByZip('94040,us');  // If no country code specified, us will be default

// By coordinates : latitude and longitude
$info = $wt->get3HourlyByCord(23.7104, 90.4074);

5 Day Historical

Get access to historical weather data for the previous 5 days.

// By coordinates : latitude, longitude and date
$info = $wt->getHistoryByCord(23.7104, 90.4074, '2020-01-09');

Air Pollution

Air Pollution API provides current, forecast and historical air pollution data for any coordinates on the globe

Besides basic Air Quality Index, the API returns data about polluting gases, such as Carbon monoxide (CO), Nitrogen monoxide (NO), Nitrogen dioxide (NO2), Ozone (O3), Sulphur dioxide (SO2), Ammonia (NH3), and particulates (PM2.5 and PM10).

Air pollution forecast is available for 5 days with hourly granularity. Historical data is accessible from 27th November 2020.

// By coordinates : latitude, longitude and date
$info = $wt->getAirPollutionByCord(23.7104, 90.4074);

Geocoding API

Geocoding API is a simple tool that we have developed to ease the search for locations while working with geographic names and coordinates. -> Direct geocoding converts the specified name of a location or area into the exact geographical coordinates; -> Reverse geocoding converts the geographical coordinates into the names of the nearby locations.

// By city name
$info = $wt->getGeoByCity('dhaka');

// By coordinates : latitude, longitude and date
$info = $wt->getGeoByCity(23.7104, 90.4074);

Free API Limitations

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

License

Laravel Open Weather API is licensed under The MIT License (MIT).