added Air Pollution API

Author: Tom Klíma

Cmfcmf/OpenWeatherMap.php

@@ -18,10 +18,11 @@
 
 namespace Cmfcmf;
 
+use Cmfcmf\OpenWeatherMap\AirPollution;
 use Cmfcmf\OpenWeatherMap\CurrentWeather;
-use Cmfcmf\OpenWeatherMap\UVIndex;
 use Cmfcmf\OpenWeatherMap\CurrentWeatherGroup;
 use Cmfcmf\OpenWeatherMap\Exception as OWMException;
+use Cmfcmf\OpenWeatherMap\UVIndex;
 use Cmfcmf\OpenWeatherMap\WeatherForecast;
 use Psr\Cache\CacheItemPoolInterface;
 use Psr\Http\Client\ClientInterface;
@@ -67,6 +68,11 @@ class OpenWeatherMap
      */
     private $uvIndexUrl = 'https://api.openweathermap.org/data/2.5/uvi';
 
+    /**
+     * @var string The basic api url to fetch air pollution data from.
+     */
+    private $airPollutionUrl = 'https://api.openweathermap.org/pollution/v1/co';
+
     /**
      * @var CacheItemPoolInterface|null $cache The cache to use.
      */
@@ -336,6 +342,31 @@ public function getHistoricUVIndex($lat, $lon, $start, $end)
         }, $data);
     }
 
+    /**
+     * Returns atmosferic pollution by Carbon Monoxie
+     *
+     * @param float $lat The location's latitude.
+     * @param float $lon The location's longitude.
+     * @param ?DateTime|string $dateTime Time of the measurement. Set null for "current"
+     *
+     * @return AirPollution
+     *
+     * @api
+     * @throws \Exception
+     */
+    public function getAirPollution($lat, $lon, $dateTime = null)
+    {
+        if ($dateTime === null) {
+            $dateTime = 'current';
+        }
+
+        $answer = $this->getRawAirPollutionData($lat, $lon, $dateTime);
+        
+        $json = $this->parseJson($answer);
+
+        return new AirPollution($json);
+    }
+
     /**
      * Directly returns the xml/json/html string returned by OpenWeatherMap for the current weather.
      *
@@ -471,6 +502,20 @@ public function getRawUVIndexData($mode, $lat, $lon, $cnt = null, $start = null,
         return $this->cacheOrFetchResult($url);
     }
 
+    /**
+     * @param $lat
+     * @param $lon
+     * @param $dateTime
+     * @return bool|string Returns the fetched data.
+     * @throws OWMException
+     */
+    public function getRawAirPollutionData($lat, $lon, $dateTime)
+    {
+        $url = $this->buildAirPollutionUrl($lat, $lon, $dateTime, $this->airPollutionUrl);
+        
+        return $this->cacheOrFetchResult($url);
+    }
+
     /**
      * Returns whether or not the last result was fetched from the cache.
      *
@@ -505,6 +550,9 @@ private function cacheOrFetchResult($url)
         $response = $this->httpClient->sendRequest($this->httpRequestFactory->createRequest("GET", $url));
         $result = $response->getBody()->getContents();
         if ($response->getStatusCode() !== 200) {
+            if ($result === '{"message":"not found"}' && $response->getStatusCode() === 404) {
+                throw new OWMException('OpenWeatherMap returned that air pollution data for this location cannot be found - try less precision location.');
+            }
             throw new OWMException('OpenWeatherMap returned a response with status code ' . $response->getStatusCode() . ' and the following content '. $result);
         }
 
@@ -606,6 +654,21 @@ private function buildQueryUrlParameter($query)
         }
     }
 
+    /**
+     * Build the url to fetch air pollution data from.
+     *
+     * @param        $lat
+     * @param        $lon
+     * @param        $dateTime
+     * @param string $url The url to prepend.
+     *
+     * @return string The fetched url
+     */
+    private function buildAirPollutionUrl($lat, $lon, $dateTime, $url)
+    {
+        return $url."/$lat,$lon/$dateTime.json?appid=" . $this->apiKey;
+    }
+
     /**
      * @param string $answer The content returned by OpenWeatherMap.
      *

Cmfcmf/OpenWeatherMap/AirPollution.php

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ * OpenWeatherMap-PHP-API — A PHP API to parse weather data from https://OpenWeatherMap.org.
+ *
+ * @license MIT
+ *
+ * Please see the LICENSE file distributed with this source code for further
+ * information regarding copyright and licensing.
+ *
+ * Please visit the following links to read about the usage policies and the license of
+ * OpenWeatherMap data before using this library:
+ *
+ * @see https://OpenWeatherMap.org/price
+ * @see https://OpenWeatherMap.org/terms
+ * @see https://OpenWeatherMap.org/appid
+ */
+
+namespace Cmfcmf\OpenWeatherMap;
+
+use Cmfcmf\OpenWeatherMap\Util\Location;
+
+/**
+ * AirPollution class used to hold the air pollution and time of measurement
+ */
+class AirPollution
+{
+    /**
+     * @var \DateTime
+     */
+    public $dateTime;
+
+    /**
+     * @var Location
+     */
+    public $location;
+
+    /**
+     * @var AirPollutionData[]
+     */
+    public $data;
+
+    /**
+     * Create a new air pollution object.
+     *
+     * @param object $json
+     *
+     * @throws \Exception
+     * @internal
+     */
+    public function __construct($json)
+    {
+        $this->dateTime = new \DateTime($json->time, new \DateTimeZone('UTC'));
+        $this->location = new Location($json->location->latitude, $json->location->longitude);
+        $airPollutionData = [];
+        foreach ($json->data as $measurement) {
+            $airPollutionData[] = new AirPollutionData($measurement);
+        }
+        $this->data = $airPollutionData;
+    }
+
+    /**
+     * @return AirPollutionData|null
+     */
+    public function getLastAirPollutionData()
+    {
+        if (count($this->data) === 0) {
+            return null;
+        }
+
+        return reset($this->data);
+    }
+}

