Repository: mapbox/mapbox-sdk-py

Issue:
Support geocoding bbox parameter

Discussion:

Patch:
diff --git a/README.rst b/README.rst
index c20b789..8b6cf8a 100644
--- a/README.rst
+++ b/README.rst
@@ -75,7 +75,7 @@ To run the examples as integration tests on your own Mapbox account
 
 .. code:: bash
 
-    MAPBOX_ACCESS_TOKEN="MY_ACCESS_TOKEN" py.test --doctest-glob='*.md' *.md
+    MAPBOX_ACCESS_TOKEN="MY_ACCESS_TOKEN" py.test --doctest-glob='*.md' docs/*.md
 
 See Also
 ========
diff --git a/docs/geocoding.md b/docs/geocoding.md
index 3586829..01d57c6 100644
--- a/docs/geocoding.md
+++ b/docs/geocoding.md
@@ -129,6 +129,24 @@ Place results may be biased toward a given longitude and latitude.
 
 ```
 
+## Forward geocoding with bounding box
+
+Place results may be limited to those falling within a given bounding box.
+
+```python
+
+>>> response = geocoder.forward(
+...     "washington", bbox=[-78.338320,38.520792,-77.935454,38.864909])
+>>> response.status_code
+200
+>>> first = response.geojson()['features'][0]
+>>> first['place_name']
+'Washington, Virginia, United States'
+>>> first['geometry']['coordinates']
+[-78.1594, 38.7135]
+
+```
+
 ## Reverse geocoding
 
 Places at a longitude, latitude point may be found using `Geocoder.reverse()`.
diff --git a/mapbox/services/geocoding.py b/mapbox/services/geocoding.py
index ef7174f..e357a04 100644
--- a/mapbox/services/geocoding.py
+++ b/mapbox/services/geocoding.py
@@ -36,7 +36,7 @@ class Geocoder(Service):
                 raise InvalidPlaceTypeError(pt)
         return {'types': ",".join(types)}
 
-    def forward(self, address, types=None, lon=None, lat=None, country=None):
+    def forward(self, address, types=None, lon=None, lat=None, country=None, bbox=None):
         """Returns a Requests response object that contains a GeoJSON
         collection of places matching the given address.
 
@@ -46,7 +46,7 @@ class Geocoder(Service):
         Place results may be constrained to those of one or more types
         or be biased toward a given longitude and latitude.
 
-        See: https://www.mapbox.com/developers/api/geocoding/#forward."""
+        See: https://www.mapbox.com/api-documentation/#geocoding."""
         uri = URITemplate(self.baseuri + '/{dataset}/{query}.json').expand(
             dataset=self.name, query=address.encode('utf-8'))
         params = {}
@@ -58,6 +58,8 @@ class Geocoder(Service):
             params.update(proximity='{0},{1}'.format(
                 round(float(lon), self.precision.get('proximity', 3)),
                 round(float(lat), self.precision.get('proximity', 3))))
+        if bbox is not None:
+            params.update(bbox='{0},{1},{2},{3}'.format(*bbox))
         resp = self.session.get(uri, params=params)
         self.handle_http_error(resp)
 
@@ -75,7 +77,7 @@ class Geocoder(Service):
         `response.geojson()` returns the geocoding result as GeoJSON.
         `response.status_code` returns the HTTP API status code.
 
-        See: https://www.mapbox.com/developers/api/geocoding/#reverse."""
+        See: https://www.mapbox.com/api-documentation/#retrieve-places-near-a-location."""
         uri = URITemplate(self.baseuri + '/{dataset}/{lon},{lat}.json').expand(
             dataset=self.name,
             lon=str(round(float(lon), self.precision.get('reverse', 5))),


Test patch:
diff --git a/tests/test_geocoder.py b/tests/test_geocoder.py
index e30504c..da98a3d 100644
--- a/tests/test_geocoder.py
+++ b/tests/test_geocoder.py
@@ -212,6 +212,23 @@ def test_geocoder_proximity_rounding():
     for coord in re.split(r'(%2C|,)', match.group(1)):
         assert _check_coordinate_precision(coord, 3)
 
+@responses.activate
+def test_geocoder_forward_bbox():
+    """Bbox parameter works"""
+
+    responses.add(
+        responses.GET,
+        'https://api.mapbox.com/geocoding/v5/mapbox.places/washington.json?bbox=-78.3284%2C38.6039%2C-78.0428%2C38.7841&access_token=pk.test',
+        match_querystring=True,
+        body='{"query": ["washington"]}', status=200,
+        content_type='application/json')
+
+    response = mapbox.Geocoder(
+        access_token='pk.test').forward(
+            'washington', bbox=(-78.3284,38.6039,-78.0428,38.7841))
+    assert response.status_code == 200
+    assert response.json()['query'] == ["washington"]
+
 @responses.activate
 def test_geocoder_reverse_rounding():
     """Reverse geocoding parameters are rounded to 5 decimal places"""