Merge pull request #286 from DenisCarriere/feature_more_providers_upg…

…raded

upgraded freegeoip and geocodefarm

README.md

@@ -142,22 +142,22 @@ $ geocode "Ottawa, ON" \
 | [Baidu][Baidu]                 | China     | API key                         |                 | yes     |           |
 | [Bing][Bing]                   | World     | API key                         | yes             | yes     |           |
 | [CanadaPost][CanadaPost]       | Canada    | API key                         |                 |         |           |
-| [FreeGeoIP][FreeGeoIP]         | World     |                                 |                 |         |           |
+| [FreeGeoIP][FreeGeoIP]         | World     |                                 | N.A             |         |           |
 | [Gaode][Gaode]                 | China     | API key                         |                 | yes     |           |
-| [Geocoder.ca][Geocoder.ca]     | CA & US   | Rate Limit                      |                 |         |           |
-| [GeocodeFarm][GeocodeFarm]     | World     | [Policy][GeocodeFarm-Policy]    |                 | yes     |           |
-| [GeoNames][GeoNames]           | World     | Username                        | yes             |         | yes     |
+| [Geocoder.ca][Geocoder.ca] (Geolytica) | CA & US | Rate Limit                | N.A             |         |           |
+| [GeocodeFarm][GeocodeFarm]     | World     | [Policy][GeocodeFarm-Policy]    | yes             | yes     |           |
+| [GeoNames][GeoNames]           | World     | Username                        | yes             |         | yes       |
 | [GeoOttawa][GeoOttawa]         | Ottawa    |                                 |                 |         |           |
-| [Google][Google]               | World     | Rate Limit, [Policy][Google-Policy] | yes         | yes     | yes     |
-| [HERE][HERE]                   | World     | API key                         |                 | yes     |           |
-| [IPInfo][IPInfo]               | World     | [Paid Plans][IPinfo-paidPlans]  |                 |       |           |
-| [Mapbox][Mapbox]               | World     | API key                         | yes             | yes     | yes     |
+| [Google][Google]               | World     | Rate Limit, [Policy][Google-Policy] | yes         | yes     | yes       |
+| [HERE][HERE]                   | World     | API key                         | yes             | yes     |           |
+| [IPInfo][IPInfo]               | World     | Rate Limit, [Paid Plans][IPinfo-paidPlans] | N.A  |         |           |
+| [Mapbox][Mapbox]               | World     | API key                         | yes             | yes     | yes       |
 | [MapQuest][MapQuest]           | World     | API key                         | yes             | yes     |           |
 | [Mapzen][Mapzen]               | World     | API key                         |                 | yes     |           |
 | [MaxMind][MaxMind]             | World     |                                 |                 |         |           |
 | [OpenCage][OpenCage]           | World     | API key                         |                 | yes     |           |
 | [OpenStreetMap][OpenStreetMap] | World     | [Policy][OpenStreetMap-Policy]  | yes             | yes     |           |
-| [Tamu][Tamu]                   | US        | API key                         |                 |         |           |
+| [Tamu][Tamu]                   | US        | API key                         | N.A             |         |           |
 | [TomTom][TomTom]               | World     | API key                         |                 |         |           |
 | [What3Words][What3Words]       | World     | API key                         | N.A             | yes     |           |
 | [Yahoo][Yahoo]                 | World     |                                 |                 |         |           |
@@ -241,4 +241,4 @@ Please feel free to give any feedback on this module. If you find any bugs or an
 [GeocodeFarm]: https://geocode.farm/
 [GeocodeFarm-Policy]: https://geocode.farm/geocoding/free-api-documentation/
 [Gaode]: http://geocoder.readthedocs.org/providers/Gaode.html
-[IPinfo-paidPlans]: http://ipinfo.io/pricing
+[IPinfo-paidPlans]: http://ipinfo.io/pricing

docs/providers/GeocodeFarm.rst

@@ -20,6 +20,8 @@ Geocoding
     >>> g.json
     ...
 
+This provider may return multiple results. You can access those results as described in the page ':doc:`/results`'.
+
 Reverse Geocoding
 ~~~~~~~~~~~~~~~~~
 
