README

⚠️ DISCLAIMER ⚠️

Apple's WeatherKit REST API is currently still in beta and the documentation is not fully up-to-date.

During development undocumented responses and values were encountered, but have been handled to the best of what information was available at the time.

📖 Table of contents

Features
Installation
- Laravel provider
Authentication
- Create new App ID
- Create new key
Usage
Documentation
License

🚀 Features

Multiple forecast types
- Current weather
- Next hour (minute-by-minute) forecast 🔹
- Hourly forecast
- Daily forecast
Weather alerts 🔸
Built-in unit conversions
- Length
- Pressure
- Speed
- Temperature

🔹 = In countries where available. 🔸 = When a country code is provided.

📦 Installation

You can install the package via Composer, by using the following command:

composer require rugaard/weatherkit

Laravel provider

This package comes with a out-of-the-box Service Provider for the Laravel framework. If you're using a newer version of Laravel (>= 5.5) then the service provider will loaded automatically.

Are you using an older version, then you need to manually add the service provider to the config/app.php file:

'providers' => [
    Rugaard\WeatherKit\Providers\LaravelServiceProvider::class,
]

Configuration

The default package configuration are setup to use the following environment variables.

Should you need to change the default configuration, you can publish the configuration file to your project.

php artisan vendor:publish --provider=\Rugaard\WeatherKit\Providers\LaravelServiceProvider

🔑 Authentication

After Apple bought DarkSky and turned into WeatherKit, the API now requires authentication. To be able to authenticate, you are required to be part of Apple's Developer Program.

Once you're enrolled with Apple Developer Program, you must register a new App ID and create a new Key.

Create new App ID

To create a new App ID, you must register your app on this form. Enter a short description and give your app a unique bundle ID (reverse url).

Example:

When you are done filling out the required fields, you need ☑️ WeatherKit under the Capabilities and App Services tabs.

Afterwards, click the blue Continue button and you're done.

Create new key

To create a new key, you must generate it from this form.

Give your key a name and make sure to enable ☑️ WeatherKit. When you're done, click the blue Continue button. You'll be redirected to a confirmation page, where you click the blue Register button.

Then, download your key as physical file to your machine. It's required for authenticating with the API.

And that's it. You're done.

⚙️ Usage

Before the client can be instantiated, it requires an access token. To generate an access token, Apple requires you to create an App ID and Key, which you to download as a physical file.

If you have not done these things yet, you can follow the guide in the 🔑 Authentication section of this README.

Generate access token

To generate an access token, you're going to need a few things:

The App ID Prefix and Bundle ID that you created in Create new App ID section.
The Key ID of the key, that you created in the Create new key section.
The physical key you downloaded in the Create new key section.

<?php

use Rugaard\WeatherKit\Token;

// Details from "Create new App ID" section.
$appIdPrefix = 'O9876S4E2I';
$bundleId = 'com.forecast.weather';

// Details from "Create new key" section.
$pathToKey = 'credentials/AuthKey_I2E4S6789O.p8'
$keyId = 1234567890;

// Create Token instance.
$token = new Token($pathToKey, $keyId, $appIdPrefix, $bundleId);

When a Token instance has been created, you can retrieve the generated access token in two different ways.

// Method 1: getToken()
$accessToken = $token->getToken();

// Method 2: __toString()
$accessToken = (string) $token;

Standalone

Before we are able to make any requests to the API, we need to instantiate the HTTP client. A client can be instantiated with or without a default location.

<?php

use Rugaard\WeatherKit\Client;

// Instantiate client without default location.
$weatherKit = new Client($token->getToken(), null, null, null);

// Instantiate client with default location.
$weatherKit = new Client((string) $token, 55.6736841, 12.5681471, 'dk');

// Instantiate client with default location and local language/timezone.
$weatherKit = new Client((string) $token, 55.6736841, 12.5681471, 'dk', 'da', 'Europe/Copenhagen');

When a client has been instantiated, it's possible to change the location, language and timezone, if needed.

// Change location to London.
$weatherKit->setLocation(51.5286416, -0.1015987);

// Country code is optional
// but required to retrieve weather alerts.
$weatherKit->setLocation(51.5286416, -0.1015987, 'gb');

// Change language to German.
$weatherKit->setLanguage('de');

// Change timezone to Paris.
$weatherKit->setTimezone('Europe/Paris');

You can either retrieve all forecasts at once or individually.

// Get all forecasts at once.
/* @var $forecasts \Illuminate\Support\Collection */
$forecasts = $weatherKit->weather();

// Get current forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\Currently */
$forecast = $weatherKit->currently();

// Get next hour (minute-by-minute) forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\NextHour */
$forecast = $weatherKit->nextHour();

// Get hourly forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\Hourly */
$forecast = $weatherKit->hourly();

// Get daily forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\Daily */
$forecast = $weatherKit->daily();

When a country code has been set with the client, you are able to retrieve weather alerts, should there be any associated with the location.

// Get weather alerts.
/* @var $alerts \Rugaard\WeatherKit\DTO\DataSets\Alerts */
$alerts = $weatherKit->alerts();

// Get detailed information about a specific alert.
/* @var $alertDetails \Rugaard\WeatherKit\DTO\Forecasts\AlertDetails */
$alertDetails = $weatherKit->alert($alerts->getData()->first()->getId());

With Laravel

When using this package with Laravel, the client will automatically be instantiated and added to the service container.

By default the settings are set via environment variables, described in the 📦 Installation section. Should you want to use something else than environment variables, you can change it in the config file at config/weatherkit.php.

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Controller;
use Rugaard\WeatherKit\Client as WeatherKit;

class WeatherController extends Controller
{
    /**
     * Get all forecasts at once.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function forecast(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->weather();
    }
    
    /**
     * Get current weather measurements.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function currently(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->currently();
    }
    
    /**
     * Get next hour (minute-by-minute) forecast.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function nextHour(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->nextHour();
    }
    
    /**
     * Get hourly forecast.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function hourly(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->hourly();
    }
    
    /**
     * Get daily forecast.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function daily(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->daily();
    }
}

It's possible to set/change default settings on the Client by setting them in the boot() method of the AppServiceProvider. This way, you can avoid setting location/language/timezone on each request.

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Rugaard\WeatherKit\Client as WeatherKit;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot(WeatherKit $weatherKit)
    {
        // Change location to London.
        $weatherKit->setLocation(51.5286416, -0.1015987);
        
        // Country code is optional
        // but required to retrieve weather alerts.
        $weatherKit->setLocation(51.5286416, -0.1015987, 'gb');
        
        // Change language to German.
        $weatherKit->setLanguage('de');
        
        // Change timezone to Paris.
        $weatherKit->setTimezone('Europe/Paris');
    }
}

📚 Documentation

For more in-depth documentation about forecast types, measurements and more, please refer to the Wiki.

🚓 License

This package is licensed under MIT.

Since this package uses an Apple service, you need follow the guidelines and requirements for attributing Apple weather data. For more details, view the attribution requirements on Apple's website.

rugaard / weatherkit

Maintainers

Details