diff --git a/README.md b/README.md index 715613b..44d6beb 100644 --- a/README.md +++ b/README.md @@ -1 +1,27 @@ -# wunderground-api \ No newline at end of file +# Weather Underground API Client + +This library shall help you integrate the WeatherUnderground API to your webservice. +It is extremely lightweight and provides all necessary code. + +## Code Example + +Using the API is very easy - you'll only need to provide a API key (Get one [here](https://www.wunderground.com/weather/api/)) in order to use it. There are functions for retrieving different weather data by predefined conditions, like "by country and city", "by latitude and longitude", "by airport code" or even "by IP address". + +```php +// By default the current conditions will be requested in english language. +$weather = (new \lfischer\wunderground\API(''))->getByLocation('Germany', 'Dusseldorf'); +``` + +## Future to-dos / nice-to-have + +At some point I'd like to improve this client to be as readable as possible. For example: + +```php +use lfischer\wunderground; + +$weather = (new API('')) + ->getConditions() + ->byLocation('Germany', 'Dusseldorf') + ->fetch() + ->asArray(); +``` \ No newline at end of file diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..0eee9d9 --- /dev/null +++ b/composer.json @@ -0,0 +1,26 @@ +{ + "name": "lfischer/wunderground-api", + "type": "library", + "description": "A simple PHP library for querying the Weather Underground API.", + "keywords": ["API", "weather"], + "homepage": "https://github.com/leonardfischer/wunderground-api", + "license": "MIT", + "authors": [{ + "name": "Leonard Fischer", + "email": "post@leonard.fischer.de", + "homepage": "http://leonardfischer.de", + "role": "Developer" + }], + "support": { + "issues": "https://github.com/leonardfischer/wunderground-api/issues", + "source": "https://github.com/leonardfischer/wunderground-api" + }, + "require": { + "php": ">=5.4.0" + }, + "autoload": { + "psr-4": { + "lfischer\\wunderground\\": "src/" + } + } +} \ No newline at end of file diff --git a/src/API.php b/src/API.php new file mode 100644 index 0000000..ce485a3 --- /dev/null +++ b/src/API.php @@ -0,0 +1,60 @@ + + */ +class API extends Request +{ + /** + * Retrieves weather data by a (API internal) "city ID". + * + * @param string $id + * @return array + */ + public function getByPWSId ($id) + { + return $this->fetch(['query' => 'pws:' . $id])->getResponseArray(); + } // function + + + /** + * Retrieves weather data by a (API internal) "city ID". + * + * @param string $code + * @return array + */ + public function getByAirportCode ($code) + { + return $this->fetch(['query' => $code])->getResponseArray(); + } // function + + + /** + * Retrieves weather data by given coordinates. + * + * @param float $lat + * @param float $lng + * @return array + */ + public function getByCoordinates ($lat, $lng) + { + return $this->fetch(['query' => $lat . ',' . $lng])->getResponseArray(); + } // function + + + /** + * Retrieves weather data by given coordinates. + * + * @param string $city + * @param string $country + * @return array + */ + public function getByLocation ($city, $country) + { + return $this->fetch(['query' => $country . '/' . $city])->getResponseArray(); + } // function +} // class \ No newline at end of file diff --git a/src/Request.php b/src/Request.php new file mode 100644 index 0000000..12ecce8 --- /dev/null +++ b/src/Request.php @@ -0,0 +1,208 @@ + + */ +class Request +{ + const URL = 'http://api.wunderground.com/api/:apiKey/:features/:settings/q/:query.json'; + + /** + * @var string + */ + protected $apiKey = ''; + + /** + * @var string + */ + protected $feature = 'conditions'; + + /** + * @var string + */ + protected $settings = 'lang:EN'; + + /** + * @var string + */ + protected $query = 'CA/San_Francisco'; + + /** + * @var string + */ + protected $responseJSON = null; + + /** + * @var array + */ + protected $responseArray = null; + + + /** + * Constructor. + * + * @param $apiKey + */ + public function __construct ($apiKey) + { + $this->apiKey = $apiKey; + } // function + + + /** + * Set a API feature. Available features: + * - alerts + * - almanac + * - astronomy + * - conditions + * - currenthurricane + * - forecast + * - forecast10day + * - geolookup + * - history + * - hourly + * - hourly10day + * - planner + * - rawtide + * - tide + * - webcams + * - yesterday + * + * @param string $feature + * @return $this + */ + public function setFeature ($feature) + { + $this->feature = $feature; + + return $this; + } // function + + + /** + * Set a API setting. Available settings are: + * - lang + * - pws + * - bestfct + * + * @param string $settings + * @return $this + */ + public function setSettings ($settings) + { + $this->settings = $settings; + + return $this; + } // function + + + /** + * Set a API query. Query examples: + * - / + * - / + * - / + * - , + * - + * - pws: + * - autoip + * - autoip.json?geo_ip= + * + * @param string $query + * @return $this + */ + public function setQuery ($query) + { + $this->query = $query; + + return $this; + } // function + + + /** + * API fetch method. + * + * @param array $parameters + * @return $this + */ + public function fetch (array $parameters = []) + { + if (isset($parameters['features'])) + { + $this->setFeature($parameters['features']); + } // if + + if (isset($parameters['settings'])) + { + $this->setSettings($parameters['settings']); + } // if + + if (isset($parameters['query'])) + { + $this->setQuery($parameters['query']); + } // if + + $url = strtr(self::URL, [ + ':apiKey' => $this->apiKey, + ':features' => $this->feature, + ':settings' => $this->settings, + ':query' => $this->query + ]); + + $this->responseJSON = file_get_contents($url); + $this->responseArray = json_decode($this->response, true); + + if (!is_array($this->responseArray)) + { + // @todo Throw exception. + } // if + + if (!isset($this->responseArray['response'])) + { + // @todo Throw exception. + } // if + + if (isset($this->responseArray['response']) && isset($this->responseArray['response']['error'])) + { + // @todo Throw exception. + } // if + + return $this; + } // function + + + /** + * Method for returning the raw response. + * + * @return string + */ + public function getResponseJSON () + { + return $this->responseJSON; + } // function + + + /** + * Method for returning the response array. + * + * @return array + */ + public function getResponseArray () + { + return $this->responseArray; + } // function + + + /** + * Method for returning the response as object. + * + * @return \stdClass + */ + public function getResponseObject () + { + return json_decode($this->responseJSON); + } // function +} // class \ No newline at end of file