@@ -54,6 +56,7 @@ Parameters
 - `key`: (optional) API Key. Only Required for Paid Users.
 - `lang`: (optional) 2 digit lanuage code to return results in. Currently only "en"(English) or "de"(German) supported.
 - `country`: (optional) The country to return results in. Used for biasing purposes and may not fully filter results to this specific country.
+- `maxRows`: (default=1) Max number of results to fetch
 - `method`: (default=geocode) Use the following:
 
   - geocode

docs/providers/HERE.rst

@@ -15,6 +15,8 @@ Geocoding
     >>> g.json
     ...
 
+This provider may return multiple results by setting the parameter `maxRows` to the desired number (1 by default). You can access those results as described in the page ':doc:`/results`'.
+
 Reverse Geocoding
 ~~~~~~~~~~~~~~~~~
 
@@ -62,6 +64,7 @@ Parameters
 - `location`: Your search location you want geocoded.
 - `app_code`: (optional) use your own Application Code from HERE.
 - `app_id`: (optional) use your own Application ID from HERE.
+- `maxRows`: (default=1) Max number of results to fetch
 - `method`: (default=geocode) Use the following:
 
   - geocode

docs/wip_guide.rst

@@ -113,6 +113,9 @@ Let's detail those three steps
         _URL = 'http://www.mapquestapi.com/geocoding/v1/address'
         _RESULT_CLASS = MapquestResult
         _KEY = mapquest_key
+        _KEY_MANDATORY = True
+
+    Because the default implementation expects an API Key, you will need to set _KEY_MANDATORY to False if no API Key is required
 
 * (**Query**) In order to make the query: the initialization of the params & headers is not done neither in the constructor anymore but in the appropriated hooks. As you can see, `location` and `provider_key` are passed through::
 
@@ -152,10 +155,14 @@ Let's detail those three steps
             return results[0]['locations']
         return []
 
-* (**Parsing**) In the cases where you are interested in some fields in the `json_response`, additionnaly to the results, you might want to override `_parse_results`. There is one example so far with GooglePlaces, where the `next_page_token` interests us::
+* (**Parsing**) In the cases where you are interested in some fields in the `json_response`, additionnaly to the results, you might want to override `_parse_results`. In which case you should also declare the new attribute in your child class. There is one example with GooglePlaces, where the `next_page_token` interests us::
 
     class PlacesQuery(MultipleResultsQuery):
 
+        def __init__(self, location, **kwargs):
+            super(PlacesQuery, self).__init__(location, **kwargs)
+            self.next_page_token = None
+
         ...
 
         def _parse_results(self, json_response):

geocoder/api.py

@@ -8,8 +8,8 @@
 from geocoder.osm import OsmQuery
 from geocoder.w3w import W3WQuery
 from geocoder.bing import BingQuery
-from geocoder.here import Here
-from geocoder.tamu import Tamu
+from geocoder.here import HereQuery
+from geocoder.tamu import TamuQuery
 from geocoder.tgos import Tgos
 from geocoder.yahoo import Yahoo
 from geocoder.baidu import Baidu
@@ -19,7 +19,7 @@
 from geocoder.yandex import Yandex
 from geocoder.mapbox import MapboxQuery
 from geocoder.mapzen import Mapzen
-from geocoder.ipinfo import Ipinfo
+from geocoder.ipinfo import IpinfoQuery
 from geocoder.komoot import Komoot
 from geocoder.maxmind import Maxmind
 from geocoder.location import Location
@@ -30,10 +30,10 @@
 from geocoder.geonames_hierarchy import GeonamesHierarchy
 from geocoder.mapquest import MapquestQuery
 from geocoder.distance import Distance
-from geocoder.geolytica import Geolytica
-from geocoder.freegeoip import FreeGeoIP
+from geocoder.geolytica import GeolyticaQuery
+from geocoder.freegeoip import FreeGeoIPQuery
 from geocoder.canadapost import Canadapost
-from geocoder.geocodefarm import GeocodeFarm
+from geocoder.geocodefarm import GeocodeFarmQuery
 from geocoder.uscensus import USCensus
 from geocoder.baidu_reverse import BaiduReverse
 from geocoder.w3w_reverse import W3WReverse
