Weather Forecast in PHP

PHP Library for the Dark Sky API.

One of the projects I was working with recently, required the weather forecast functionality. There is a bunch of the weather forecast providers, so that you may choose from many options. I’ve chosen the Dark Sky API for myself and created the PHP Library for it. This article would give you some extra tips and tricks about the usage of the Dark Sky API and the PHP Library itself.

Dark Sky Account

First of all, you have to register and get your secret key:

Your “Secret Key” to access the Dark Sky API.

Dark Sky provides 1,000 free API requests every day. You can use those free requests right after registering, with your brand new secret key.

If you need more, you have to provide your Billing Information. Each API request over the free daily limit costs $0.0001. In other words, every extra 10,000 API requests would cost you $1.00. For example, 51,000 requests per day would cost $5.00 per day: 1,000 free requests + 50,000 paid requests.

You may set the Daily Usage Limit to make your payments more predictable:

Set the “Daily Usage Limit” to make your payments more predictable.

Installation

PHP Library is a stand-alone PHP package, which means that you can use it in any PHP application, no matter which framework do you use (if using any).

It requires at least PHP 5.5.9 (6 Feb 2014) which covers the vast majority of the existing and new PHP applications.

You may use Composer to install it into your project:

composer require dmitry-ivanov/dark-sky-api

Usage

The Dark Sky API provides two types of requests: Forecast Request and Time Machine Request. Forecast Request provides the weather data related to the current moment, and Time Machine Request allows you to specify the time.

Each request utilizes HTTP compression, as API suggests. Multiple Time Machine Requests are sent concurrently, which is much more performant.

Forecast Request

Forecast Request which obtains all blocks (default).

Required parameters are the secret-key and location (which is my hometown in this example). You may omit the units and the language parameters. The Dark Sky API would use the default values in that case.

The response is represented by the data blocks, such as currently, minutely, hourly, daily, etc. Request obtains all of the data blocks by default, which is unnecessary in many situations and may be optimized.

Dark Sky API provides the exclude parameter to manage the response data. Let’s imagine you need only the currently block. API suggests using the exclude=minutely,hourly,daily,alerts,flags parameter in that case.

You have to specify everything you want to exclude from the response.

But I think it’s more natural to specify what do you want to include, actually:

Forecast Request which obtains only the “currently” block.

You may use an array if you want to include several blocks:

Forecast Request which obtains “currently” and “daily” blocks.

Check the Response Format to see all of the available properties.

Time Machine Request

Time Machine Request with one date.

Time Machine Requests provide an ability to specify the date, for which you want to get the weather data. The “date” also may have the time part, and any “strtotime” string is acceptable, e.g. 1 Dec 2018, 2018-12-01 15:30:00, etc.

Of course, you can manage the response data, as well:

Time Machine Request which obtains only the “daily” block.

You may use an array of dates for multiple requests:

Multiple Time Machine Requests are sent concurrently.

Multiple Time Machine Requests are sent concurrently, and it’s much faster than sending them one after another. Note that an array is returned in that case, and the requested dates are used as its keys.

Headers, Alerts, and Flags

Object-level access to the Response Headers, Weather Alerts, and Flags.

The package also provides object-level access to the Response Headers, Weather Alerts, and Flags. Check the documentation to see available props.

Laravel Support

The last, but not the least is the Laravel support.

The package utilizes Laravel Package Discovery. If you’re using Laravel 5.5+, you will get the registered service provider and alias out-of-the-box.

Usage

Set your Secret Key in .env file:

DARK_SKY_KEY="Your Secret Key"

You may use the configured facade now:

Laravel facade usage.

Publish the config file to override request parameters (optionally):

php artisan vendor:publish --provider="DmitryIvanov\DarkSkyApi\Adapters\Laravel\DarkSkyApiServiceProvider"

I hope that this package and this article would be useful for you. It was exciting for me to create it, and I enjoyed to use the Dark Sky API overall.

And, of course, I am the first user of my package.

Thank you!