Cmfcmf/OpenWeatherMap/AirPollutionData.php

@@ -0,0 +1,79 @@
+<?php
+
+/*
+ * OpenWeatherMap-PHP-API — A PHP API to parse weather data from https://OpenWeatherMap.org.
+ *
+ * @license MIT
+ *
+ * Please see the LICENSE file distributed with this source code for further
+ * information regarding copyright and licensing.
+ *
+ * Please visit the following links to read about the usage policies and the license of
+ * OpenWeatherMap data before using this library:
+ *
+ * @see https://OpenWeatherMap.org/price
+ * @see https://OpenWeatherMap.org/terms
+ * @see https://OpenWeatherMap.org/appid
+ */
+
+namespace Cmfcmf\OpenWeatherMap;
+
+/**
+ * AirPollution class used to hold the air pollution and time of measurement
+ */
+class AirPollutionData
+{
+    /**
+     * @var float measurement precision
+     */
+    public $precision;
+
+    /**
+     * @var float atmospheric pressure at the point of measurement in hPa
+     */
+    public $pressure;
+
+    /**
+     * @var float volume mixing ratio
+     */
+    public $value;
+
+    /**
+     * Create a new air pollution data object.
+     *
+     * @param object $json
+     *
+     * @internal
+     */
+    public function __construct($json)
+    {
+        $this->precision = (float)$json->precision;
+        $this->pressure = (float)$json->pressure;
+        $this->value = (float)$json->value;
+    }
+
+    /**
+     * @return float
+     */
+    public function getPrecision(): float
+    {
+        return $this->precision;
+    }
+
+    /**
+     * @return float
+     */
+    public function getPressure(): float
+    {
+        return $this->pressure;
+    }
+
+    /**
+     * @return float
+     */
+    public function getValue(): float
+    {
+        return $this->value;
+    }
+    
+}

tests/OpenWeatherMapTest.php

@@ -167,6 +167,17 @@ public function testGetDailyWeatherForecast()
 
         $this->assertInstanceOf('\Cmfcmf\OpenWeatherMap\WeatherForecast', $dailyForecast);
     }
+    
+    public function testGetAirPollution() 
+    {
+        $airPollutionCurrent = $this->owm->getAirPollution(40, -74, null);
+        
+        $this->assertInstanceOf(OpenWeatherMap\AirPollution::class, $airPollutionCurrent);
+
+        $airPollutionPast = $this->owm->getAirPollution(40, -74, new \DateTime('now - 2 months'));
+        
+        $this->assertInstanceOf(OpenWeatherMap\AirPollution::class, $airPollutionPast);
+    }
 
     public function testWasCached()
     {