@@ -66,7 +66,7 @@
         'geocode': Tgos
     },
     'here': {
-        'geocode': Here,
+        'geocode': HereQuery,
         'reverse': HereReverse,
     },
     'baidu': {
@@ -89,15 +89,15 @@
         'reverse': MapboxReverse,
     },
     'maxmind': {'geocode': Maxmind},
-    'ipinfo': {'geocode': Ipinfo},
+    'ipinfo': {'geocode': IpinfoQuery},
     'geonames': {
         'geocode': GeonamesQuery,
         'details': GeonamesDetails,
         'timezone': GeonamesDetails,
         'children': GeonamesChildren,
         'hierarchy': GeonamesHierarchy
     },
-    'freegeoip': {'geocode': FreeGeoIP},
+    'freegeoip': {'geocode': FreeGeoIPQuery},
     'w3w': {
         'geocode': W3WQuery,
         'reverse': W3WReverse,
@@ -110,7 +110,7 @@
         'geocode': MapquestQuery,
         'reverse': MapquestReverse,
     },
-    'geolytica': {'geocode': Geolytica},
+    'geolytica': {'geocode': GeolyticaQuery},
     'canadapost': {'geocode': Canadapost},
     'opencage': {
         'geocode': OpenCage,
@@ -136,10 +136,10 @@
         'reverse': KomootReverse,
     },
     'tamu': {
-        'geocode': Tamu
+        'geocode': TamuQuery
     },
     'geocodefarm': {
-        'geocode': GeocodeFarm,
+        'geocode': GeocodeFarmQuery,
         'reverse': GeocodeFarmReverse,
     },
     'uscensus': {
@@ -375,6 +375,7 @@ def here(location, **kwargs):
     :param ``location``: Your search location you want geocoded.
     :param ``app_code``: (optional) use your own Application Code from HERE.
     :param ``app_id``: (optional) use your own Application ID from HERE.
+    :param ``maxRows``: (default=1) Max number of results to fetch
     :param ``method``: (default=geocode) Use the following:
         > geocode
         > reverse
@@ -541,6 +542,7 @@ def geocodefarm(location, **kwargs):
     :param ``key``: (optional) API Key. Only Required for Paid Users.
     :param ``lang``: (optional) 2 digit language code to return results in. Currently only "en"(English) or "de"(German) supported.
     :param ``country``: (optional) The country to return results in. Used for biasing purposes and may not fully filter results to this specific country.
+    :param ``maxRows``: (default=1) Max number of results to fetch
 
     API Reference
     -------------

geocoder/arcgis.py

@@ -59,11 +59,7 @@ class ArcgisQuery(MultipleResultsQuery):
 
     _URL = 'https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find'
     _RESULT_CLASS = ArcgisResult
-
-    @classmethod
-    def _get_api_key(cls, key=None):
-        # No API KEY for OSM
-        return None
+    _KEY_MANDATORY = False
 
     def _build_params(self, location, provider_key, **kwargs):
         # backward compatitibility for 'limit' (now maxRows)

geocoder/base.py

@@ -659,6 +659,7 @@ class MultipleResultsQuery(MutableSequence):
     _URL = None
     _RESULT_CLASS = None
     _KEY = None
+    _KEY_MANDATORY = True
     _TIMEOUT = 5.0
 
     @staticmethod
@@ -683,7 +684,7 @@ def _get_api_key(cls, key=None):
         key = key or cls._KEY
 
         # raise exception if not valid key found
-        if not key:
+        if not key and cls._KEY_MANDATORY:
             raise ValueError('Provide API Key')
 
         return key
@@ -813,18 +814,19 @@ def _connect(self):
             )
 
             # check that response is ok
+            self.status_code = response.status_code
             response.raise_for_status()
-            self.status_code = 200
 
             # rely on json method to get non-empty well formatted JSON
             json_response = response.json()
             self.url = response.url
             LOGGER.info("Requested %s", self.url)
 
-        except requests.exceptions.RequestException:
+        except requests.exceptions.RequestException as err:
             # store real status code and error
-            self.status_code = response.status_code
-            self.error = u'ERROR - {}'.format(str(response))
+            self.error = u'ERROR - {}'.format(str(err))
+            LOGGER.error("Status code %s from %s: %s",
+                         self.status_code, self.url, self.error)
 
             # return False
             return False