Added W3W provider

README.md

@@ -38,18 +38,18 @@ $ pip install geocoder
 
 ## Providers
 
-| Global        | Country       | Local     | IP Address    | 
-|:--------------|:------------- |:----------|:--------------|
-| ArcGIS        | CanadaPost    | GeoOttawa | FreeGeoIP     |
-| Bing          | Geocoder.ca   |           | MaxMind       |
-| Geonames      |               |           |               |
-| Google        |               |           |               |
-| HERE          |               |           |               |
-| MapQuest      |               |           |               |
-| OpenCage      |               |           |               |
-| OpenStreetMap |               |           |               |
-| TomTom        |               |           |               |
-| Yahoo         |               |           |               |
+| Global        | Country       | Custom     | 
+|:--------------|:------------- |:-----------|
+| ArcGIS        | CanadaPost    | GeoOttawa  |
+| Bing          | Geocoder.ca   | FreeGeoIP  |
+| Geonames      | Baidu         | MaxMind    |
+| Google        |               | what3words |
+| HERE          |               |            |
+| MapQuest      |               |            |
+| OpenCage      |               |            |
+| OpenStreetMap |               |            |
+| TomTom        |               |            |
+| Yahoo         |               |            |
 
 
 

docs/index.md

@@ -1,7 +1,7 @@
 Title:   Python Geocoder API
 Summary: Home page for Geocoder
 Authors: Denis Carriere
-Date:    February 20, 2015
+Date:    February 28, 2015
 base_url: http://geocoder.readthedocs.org
 
 # Geocoder
@@ -44,18 +44,18 @@ $ pip install geocoder
 
 ## Providers
 
-| Global        | Country       | Local     | IP Address    | 
-|:--------------|:------------- |:----------|:--------------|
-| ArcGIS        | CanadaPost    | GeoOttawa | FreeGeoIP     |
-| Bing          | Geocoder.ca   |           | MaxMind       |
-| Geonames      |               |           |               |
-| Google        |               |           |               |
-| HERE          |               |           |               |
-| MapQuest      |               |           |               |
-| OpenCage      |               |           |               |
-| OpenStreetMap |               |           |               |
-| TomTom        |               |           |               |
-| Yahoo         |               |           |               |
+| Global        | Country       | Custom     | 
+|:--------------|:------------- |:-----------|
+| ArcGIS        | CanadaPost    | GeoOttawa  |
+| Bing          | Geocoder.ca   | FreeGeoIP  |
+| Geonames      | Baidu         | MaxMind    |
+| Google        |               | what3words |
+| HERE          |               |            |
+| MapQuest      |               |            |
+| OpenCage      |               |            |
+| OpenStreetMap |               |            |
+| TomTom        |               |            |
+| Yahoo         |               |            |
 
 
 

docs/providers/W3W.md

