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.
- 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.
You can install the package via Composer, by using the following command:
composer require rugaard/weatherkitThis 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,
]The default package configuration are setup to use the following environment variables.
| Variable name | Default | Description |
|---|---|---|
RUGAARD_WEATHERKIT_AUTH_FILEPATH |
Path to the .p8 key file. |
|
RUGAARD_WEATHERKIT_AUTH_KEY_ID |
Key ID matching the .p8 key file |
|
RUGAARD_WEATHERKIT_AUTH_APP_PREFIX_ID |
App Prefix ID (aka. Team ID) | |
RUGAARD_WEATHERKIT_AUTH_BUNDLE_ID |
Bundle ID of your App ID. | |
RUGAARD_WEATHERKIT_LANGUAGE_CODE |
config('app.locale', 'en') |
Language code |
RUGAARD_WEATHERKIT_TIMEZONE |
config('app.timezone', 'UTC') |
Set timezone of timestamps |
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\LaravelServiceProviderAfter 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.
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:
| Description | Bundle ID |
|---|---|
| Latest weather forecast | com.forecast.weather |
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.
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.
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.
To generate an access token, you're going to need a few things:
- The
App ID PrefixandBundle IDthat you created in Create new App ID section. - The
Key IDof 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;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());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');
}
}For more in-depth documentation about forecast types, measurements and more, please refer to the Wiki.
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent