Weather overview endpoint

composer.json

@@ -14,7 +14,7 @@
     "require": {
         "php": ">=8.1",
         "myclabs/deep-copy": "^1.13",
-        "programmatordev/php-api-sdk": "^2.0",
+        "programmatordev/php-api-sdk": "^2.1",
         "symfony/options-resolver": "^6.4|^7.3"
     },
     "require-dev": {

docs/03-supported-apis.md

@@ -5,6 +5,7 @@
     - [getWeather](#getweather)
     - [getWeatherByDate](#getweatherbydate)
     - [getWeatherSummaryByDate](#getweathersummarybydate)
+    - [getWeatherOverviewByDate](#getweatheroverviewbydate)
   - [Weather](#weather)
     - [getCurrent](#getcurrent)
     - [getForecast](#getforecast)
@@ -68,6 +69,21 @@ Returns a [`WeatherSummary`](05-entities.md#weathersummary) object:
 $weatherSummary = $api->oneCall()->getWeatherSummaryByDate(50, 50, new \DateTime('1985-07-19'));
 ```
 
+#### `getWeatherOverviewByDate`
+
+```php
+getWeatherOverviewByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherOverview
+```
+
+Get the weather overview with a human-readable summary for today and tomorrow's forecast, 
+using OpenWeather AI.
+
+Returns a [`WeatherOverview`](05-entities.md#weatheroverview) object:
+
+```php
+$weatherOverview = $api->oneCall()->getWeatherOverviewByDate(50, 50, new \DateTime('today'));
+```
+
 ### Weather
 
 #### `getCurrent`

docs/05-entities.md

@@ -78,6 +78,13 @@
 - `getAtmosphericPressure()`: `int`
 - `getWind()`: [`Wind`](#wind)
 
+### WeatherOverview
+
+- `getCoordinate()`: [`Coordinate`](#coordinate)
+- `getTimezone()`: [`Timezone`](#timezone)
+- `getDateTime()`: `\DateTimeImmutable`
+- `getOverview()`: `string`
+
 ### WeatherData
 
 - `getDateTime()`: `\DateTimeImmutable`

src/Entity/AirPollution/AirPollutionCollection.php

@@ -18,7 +18,7 @@ class AirPollutionCollection
 
     public function __construct(array $data)
     {
-        $this->numResults = \count($data['list']);
+        $this->numResults = count($data['list']);
         $this->coordinate = new Coordinate($data['coord']);
         $this->data = $this->createEntityList(AirPollutionData::class, $data['list']);
     }

src/Entity/AirPollution/AirQuality.php

@@ -28,12 +28,12 @@ private function findQualitativeName(int $index): string
     {
         // levels based on https://openweathermap.org/api/air-pollution
         return match ($index) {
-            0 => 'Undefined',
             1 => 'Good',
             2 => 'Fair',
             3 => 'Moderate',
             4 => 'Poor',
-            5 => 'Very Poor'
+            5 => 'Very Poor',
+            default => 'Undefined'
         };
     }
 }

src/Entity/OneCall/DayData.php

@@ -28,7 +28,7 @@ public function __construct(array $data)
 
         $this->temperature = new Temperature($data['temp']);
         $this->temperatureFeelsLike = new Temperature($data['feels_like']);
-        $this->precipitationProbability = \round($data['pop'] * 100);
+        $this->precipitationProbability = round($data['pop'] * 100);
         $this->summary = $data['summary'];
         $this->moonPhase = new MoonPhase($data);
         $this->moonriseAt = \DateTimeImmutable::createFromFormat('U', $data['moonrise']);

src/Entity/OneCall/HourData.php

@@ -19,7 +19,7 @@ public function __construct(array $data)
         $this->temperature = $data['temp'];
         $this->temperatureFeelsLike = $data['feels_like'];
         $this->visibility = $data['visibility'];
-        $this->precipitationProbability = \round($data['pop'] * 100);
+        $this->precipitationProbability = round($data['pop'] * 100);
     }
 
     public function getTemperature(): float

src/Entity/OneCall/MoonPhase.php

@@ -23,7 +23,7 @@ public function __construct(array $data)
     {
         $this->value = $data['moon_phase'];
         $this->systemName = $this->findSystemName($this->value);
-        $this->name = \ucwords(\strtolower(\str_replace('_', ' ', $this->systemName)));
+        $this->name = ucwords(strtolower(str_replace('_', ' ', $this->systemName)));
     }
 
     public function getValue(): float

src/Entity/OneCall/WeatherOverview.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
+
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinate;
+use ProgrammatorDev\OpenWeatherMap\Entity\Timezone;
+
+class WeatherOverview
+{
+    private Coordinate $coordinate;
+
+    private Timezone $timezone;
+
+    private \DateTimeImmutable $dateTime;
+
+    private string $overview;
+
+    public function __construct(array $data)
+    {
+        $this->coordinate = new Coordinate($data);
+
+        $this->timezone = new Timezone([
+            'timezone_offset' => \DateTimeImmutable::createFromFormat('P', $data['tz'])->getOffset()
+        ]);
+
+        $this->dateTime = \DateTimeImmutable::createFromFormat(
+            'Y-m-d H:i:s P',
+            sprintf('%s 00:00:00 %s', $data['date'], $data['tz'])
+        );
+
+        $this->overview = $data['weather_overview'];
+    }
+
+    public function getCoordinate(): Coordinate
+    {
+        return $this->coordinate;
+    }
+
+    public function getTimezone(): Timezone
+    {
+        return $this->timezone;
+    }
+
+    public function getDateTime(): \DateTimeImmutable
+    {
+        return $this->dateTime;
+    }
+
+    public function getOverview(): string
+    {
+        return $this->overview;
+    }
+}

src/Entity/OneCall/WeatherSummary.php

@@ -36,7 +36,7 @@ public function __construct(array $data)
 
         $this->dateTime = \DateTimeImmutable::createFromFormat(
             'Y-m-d H:i:s P',
-            \sprintf('%s 00:00:00 %s', $data['date'], $data['tz'])
+            sprintf('%s 00:00:00 %s', $data['date'], $data['tz'])
         );
 
         $this->cloudiness = \round($data['cloud_cover']['afternoon']);
@@ -52,11 +52,11 @@ public function __construct(array $data)
             'max' => $data['temperature']['max']
         ]);
 
-        $this->atmosphericPressure = \round($data['pressure']['afternoon']);
+        $this->atmosphericPressure = round($data['pressure']['afternoon']);
 
         $this->wind = new Wind([
             'speed' => $data['wind']['max']['speed'],
-            'deg' => \round($data['wind']['max']['direction'])
+            'deg' => round($data['wind']['max']['direction'])
         ]);
     }
 
@@ -70,9 +70,6 @@ public function getTimezone(): Timezone
         return $this->timezone;
     }
 
-    /**
-     * DateTime in UTC
-     */
     public function getDateTime(): \DateTimeImmutable
     {
         return $this->dateTime;

src/Entity/Weather/WeatherData.php

@@ -54,7 +54,7 @@ public function __construct(array $data)
         $this->wind = new Wind($data['wind']);
 
         $this->precipitationProbability = isset($data['pop'])
-            ? \round($data['pop'] * 100)
+            ? round($data['pop'] * 100)
             : null;
 
         $this->rainVolume = $data['rain']['1h'] ?? $data['rain']['3h'] ?? null;

src/Exception/ApiErrorException.php

@@ -8,7 +8,9 @@ class ApiErrorException extends \Exception
 
     public function __construct(array $error)
     {
-        parent::__construct($error['message'], $error['cod']);
+        $code = $error['cod'] ?? $error['code'];
+
+        parent::__construct($error['message'], $code);
 
         $this->parameters = $error['parameters'] ?? null;
     }

src/Resource/OneCallResource.php

@@ -5,6 +5,7 @@
 use ProgrammatorDev\Api\Method;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\Weather;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherMoment;
+use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherOverview;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherSummary;
 use ProgrammatorDev\OpenWeatherMap\Resource\Util\LanguageTrait;
 use ProgrammatorDev\OpenWeatherMap\Resource\Util\UnitSystemTrait;
@@ -77,4 +78,24 @@ public function getWeatherSummaryByDate(float $latitude, float $longitude, \Date
 
         return new WeatherSummary($data);
     }
+
+    /**
+     * Get the weather overview with a human-readable summary for today and tomorrow's forecast, using OpenWeather AI
+     *
+     * @throws ClientExceptionInterface
+     */
+    public function getWeatherOverviewByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherOverview
+    {
+        $data = $this->api->request(
+            method: Method::GET,
+            path: '/data/3.0/onecall/overview',
+            query: [
+                'lat' => $latitude,
+                'lon' => $longitude,
+                'date' => $date->format('Y-m-d')
+            ]
+        );
+
+        return new WeatherOverview($data);
+    }
 }

tests/Integration/OneCallResourceTest.php

@@ -4,6 +4,7 @@
 
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\Weather;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherMoment;
+use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherOverview;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherSummary;
 use ProgrammatorDev\OpenWeatherMap\Test\AbstractTest;
 use ProgrammatorDev\OpenWeatherMap\Test\MockResponse;
@@ -36,5 +37,12 @@ public static function provideItemResponseData(): \Generator
             'getWeatherSummaryByDate',
             [50, 50, new \DateTime()]
         ];
+        yield 'get weather overview by date' => [
+            WeatherOverview::class,
+            MockResponse::ONE_CALL_OVERVIEW,
+            'oneCall',
+            'getWeatherOverviewByDate',
+            [50, 50, new \DateTime()]
+        ];
     }
 }

tests/Unit/OneCall/WeatherOverviewTest.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Test\Unit\OneCall;
+
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinate;
+use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherOverview;
+use ProgrammatorDev\OpenWeatherMap\Entity\Timezone;
+use ProgrammatorDev\OpenWeatherMap\Test\AbstractTest;
+
+class WeatherOverviewTest extends AbstractTest
+{
+    public function testMethods()
+    {
+        $entity = new WeatherOverview([
+            'lat' => 50,
+            'lon' => 50,
+            'tz' => '+00:00',
+            'date' => '2025-01-01',
+            'weather_overview' => 'Weather overview text'
+        ]);
+
+        $this->assertInstanceOf(Coordinate::class, $entity->getCoordinate());
+        $this->assertInstanceOf(Timezone::class, $entity->getTimezone());
+        $this->assertInstanceOf(\DateTimeImmutable::class, $entity->getDateTime());
+        $this->assertSame('Weather overview text', $entity->getOverview());
+    }
+}

tests/Unit/OneCall/WeatherSummaryTest.php

@@ -2,10 +2,8 @@
 
 namespace ProgrammatorDev\OpenWeatherMap\Test\Unit\OneCall;
 
-use ProgrammatorDev\OpenWeatherMap\Entity\Condition;
 use ProgrammatorDev\OpenWeatherMap\Entity\Coordinate;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\Temperature;
-use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherData;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherSummary;
 use ProgrammatorDev\OpenWeatherMap\Entity\Timezone;
 use ProgrammatorDev\OpenWeatherMap\Entity\Wind;