Merge pull request #274 from DenisCarriere/bbox_documentation

Bbox documentation

docs/providers/Bing.rst

@@ -49,6 +49,7 @@ Parameters
 
 - `location`: Your search location you want geocoded.
 - `key`: use your own API Key from Bing.
+- `maxRows`: (default=1) Max number of results to fetch
 - `method`: (default=geocode) Use the following:
 
   - geocode

docs/providers/GeoNames.rst

@@ -3,9 +3,9 @@ GeoNames
 
 GeoNames is mainly using REST APIs. It offers 40 different webservices, listed with examples in its `overview <http://www.geonames.org/export/ws-overview.html>`_
 
-Geocoder provides you with various methods for different purposes:
+Geocoder supports the following ones:
 
-- (geocode) retrieve GeoNames's geocoded data from a query string, and various filters
+- (geocoding) retrieve GeoNames's geocoded data from a query string, and various filters
 - (details) retrieve all geonames data for a given *geonames_id*
 - (children) retrieve the hierarchy of a given *geonames_id*
 - (hierarchy) retrieve all children for a given *geonames_id*
@@ -52,51 +52,41 @@ They are all supported
     >>> g.population
     19274244
 
-Proximity
----------
 
-Geomanes allows the extra parameters 'east', 'west', 'north', 'south' to restrict the query to the therefore defined box. They provide the functionnality 'proximity' that can be found on some other providers (e.g Mapbox)
+Multiple filters for some parameters
+------------------------------------
 
+As pointed out in Geonames specs, the search (geocoding) service accepts multiple values for some parameters, namingly:
 
-.. code-block:: python
+- country
+- featureClass
+- featureCode
 
-    >>> g = geocoder.geonames('Paris', key='<USERNAME>', east=-96.0, west=-95.0, north=33.5, south=33.0)
-    >>> g.address
-    'Kosciusko'
-    >>> g.country
-    'United States'
-
-
-For consistency purpose, geocoder also accepts a 'bbox' parameter. Follows an example where google provider is used first, and the resulting bbox is passed to make a query to geonames:
+This is also supported by Geocoder, which will expect an array instead of the normal string.
 
 
 .. code-block:: python
 
-    >>> location = 'Ontario, Ottawa'
-    >>> google_result = geocoder.google(location, key='YOUR KEY')
-    >>> google_result.address
-    'Ottawa, ON, Canada'
-    >>> google_result.bbox
-    {'northeast': [45.5375801, -75.2465979], 'southwest': [44.962733, -76.35391589999999]}
-    >>> g = geocoder.geonames(location, key='YOUR USERNAME', bbox=google_result.bbox)
-    >>> g.address
-    'Ottawa'
-
+    >>> g = geocoder.geonames('Paris', maxRows=5, country=['FR', 'US'], key='<USERNAME>')
+    >>> print([(r.address, r.country) for r in g])
+    [('Paris', 'France'), ('Paris', 'United States'), ('Paris', 'France'), ('Paris', 'United States'), ('Paris', 'United States')]
 
-Multiple values for some parameters
------------------------------------
 
-As pointed out in Geonames specs, the search (geocoding) service accepts multiple values for some parameters (e.g. 'country', 'featureClass' and 'featureCode')
+Proximity
+---------
 
+As mentioned above, Geomanes allows the extra parameters 'east', 'west', 'north', 'south' to restrict the query to the therefore defined box. 
 
-This is also supported by Geocoder, which will expect in these cases an array instead of the normal string.
+.. code-block:: python
 
+    >>> g = geocoder.geonames('Paris', key='<USERNAME>', east=-96.0, west=-95.0, north=33.5, south=33.0)
+    >>> g.address
+    'Kosciusko'
+    >>> g.country
+    'United States'
 
-.. code-block:: python
 
-    >>> g = geocoder.geonames('Paris', key='<USERNAME>', maxRows=5, country=['FR', 'US'])
-    >>> print([(r.address, r.country) for r in g])
-    [('Paris', 'France'), ('Paris', 'United States'), ('Paris', 'France'), ('Paris', 'United States'), ('Paris', 'United States')]
+For consistency purpose, geocoder also accepts a 'proximity' parameter, which can be a bbox, bounds or a dictionnary with all directions. Please refer to the page ':doc:`/results`' for more details.
 
 
 Details (inc. timezone, bbox)
