Implemented Geocoding API support - fixes #364

csparpa · csparpa · commit 6731479d40c5 · 2021-01-31T22:17:48.000+01:00
diff --git a/README.md b/README.md
@@ -32,6 +32,7 @@ With PyOWM you can integrate into your code any of the following OpenWeatherMap
  - **Stations API v3.0**, allowing to create and manage meteostation and publish local weather measurements
  - **Weather Alerts API v3.0**, allowing to set triggers on weather conditions and areas and poll for spawned alerts
  - **Image tiles** for several map layers provided by OWM
+ - **Geocoding API v1.0** allowing to perform direct/reverse geocoding 
 
  ##  Get started
 
diff --git a/pyowm/commons/uris.py b/pyowm/commons/uris.py
@@ -0,0 +1,7 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+ROOT_GEOCODING_API_URL = 'openweathermap.org/geo/1.0'
+DIRECT_GEOCODING_URI = 'direct'
+REVERSE_GEOCODING_URI = 'reverse'
+
diff --git a/pyowm/constants.py b/pyowm/constants.py
@@ -5,6 +5,7 @@
 AGRO_API_VERSION = (1, 0, 0)
 AIRPOLLUTION_API_VERSION = (3, 0, 0)
 ALERT_API_VERSION = (3, 0, 0)
+GEOCODING_API_VERSION = (1, 0, 0)
 STATIONS_API_VERSION = (3, 0, 0)
 UVINDEX_API_VERSION = (3, 0, 0)
 WEATHER_API_VERSION = (2, 5, 0)
diff --git a/pyowm/geocodingapi10/__init__.py b/pyowm/geocodingapi10/__init__.py
diff --git a/pyowm/geocodingapi10/geocoding_manager.py b/pyowm/geocodingapi10/geocoding_manager.py
@@ -0,0 +1,85 @@
+from pyowm.commons.http_client import HttpClient
+from pyowm.commons.uris import ROOT_GEOCODING_API_URL, DIRECT_GEOCODING_URI, REVERSE_GEOCODING_URI
+from pyowm.constants import GEOCODING_API_VERSION
+from pyowm.utils import geo
+from pyowm.weatherapi25.location import Location
+
+
+class GeocodingManager:
+
+    """
+    A manager objects that provides a full interface to OWM Geocoding API.
+
+    :param API_key: the OWM API key
+    :type API_key: str
+    :param config: the configuration dictionary
+    :type config: dict
+    :returns: an *GeocodingManager* instance
+    :raises: *AssertionError* when no API Key is provided
+
+    """
+
+    def __init__(self, API_key, config):
+        assert API_key is not None, 'You must provide a valid API Key'
+        self.API_key = API_key
+        assert isinstance(config, dict)
+        self.http_client = HttpClient(API_key, config, ROOT_GEOCODING_API_URL)
+
+    def geocoding_api_version(self):
+        return GEOCODING_API_VERSION
+
+    def geocode(self, toponym, country=None, state_code=None, limit=None):
+        """
+        Invokes the direct geocoding API endpoint
+
+        :param toponym: the name of the location
+        :type toponym: `str`
+        :param country: the 2-chars ISO symbol of the country
+        :type country: `str` or `None`
+        :param state_code: the 2-chars ISO symbol of state (only useful in case the country is US)
+        :type state_code: `str` or `None`
+        :param limit: the max number of results to be returned in case of multiple matchings (no limits by default)
+        :type limit: `int` or `None`
+        :returns: a list of *Location* instances
+        :raises: *AssertionError*, *ValueError*, *APIRequestError*
+
+        """
+        assert toponym, 'Toponym must be specified'
+        if country is not None and len(country) != 2:
+            raise ValueError("Country must be a 2-char string")
+        if state_code is not None and len(state_code) != 2:
+            raise ValueError("State Code must be a 2-char string")
+        if limit is not None:
+            assert isinstance(limit, int)
+            assert limit > 0
+
+        query = toponym
+        if state_code is not None:
+            query += ',' + state_code
+        if country is not None:
+            query += ',' + country
+
+        params = {'q': query}
+
+        if limit is not None:
+            params['limit'] = limit
+
+        _, json_data = self.http_client.get_json(DIRECT_GEOCODING_URI, params=params)
+        return [Location.from_dict(item) for item in json_data]
+
+    def reverse_geocode(self, lat, lon, limit=None):
+        geo.assert_is_lon(lon)
+        geo.assert_is_lat(lat)
+        if limit is not None:
+            assert isinstance(limit, int)
+            assert limit > 0
+
+        params = {'lat': lat, 'lon': lon}
+        if limit is not None:
+            params['limit'] = limit
+
+        _, json_data = self.http_client.get_json(REVERSE_GEOCODING_URI, params=params)
+        return [Location.from_dict(item) for item in json_data]
+
+    def __repr__(self):
+        return '<%s.%s>' % (__name__, self.__class__.__name__)
diff --git a/pyowm/owm.py b/pyowm/owm.py
@@ -5,6 +5,7 @@
 from pyowm.agroapi10 import agro_manager
 from pyowm.airpollutionapi30 import airpollution_manager
 from pyowm.alertapi30 import alert_manager
