Implement Coordinates by Location Name endpoint

Cmfcmf/OpenWeatherMap.php

@@ -23,6 +23,8 @@
 use Cmfcmf\OpenWeatherMap\CurrentWeatherGroup;
 use Cmfcmf\OpenWeatherMap\Exception as OWMException;
 use Cmfcmf\OpenWeatherMap\NotFoundException as OWMNotFoundException;
+use Cmfcmf\OpenWeatherMap\Util\City;
+use Cmfcmf\OpenWeatherMap\Util\Location;
 use Cmfcmf\OpenWeatherMap\UVIndex;
 use Cmfcmf\OpenWeatherMap\WeatherForecast;
 use Psr\Cache\CacheItemPoolInterface;
@@ -74,6 +76,12 @@ class OpenWeatherMap
      */
     private $airPollutionUrl = 'https://api.openweathermap.org/pollution/v1/';
 
+    /**
+     * @var string The base API URL for fetching coordinates by location name.
+     * @see https://openweathermap.org/api/geocoding-api#direct_name
+     */
+    private $coordinatesByLocationNameUrl = 'http://api.openweathermap.org/geo/1.0/direct';
+
     /**
      * @var CacheItemPoolInterface|null $cache The cache to use.
      */
@@ -589,7 +597,9 @@ private function cacheOrFetchResult($url)
             }
         }
 
-        $response = $this->httpClient->sendRequest($this->httpRequestFactory->createRequest("GET", $url));
+        $response = $this->httpClient->sendRequest(
+            $this->httpRequestFactory->createRequest("GET", $url)
+        );
         $result = $response->getBody()->getContents();
         if ($response->getStatusCode() !== 200) {
             if (false !== strpos($result, 'not found') && $response->getStatusCode() === 404) {
@@ -668,6 +678,67 @@ private function buildUVIndexUrl($mode, $lat, $lon, $cnt = null, \DateTime $star
         return sprintf($this->uvIndexUrl . '%s?%s', $requestMode, http_build_query($params));
     }
 
+    public function getCoordinatesByLocationName(
+        $city,
+        $stateCode = null,
+        $countryCode = null,
+        $limit = null
+    ) {
+        $url = $this->buildCoordinatesByLocationNameUrl($city, $stateCode, $countryCode, $limit);
+        $response = $this->cacheOrFetchResult($url);
+        $data = $this->parseJson($response);
+        $cities = [];
+        foreach ($data as $datum) {
+            $cities[] = new City(
+                -1,
+                $datum->name,
+                $datum->lat,
+                $datum->lon,
+                $datum->country,
+                null,
+                null,
+                $datum->state,
+                (array)$datum->local_names
+            );
+        }
+
+        return $cities;
+    }
+
+    private function buildCoordinatesByLocationNameUrl(
+        string $city,
+        string $stateCode = null,
+        string $countryCode = null,
+        int $limit = null
+    ): string
+    {
+        $params = array(
+            'appid' => $this->apiKey,
+            'q' => $city,
+        );
+
+        if ($stateCode !== null) {
+            $params['q'] = sprintf('%s,%s', $params['q'], $stateCode);
+            if ($countryCode !== null) {
+                $params['q'] = sprintf('%s,%s', $params['q'], $countryCode);
+            }
+        } else {
+            if ($countryCode !== null) {
+                $params['q'] = sprintf('%s,,%s', $params['q'], $countryCode);
+            }
+        }
+
+        if ($limit !== null) {
+            $params['limit'] = $limit;
+        }
+
+        return sprintf(
+            '%s?%s',
+            $this->coordinatesByLocationNameUrl,
+            http_build_query($params)
+        );
+    }
+
     /**
      * Builds the query string for the url.
      *

Cmfcmf/OpenWeatherMap/Util/City.php

@@ -38,6 +38,16 @@ class City extends Location
      */
     public $country;
 
+    /**
+     * @var string|null The state in which the city is located.
+     */
+    public $state;
+
+    /**
+     * @var array<string,string> An array of internationalised versions of the city's name.
+     */
+    public $localNames = [];
+
     /**
      * @var int The city's population
      */
@@ -58,16 +68,29 @@ class City extends Location
      * @param string $country        The abbreviation of the country the city is located in
      * @param int    $population     The city's population.
      * @param int    $timezoneOffset The shift in seconds from UTC.
+     * @param string $state          The state in which the city is located.
+     * @param array  $localNames     An array of internationalised versions of the city's name.
      *
      * @internal
      */
-    public function __construct($id, $name = null, $lat = null, $lon = null, $country = null, $population = null, $timezoneOffset = null)
-    {
+    public function __construct(
+        $id,
+        $name = null,
+        $lat = null,
+        $lon = null,
+        $country = null,
+        $population = null,
+        $timezoneOffset = null,
+        $state = null,
+        $localNames = []
+    ) {
         $this->id = (int)$id;
         $this->name = isset($name) ? (string)$name : null;
         $this->country = isset($country) ? (string)$country : null;
         $this->population = isset($population) ? (int)$population : null;
         $this->timezone = isset($timezoneOffset) ? new \DateTimeZone(self::timezoneOffsetInSecondsToHours((int)$timezoneOffset)) : null;
+        $this->state = $state ?? null;
+        $this->localNames = $localNames ?? [];
 
         parent::__construct($lat, $lon);
     }

composer.json

@@ -21,6 +21,7 @@
         "ext-json": "*",
         "ext-libxml": "*",
         "ext-simplexml": "*",
+        "mjelamanov/psr18-guzzle": "^1.2",
         "psr/cache": "^1 || ^2 || ^3",
         "psr/http-client": "^1.0",
         "psr/http-factory": "^1.0"