@@ -167,7 +157,7 @@ This method requires a valid *geonames_id*, which you can get with the geocode m
 Children and Hierarchy
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-These two web services expect a geonames_id, which means you first need to make geocode your location. They will return multiple results most of the time, which you can access as described in the :ref:`results page <results>`.
+These two web services expect a *geonames_id*, which means you first need to make geocode your location. They will return multiple results most of the time, which you can access as described in the page ':doc:`/results`'.
 
 .. code-block:: python
 
@@ -200,16 +190,20 @@ To make sure your API key is store safely on your computer, you can define that
 Parameters
 ----------
 
-- `location`: Your search location you want geocoded.
-- `key`: (required) geonames *username" needs to be passed with each request.
+- `location`: Your search location you want **geocoded**.
+- `geonameid`: The place you want **details** / **children** / **hierarchy** for.
+- `key`: (required) geonames *username* needs to be passed with each request.
+- `maxRows`: (default=1) Max number of results to fetch
+- `proximity`: Search within given area (bbox, bounds, or around latlng)
 - `method`: (default=geocode) Use the following:
 
   - geocode
-  - details
-  - timezone
+  - details (mainly for administrive data and timezone)
+  - timezone (alias of details)
   - children
   - hierarchy
 
+
 References
 ----------
 

docs/providers/Google.rst

@@ -113,6 +113,7 @@ Parameters
 - `language`: 2-letter code of preferred language of returned address elements.
 - `client`: Google for Work client ID. Use with client_secret. Cannot use with key parameter
 - `client_secret`: Google for Work client secret. Use with client.
+- `proximity`: Search within given area (bbox, bounds, or around latlng)
 - `method`: (default=geocode) Use the following:
 
   - geocode

docs/providers/MapQuest.rst

@@ -47,6 +47,7 @@ Parameters
 ----------
 
 - `location`: Your search location you want geocoded.
+- `maxRows`: (default=1) Max number of results to fetch
 - `method`: (default=geocode) Use the following:
 
   - geocode

docs/providers/Mapbox.rst