+from pyowm.geocodingapi10 import geocoding_manager
 from pyowm.stationsapi30 import stations_manager
 from pyowm.tiles import tile_manager
 from pyowm.utils import strings
@@ -125,6 +126,14 @@ def weather_manager(self):
         """
         return weather_manager.WeatherManager(self.api_key, self.config)
 
+    def geocoding_manager(self):
+        """
+        Gives a `pyowm.geocoding10.geocoding_manager.GeocodingManager` instance that can be used to perform direct
+        and reverse geocoding
+        :return: a `pyowm.geocoding10.geocoding_manager.GeocodingManager` instance
+        """
+        return geocoding_manager.GeocodingManager(self.api_key, self.config)
+
     def __repr__(self):
         return "<%s.%s - API key=%s, subscription type=%s, PyOWM version=%s>" % \
                     (__name__,
diff --git a/pyowm/weatherapi25/location.py b/pyowm/weatherapi25/location.py
@@ -83,6 +83,9 @@ def from_dict(cls, the_dict):
             else:
                 lon = 0.0
             lat = data['station']['coord'].get('lat', 0.0)
+        elif 'lat' in the_dict and 'lon' in the_dict:
+            lat = the_dict['lat']
+            lon = the_dict['lon']
         else:
             raise KeyError("Impossible to read geographical coordinates from JSON")
         if 'country' in data:
diff --git a/sphinx/index.rst b/sphinx/index.rst
@@ -37,6 +37,7 @@ With PyOWM you can interact programmatically with the following OpenWeatherMap w
  - **UV Index API v3.0**, offering data about Ultraviolet exposition
  - **Stations API v3.0**, allowing to create and manage meteostation and publish local weather measurements
  - **Weather Alerts API v3.0**, allowing to set triggers on weather conditions and areas and poll for spawned alerts
+ - **Geocoding API v1.0** allowing to perform direct/reverse geocoding
 
 And you can also get **image tiles** for several map layers provided by OWM
 
@@ -183,6 +184,15 @@ Alerts API examples
 
    v3/alerts-api-usage-examples
 
+Geocoding API examples
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+
+   v3/geocoding-api-usage-examples
+
+
 Map tiles client examples
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 .. toctree::
diff --git a/sphinx/pyowm.geocodingapi10.rst b/sphinx/pyowm.geocodingapi10.rst
@@ -0,0 +1,13 @@
+pyowm.geocodingapi10 package
+============================
+
+Submodules
+----------
+
+pyowm.geocodingapi10.geocoding_manager module
+---------------------------------------------
+
+.. automodule:: pyowm.geocodingapi10.geocoding_manager
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/sphinx/pyowm.rst b/sphinx/pyowm.rst
@@ -10,6 +10,7 @@ Subpackages
     pyowm.alertapi30
     pyowm.commons
     pyowm.airpollutionapi30
+    pyowm.geocodingapi10
     pyowm.stationsapi30
     pyowm.tiles
     pyowm.utils
diff --git a/sphinx/v3/code-recipes.md b/sphinx/v3/code-recipes.md
@@ -130,17 +130,24 @@ version_tuple = (major, minor, patch) = owm.version
 
 <div id="identifying_places"/>
 
-## Identifying cities and places via city IDs
+## Identifying cities and places
 
-### Obtain the city ID registry
+You can easily get the City ID of a known toponym, as well as its geographic coordinates
+Also you can leverage direct/reverse geocoding 
+
+### City IDs
+
+The following calls will not result in any OWM API call in the background, so they will only happen locally to your machine.
+
+#### Obtain the city ID registry
 Use the city ID registry to lookup the ID of a city given its name
 ```python
 from pyowm.owm import OWM
 owm = OWM('your-api-key')
 city_id_registry = owm.city_id_registry()
 ```
 
-### Get the ID of a city given its name
+#### Get the ID of a city given its name
 Don't forget that there is a high probabilty that your city is not unique in the world, and multiple cities with the same name exist in other countries
 Therefore specify toponyms and country 2-letter names separated by comma. Eg: if you search for the British `London` you'll likely multiple results: 
 you then should also specify the country (`GB`) to narrow the search only to Great Britain.
@@ -165,9 +172,8 @@ list_of_tuples = london = reg.ids_for('LoNdoN', country='GB')                 #
 and would get the very same results as above.
 
 
-### Get the IDs of cities whose name contain a specific string
-
-In order yo find all cities with names having your string as a substring you need to use the optional parameter `matching='like'`
+#### Get the IDs of cities whose name contain a specific string
+In order to find all cities with names having your string as a substring you need to use the optional parameter `matching='like'`
 
 In example, let's find IDs for all British cities having the string `london` in their names:
 
@@ -182,7 +188,7 @@ list_of_tuples = reg.ids_for('london', country='GB', matching='like')  # We'll g
                                                                        #            (2643734, 'Londonderry County Borough', 'GB')]
 ```
 
-### Get geographic coordinates of a city given its name
+#### Get geographic coordinates of a city given its name
 Just use call `locations_for` on the registry: this will give you a `Location` object containing lat & lon
 
 Let's find geocoords for Moscow (Russia):
@@ -197,7 +203,7 @@ lat = moscow.lat   # 55.75222
 lon = moscow.lon   # 37.615555
 ```
 
-### Get GeoJSON geometry (point) for a city given its name
+#### Get GeoJSON geometry (point) for a city given its name
 PyOWM encapsulates [GeoJSON](https://pypi.org/project/geojson/) geometry objects that are compliant with the GeoJSON specification.
 
 This means, for example, that you can get a `Point` geometry using the registry. Let's find the geometries for all `Rome` cities in the world:
@@ -209,6 +215,65 @@ reg = owm.city_id_registry()
 list_of_geopoints = reg.geopoints_for('rome')
 ```
 
+### Direct/reverse geocoding
+
+Simply put:
+  - DIRECT GEOCODING: from toponym to geocoords
+  - REVERSE GEOCODING: from geocoords to toponyms
+
+
+Both geocoding actions are performed via a `geocoding_manager` object and will require an actual call to be made to the
+OWM API: so please bear that in mind because that will count against your amount of allowed API calls
+
+#### Direct gecocoding of a toponym
+
+The call is very similar to `ids_for` and `locations_for`.
+
+You at least need to specify the toponym name and country ISO code (eg. `GB`, `IT`, `JP`, ...), while if the input 
+toponym is in the United States you should also specify the `state_code` parameter 
+
+The call returns a list of `Location` object instances (in case of no ambiguity, only one item in the list will be returned)
+You can then get the lat/lon from the object instances themselves
+
+Results can be limited with the `limit` parameter
+
+```python
+from pyowm.owm import OWM
+owm = OWM('your-api-key')
+mgr = owm.geocoding_manager()
+
+# geocode London (no country specified) - we'll get many results
+list_of_locations = mgr.geocode('London')
+a_london = list_of_locations[0]  # taking the first London in the list
+a_london.lat
+a_london.lon 
+
+# geocode London (Great Britain) - we'll get up to three Londons that exist in GB
+list_of_locations = mgr.geocode('London', country='GB', limit=3)
+
+# geocode London (Ohio, United States of America): we'll get all the Londons in Ohio
+list_of_locations = mgr.geocode('London', country='US', state_code='OH')
+```
+
+#### Reverse gecocoding of geocoordinates
+With reverse geocoding you input a lat/lon float couple and retrieve a list all the `Location` objects associated with 
+these coordinates.
+
+Results can be limited with the `limit` parameter
+
+```python
+from pyowm.owm import OWM
+owm = OWM('your-api-key')
+mgr = owm.geocoding_manager()
+
+# London
+lat = 51.5098
+lon = -0.1180
+
+# reverse geocode London
+list_of_locations = mgr.reverse_geocode(lat, lon)  # list contains: City of London, Islington, Lewisham, ...
+```
+
 
 <div id="onecall"/>
 
diff --git a/sphinx/v3/geocoding-api-usage-examples.md b/sphinx/v3/geocoding-api-usage-examples.md
@@ -0,0 +1,8 @@
+# Geocoding API usage examples
+
+The OWM Weather API gives you the possibility to perform direct and reverse geocoding:
+  - DIRECT GEOCODING: from toponym to geocoords
+  - REVERSE GEOCODING: from geocoords to toponyms
+
+
+Please refer to the `Code Recipes` page, sections: `Direct/reverse geocoding`
diff --git a/tests/integration/geocodingapi10/__init__.py b/tests/integration/geocodingapi10/__init__.py
diff --git a/tests/integration/geocodingapi10/test_integration_geocodingapi10.py b/tests/integration/geocodingapi10/test_integration_geocodingapi10.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import unittest
+import os
+from pyowm import owm
+from pyowm.weatherapi25.location import Location
+
+
+class IntegrationTestsGeocodingAPI(unittest.TestCase):
+
+    __owm = owm.OWM(os.getenv('OWM_API_KEY', None))
+
+    def test_geocode(self):
+        mgr = self.__owm.geocoding_manager()
+
+        # Geocode all Paris in the United States
+        locations = mgr.geocode('Paris', 'US')
+        self.assertTrue(isinstance(locations, list))
+        self.assertTrue(all([isinstance(l, Location) for l in locations]))
+        self.assertTrue(all([l.name == 'Paris' and l.country == 'US' for l in locations]))
+
+    def test_reverse_geocode(self):
+        mgr = self.__owm.geocoding_manager()
+
+        # Reverse geocode the geocoords for Florence (Italy)
+        locations = mgr.reverse_geocode(43.783731, 11.246603)
+        self.assertTrue(isinstance(locations, list))
+        self.assertTrue(all([isinstance(l, Location) for l in locations]))
+        self.assertTrue(all([l.name == 'Firenze' and l.country == 'IT' for l in locations]))
+
diff --git a/tests/unit/geocodingapi10/__init__.py b/tests/unit/geocodingapi10/__init__.py
diff --git a/tests/unit/geocodingapi10/geocoding_manager.py b/tests/unit/geocodingapi10/geocoding_manager.py
diff --git a/tests/unit/test_owm.py b/tests/unit/test_owm.py