@@ -0,0 +1,39 @@
+# what3words
+
+what3words is a global grid of 57 trillion 3mx3m squares.
+Each square has a 3 word address that can be communicated quickly,
+easily and with no ambiguity.
+
+> **Addressing the world**
+> Everyone and everywhere now has an address
+
+## Python Example
+
+**Geocoding 3 Words**
+
+```python
+>>> import geocoder
+>>> g = geocoder.w3w('embedded.fizzled.trial')
+>>> g.json
+...
+```
+
+**Reverse Geocoding**
+
+```python
+>>> import geocoder
+>>> g = geocoder.w3w([45.15, -75.14], method='reverse')
+>>> g.json
+...
+```
+
+## Parameters
+
+> :param **location**: Your search location you want geocoded.
+> :param **key**: W3W API key.
+> :param **method**: Chose a method (geocode, method)
+
+## References
+
+<i class="icon-doc"></i> [API Reference](http://developer.what3words.com/)
+<i class="icon-key"></i> [Get W3W key](http://developer.what3words.com/api-register/)

geocoder/__init__.py

@@ -26,14 +26,14 @@
 __title__ = 'geocoder'
 __author__ = 'Denis Carriere'
 __author_email__ = 'carriere.denis@gmail.com'
-__version__ = '1.1.5'
+__version__ = '1.2.0'
 __license__ = 'MIT'
 __copyright__ = 'Copyright (c) 2013-2015 Denis Carriere'
 
 # CORE
 from .api import get, yahoo, bing, geonames, google, mapquest
 from .api import nokia, osm, tomtom, geolytica, arcgis, opencage
-from .api import maxmind, freegeoip, ottawa, here, baidu
+from .api import maxmind, freegeoip, ottawa, here, baidu, w3w
 
 # EXTRAS
 from .api import timezone, elevation, ip, canadapost, reverse

geocoder/api.py

@@ -3,6 +3,7 @@
 
 import sys
 from .osm import Osm
+from .w3w import W3W
 from .bing import Bing
 from .here import Here
 from .yahoo import Yahoo
@@ -20,6 +21,7 @@
 from .geolytica import Geolytica
 from .freegeoip import FreeGeoIP
 from .canadapost import Canadapost
+from .w3w_reverse import W3WReverse
 from .here_reverse import HereReverse
 from .bing_reverse import BingReverse
 from .google_reverse import GoogleReverse
@@ -51,6 +53,10 @@ def get(location, **kwargs):
         'maxmind': {'geocode': Maxmind},
         'geonames': {'geocode': Geonames},
         'freegeoip': {'geocode': FreeGeoIP},
+        'w3w': {
+            'geocode': W3W,
+            'reverse': W3WReverse,
+        },
         'mapquest': {
             'geocode': Mapquest,
             'reverse': MapquestReverse,
@@ -102,6 +108,16 @@ def google(location, **kwargs):
     return get(location, provider='google', **kwargs)
 
 
+def w3w(location, **kwargs):
+    """what3words Provider
+
+    :param location: Your search location you want geocoded.
+    :param key: W3W API key.
+    :param method: Chose a method (geocode, method)
+    """
+    return get(location, provider='baidu', **kwargs)
+
+
 def baidu(location, **kwargs):
     """Baidu Provider
 

geocoder/keys.py

@@ -10,3 +10,4 @@
 opencage_key = '519418b47cfac1f8d435a7f3fda6a7e0'
 mapquest_key = 'Kmjtd|luua2qu7n9,7a=o5-lzbgq'
 baidu_key = 'E4805d16520de693a3fe707cdc962045'
+w3w_key = 'AHWMVNDY'

geocoder/w3w.py

@@ -0,0 +1,74 @@
+#!/usr/bin/python
+# coding: utf8
+
+from .base import Base
+from .keys import w3w_key
+
+
+class W3W(Base):
+    """
+    What3Words
+    ==========
+    What3Words is a global grid of 57 trillion 3mx3m squares.
+    Each square has a 3 word address that can be communicated quickly,
+    easily and with no ambiguity.
+
+    Addressing the world
+
+    Everyone and everywhere now has an address
+
+    Params
+    ------
+    :param location: Your search location you want geocoded.
+    :param key: W3W API key.
+    :param method: Chose a method (geocode, method)
+
+    References
+    ----------
+    API Reference: http://developer.what3words.com/
+    Get W3W key: http://developer.what3words.com/api-register/
+    """
+    provider = 'w3w'
+    method = 'geocode'
+
+    def __init__(self, location, **kwargs):
+        self.url = 'http://api.what3words.com/w3w'
+        self.location = location
+        self.params = {
+            'string': location,
+            'key': kwargs.get('key', w3w_key),
+        }
+        self._initialize(**kwargs)
+
+    @property
+    def lat(self):
+        position = self.parse['position']
+        if position:
+            return position[0]
+
+    @property
+    def lng(self):
+        position = self.parse['position']
+        if position:
+            return position[1]
+
+    @property
+    def position(self):
+        return self.parse.get('position')
+
+    @property
+    def language(self):
+        return self.parse.get('language')
+
+    @property
+    def type(self):
+        return self.parse.get('type')
+
+    @property
+    def words(self):
+        return self.parse.get('words')
+
+if __name__ == '__main__':
+    g = W3W('embedded.fizzled.trial')
+    import json
+    print json.dumps(g.json, indent=4)

geocoder/w3w_reverse.py

@@ -0,0 +1,54 @@
+#!/usr/bin/python
+# coding: utf8
+
+from .base import Base
+from .keys import w3w_key
+from .w3w import W3W
+from .location import Location
+
+
+class W3WReverse(W3W, Base):
+    """
+    what3words
+    ==========
+    what3words is a global grid of 57 trillion 3mx3m squares.
+    Each square has a 3 word address that can be communicated quickly,
+    easily and with no ambiguity.
+
+    Addressing the world
+
+    Everyone and everywhere now has an address
+
+    Params
+    ------
+    :param location: Your search location you want geocoded.
+    :param key: W3W API key.
+    :param method: Chose a method (geocode, method)
+
+    References
+    ----------
+    API Reference: http://developer.what3words.com/
+    Get W3W key: http://developer.what3words.com/api-register/
+    """
+    provider = 'w3w'
+    method = 'reverse'
+
+    def __init__(self, location, **kwargs):
+        self.url = 'http://api.what3words.com/position'
+        location = Location(location)
+        self.location = location.latlng
+        self.params = {
+            'position': self.location,
+            'key': kwargs.get('key', w3w_key),
+        }
+        self._initialize(**kwargs)
+
+    @property
+    def ok(self):
+        return bool(self.words)
+
+if __name__ == '__main__':
+    g = W3WReverse([45.15, -75.14])
+    import json
+    print json.dumps(g.json, indent=4)
+    print g.url

mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: Python Geocoder API
 theme: readthedocs
 Authors: Denis Carriere
-Date: February 20, 2015
+Date: February 28, 2015
 repo_url: https://github.com/DenisCarriere/geocoder
 base_url: http://geocoder.readthedocs.org
 markdown_extensions: ['tables', 'toc', 'meta', 'fenced_code']
@@ -25,6 +25,7 @@ pages:
 
 # Providers
 # =========
+- ['providers/W3W.md', 'Providers', 'what3words']
 - ['providers/Baidu.md', 'Providers', 'Baidu']
 - ['providers/HERE.md', 'Providers', 'HERE']
 - ['providers/ArcGIS.md', 'Providers', 'ArcGIS']

setup.py

@@ -2,7 +2,7 @@
 # coding: utf8
 from setuptools import setup
 
-__version__ = '1.1.5'
+__version__ = '1.2.0'
 requirements_file = "requirements.txt"
 requirements = [pkg.strip() for pkg in open(requirements_file).readlines()]
 

test_geocoder.py

@@ -6,6 +6,7 @@
 
 address = '453 Booth Street, Ottawa'
 location = 'Ottawa, Ontario'
+words = 'embedded.fizzled.trial'
 city = 'Ottawa'
 ip = '74.125.226.99'
 china = '中国'
@@ -17,6 +18,7 @@
 def test_entry_points():
     geocoder.ip
     geocoder.osm
+    geocoder.w3w
     geocoder.bing
     geocoder.here
     geocoder.baidu
@@ -45,6 +47,16 @@ def test_freegeoip():
 """
 
 
+def test_w3w():
+    g = geocoder.w3w(words)
+    assert g.ok
+
+
+def test_w3w_reverse():
+    g = geocoder.w3w(ottawa, method='reverse')
+    assert g.ok
+
+
 def test_maxmind():
     g = geocoder.maxmind(ip)
     assert g.ok