@@ -41,6 +41,9 @@ Request feature data that best matches input and is biased to the given {latitud
     "200 Queen St W, Toronto, M5T 1T9, Ontario, Canada"
     ...
 
+For consistency purpose, geocoder also accepts other formats for the 'proximity' parameter, which could be a bbox, bounds or a dictionnary with all directions. Please refer to teh page ':doc:`/results`' for more details.
+
+
 Command Line Interface
 ----------------------
 
@@ -65,6 +68,7 @@ Parameters
 - `proximity`: Search nearby [lat, lng].
 - `key`: Use your own access token from Mapbox.
 - `country`: Filtering by country code {cc} ISO 3166 alpha 2.
+- `proximity`: Search within given area (bbox, bounds, or around latlng)
 - `method`: (default=geocode) Use the following:
 
   - geocode

docs/results.rst

@@ -1,8 +1,8 @@
 Access to geocoder results
 ==========================
 
-Work In Progress
-~~~~~~~~~~~~~~~~
+[WIP] Multiple results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As for now, Geocoder always returns one result: the best match according to the queried provider.
 
@@ -18,7 +18,7 @@ As for now, Geocoder always returns one result: the best match according to the
     ...
 
 
-A **Work** is **In Progress** to support multiple results (you will find which providers support this feature on the `README file <https://github.com/DenisCarriere/geocoder/blob/master/README.md>`_). 
+A **Work** is **In Progress** to support multiple results (you will find which providers support this feature on the `README file <https://github.com/DenisCarriere/geocoder/blob/master/README.md>`_).
 
 Simply add *maxRows* in your query:
 
@@ -42,7 +42,7 @@ Extending without breaking
 The objective is to allow access to multiple results, without breaking the lib, neither adding to much complexity.
 
 - all existing API calls shoul continue to Work
-- access to all restults should be easy
+- access to all results should be easy
 
 .. code-block:: python
 
@@ -76,7 +76,6 @@ Note that the API calls are done on the best match from the provider, but you ca
     >>> g.address
     'Best Western Plus Mountainview Inn and Suites'
 
-
 "Breaking" change
 -----------------
 
@@ -131,7 +130,7 @@ Instead, the *geojson* property will apply to **all** results, therefore returni
 More ?
 ------
 
-The returned object *g* is a `MutableSequence (python >3.3) <https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSequence>`_ because you might be interested in the actual order of the results given back by the provider, e.g. when querying the its hierarchy:
+The returned object *g* is a `MutableSequence (python >= 3.3) <https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSequence>`_ because you might be interested in the actual order of the results given back by the provider, e.g. when querying the its hierarchy:
 
 .. code-block:: python
 
@@ -147,3 +146,87 @@ The returned object *g* is a `MutableSequence (python >3.3) <https://docs.python
     California ['37.25022', '-119.75126']
     Santa Clara County ['37.23249', '-121.69627']
     Mountain View ['37.38605', '-122.08385']
+
+BBox & Bounds
+~~~~~~~~~~~~~
+
+Overview
+--------
+
+Some Geocoder results will contain a BBox/Bounds of the geographical extent of the result.
+There are two different widely adopted formats:
+
+- `Bounds`: 
+    An Object defined which was first implemented by **Google Maps API** and adopted by many other providers such as Leaflet.
+
+    .. code-block:: python
+
+        {
+            northeast: [north, east],
+            southwest: [south, west]
+        }
+
+
+- `BBox`:
+    An Array of 4 numbers which follows the **GeoJSON** BBox specification.
+
+    .. code-block:: python
+
+        [west, south, east, north]
+
+The major difference between both is the coordinates are flipped (LatLng => LngLat).
+
+How to use 
+----------
+
+BBox or Bounds can be used in geocoding queries to limit the search to the given area. The two formats are accepted.
+
+Let's look at a basic search for 'Paris'
+
+.. code-block:: python
+
+    >>> import geocoder
+    >>> g = geocoder.geonames('Paris', maxRows=3, key='<USERNAME>')
+    >>> print([(r.address, r.country, r.latlng) for r in g])
+    [ ('Paris', 'France', ['48.85341', '2.3488']), 
+      ('Paris', 'United States', ['33.66094', '-95.55551']), 
+      ('Paris', 'Denmark', ['56.51417', '8.48996'])]
+
+Now, if you are **not** interested in any of those matches, you might have an hard time to find yours. That's where proximity comes into play.
+
+Let's assume for the sake of this example that you are seeking 'Paris' nearby [43.2, -80.3]. You just need to define your bbox, or your bounds, and use the 'proximity' parameter...
+
+
+.. code-block:: python
+
+    >>> bounds = {
+            'southwest': [43.0, -80.5],
+            'northeast': [43.5, -80.0]
+        }
+    >>> g = geocoder.geonames('Paris', proximity=bounds, key='<USERNAME>')
+    >>> print([g.address, g.country, g.latlng])
+    ['Paris', 'Canada', ['43.2001', '-80.38297']]
+
+    # let's do the same with bounds
+    >>> bbox = [-80.5, 43.0, -80.0, 43.5]
+    >>> g = geocoder.geonames('Paris', proximity=bbox, key='<USERNAME>')
+    >>> print([g.address, g.country, g.latlng])
+    ['Paris', 'Canada', ['43.2001', '-80.38297']]
+
+Actually, you can even just use a couple of (lat, lng) and the box will be created with a tolerance of 0.5 degrees in the four directions (west, south, east, north)
+
+.. code-block:: python
+
+    >>> latlng = [43.0, -80.0]
+    >>> g = geocoder.geonames('Paris', proximity=latlng, key='<USERNAME>')
+    >>> print([g.address, g.country, g.latlng])
+    ['Paris', 'Canada', ['43.2001', '-80.38297']]
+
+
+Compliant providers
+-------------------
+
+- :doc:`Google Places <providers/Google>`
+- :doc:`Geonames <providers/GeoNames>`
+- :doc:`Mapbox <providers/Mapbox>`
+