Add bbox parameter

README.md

@@ -26,6 +26,7 @@ Photon software is open source and licensed under [Apache License, Version 2.0](
 - location bias
 - typo tolerance
 - filter by osm tag and value
+- filter by bounding box
 - reverse geocode a coordinate to an address
 - OSM data import (built upon [Nominatim](https://github.com/twain47/Nominatim)) inclusive continuous updates
 
@@ -132,6 +133,12 @@ http://localhost:2322/api?q=berlin&limit=2
 http://localhost:2322/api?q=berlin&lang=it
 ```
 
+#### Filter results by bounding box
+Expected format is minLon,minLat,maxLon,maxLat. 
+```
+http://localhost:2322/api?q=berlin&bbox=9.5,51.5,11.5,53.5
+```
+
 #### Filter results by [tags and values](http://taginfo.openstreetmap.org/projects/nominatim#tags) 
 *Note: not all tags on [link in the title](http://taginfo.openstreetmap.org/projects/nominatim#tags) are supported. Please see [nominatim source](https://github.com/openstreetmap/osm2pgsql/blob/master/output-gazetteer.cpp#L81) for an accurate list.*
 If one or many query parameters named ```osm_tag``` are present, photon will attempt to filter results by those tags. In general, here is the expected format (syntax) for the value of osm_tag request parameters.

src/main/java/de/komoot/photon/query/BoundingBoxParamConverter.java

@@ -0,0 +1,45 @@
+package de.komoot.photon.query;
+
+import com.vividsolutions.jts.geom.Envelope;
+
+import de.komoot.photon.utils.Function;
+import spark.Request;
+
+/**
+ * Converts the bbox parameter into an Envelope and performs format checking.
+ * Created by Holger Bruch on 10/13/2018.
+ */
+public class BoundingBoxParamConverter implements Function<Request, Envelope, BadRequestException> {
+
+    private static final String INVALID_BBOX_ERROR_MESSAGE = "invalid search term 'bbox', expected format is: minLon,minLat,maxLon,maxLat";
+
+    @Override
+    public Envelope apply(Request webRequest) throws BadRequestException {
+        String bboxParam = webRequest.queryParams("bbox");
+        if (bboxParam == null) {
+            return null;
+        }
+        Envelope bbox = null;
+        try {
+            String[] bboxCoords = bboxParam.split(",");
+            if (bboxCoords.length != 4) {
+                throw new BadRequestException(400, INVALID_BBOX_ERROR_MESSAGE);
+            }
+            Double minLon = Double.valueOf(bboxCoords[0]);
+            Double minLat = Double.valueOf(bboxCoords[2]);
+            Double maxLon = Double.valueOf(bboxCoords[1]);
+            Double maxLat = Double.valueOf(bboxCoords[3]);
+            if (minLon > 180.0 || minLon < -180.00 || maxLon > 180.0 || maxLon < -180.00) {
+                throw new BadRequestException(400, INVALID_BBOX_ERROR_MESSAGE);
+            }
+            if (minLat > 90.0 || minLat < -90.00 || maxLat > 90.0 || maxLat < -90.00) {
+                throw new BadRequestException(400, INVALID_BBOX_ERROR_MESSAGE);
+            }
+            bbox = new Envelope(minLon, minLat, maxLon, maxLat);
+        } catch (NumberFormatException nfe) {
+            throw new BadRequestException(400, INVALID_BBOX_ERROR_MESSAGE);
+        }
+
+        return bbox;
+    }
+}

src/main/java/de/komoot/photon/query/FilteredPhotonRequest.java

@@ -1,5 +1,6 @@
 package de.komoot.photon.query;
 
+import com.vividsolutions.jts.geom.Envelope;
 import com.vividsolutions.jts.geom.Point;
 
 import java.util.HashMap;
@@ -20,8 +21,8 @@ public class FilteredPhotonRequest extends PhotonRequest {
     private Map<String, Set<String>> excludeTags = new HashMap<String, Set<String>>(3);
     private Map<String, Set<String>> excludeTagValues = new HashMap<String, Set<String>>(3);
 
-    FilteredPhotonRequest(String query, int limit, Point locationForBias, double locBiasScale, String language) {
-        super(query, limit, locationForBias, locBiasScale, language);
+    FilteredPhotonRequest(String query, int limit, Envelope bbox, Point locationForBias, double locBiasScale, String language) {
+        super(query, limit, bbox, locationForBias, locBiasScale, language);
     }
 
     public Set<String> keys() {

src/main/java/de/komoot/photon/query/PhotonQueryBuilder.java

@@ -2,6 +2,7 @@
 
 
 import com.google.common.collect.ImmutableSet;
+import com.vividsolutions.jts.geom.Envelope;
 import com.vividsolutions.jts.geom.Point;
 import org.elasticsearch.common.lucene.search.function.CombineFunction;
 import org.elasticsearch.common.lucene.search.function.FiltersFunctionScoreQuery.ScoreMode;
@@ -51,6 +52,8 @@ public class PhotonQueryBuilder implements TagFilterQueryBuilder {
 
     private MatchQueryBuilder languageMatchQueryBuilder;
 
+    private GeoBoundingBoxQueryBuilder bboxQueryBuilder;
+
     private QueryBuilder m_finalQueryBuilder;
 
     protected ArrayList<FilterFunctionBuilder> m_alFilterFunction4QueryBuilder = new ArrayList<>(1);
@@ -133,6 +136,15 @@ public TagFilterQueryBuilder withLocationBias(Point point, double scale) {
                         .boostMode(CombineFunction.MULTIPLY);
         return this;
     }
+
+     @Override
+    public TagFilterQueryBuilder withBoundingBox(Envelope bbox) {
+        if (bbox == null) return this;
+        bboxQueryBuilder = new GeoBoundingBoxQueryBuilder("coordinate");
+        bboxQueryBuilder.setCorners(bbox.getMaxY(), bbox.getMinX(), bbox.getMinY(), bbox.getMaxX());
+
+        return this;
+    }
 
     @Override
     public TagFilterQueryBuilder withTags(Map<String, Set<String>> tags) {
@@ -314,6 +326,9 @@ public QueryBuilder buildQuery() {
                 m_queryBuilderForTopLevelFilter.must(andQueryBuilderForExcludeTagFiltering);
 
         }
+
+        if (bboxQueryBuilder != null) 
+            m_queryBuilderForTopLevelFilter.filter(bboxQueryBuilder);
 
         state = State.FINISHED;
 

src/main/java/de/komoot/photon/query/PhotonRequest.java

@@ -1,5 +1,6 @@
 package de.komoot.photon.query;
 
+import com.vividsolutions.jts.geom.Envelope;
 import com.vividsolutions.jts.geom.Point;
 
 import java.io.Serializable;
@@ -13,13 +14,15 @@ public class PhotonRequest implements Serializable {
     private Point locationForBias;
     private String language;
     private final double scale;
+    private Envelope bbox;
 
-    public PhotonRequest(String query, int limit, Point locationForBias, double scale, String language) {
+    public PhotonRequest(String query, int limit, Envelope bbox, Point locationForBias, double scale, String language) {
         this.query = query;
         this.limit = limit;
         this.locationForBias = locationForBias;
         this.scale = scale;
         this.language = language;
+        this.bbox = bbox;
     }
 
     public String getQuery() {
@@ -29,6 +32,10 @@ public String getQuery() {
     public Integer getLimit() {
         return limit;
     }
+
+    public Envelope getBbox() {
+        return bbox;
+    }
 
     public Point getLocationForBias() {
         return locationForBias;

src/main/java/de/komoot/photon/query/PhotonRequestFactory.java

@@ -1,6 +1,7 @@
 package de.komoot.photon.query;
 
 import com.vividsolutions.jts.geom.Coordinate;
+import com.vividsolutions.jts.geom.Envelope;
 import com.vividsolutions.jts.geom.GeometryFactory;
 import com.vividsolutions.jts.geom.Point;
 import com.vividsolutions.jts.geom.PrecisionModel;
@@ -17,13 +18,16 @@
  */
 public class PhotonRequestFactory {
     private final LanguageChecker languageChecker;
+    private final BoundingBoxParamConverter bboxParamConverter;
+
     private final static GeometryFactory geometryFactory = new GeometryFactory(new PrecisionModel(), 4326);
 
     protected static HashSet<String> m_hsRequestQueryParams = new HashSet<>(Arrays.asList("lang", "q", "lon", "lat",
-            "limit", "osm_tag", "location_bias_scale"));
+            "bbox", "limit", "osm_tag", "location_bias_scale"));
 
     public PhotonRequestFactory(Set<String> supportedLanguages) {
         this.languageChecker = new LanguageChecker(supportedLanguages);
+        this.bboxParamConverter = new BoundingBoxParamConverter();
     }
 
     public <R extends PhotonRequest> R create(Request webRequest) throws BadRequestException {
@@ -53,7 +57,9 @@ public <R extends PhotonRequest> R create(Request webRequest) throws BadRequestE
         } catch (Exception nfe) {
             //ignore
         }
-
+
+        Envelope bbox = bboxParamConverter.apply(webRequest);
+
         // don't use too high default value, see #306
         double scale = 1.6;
         String scaleStr = webRequest.queryParams("location_bias_scale");
@@ -66,9 +72,9 @@ public <R extends PhotonRequest> R create(Request webRequest) throws BadRequestE
 
         QueryParamsMap tagFiltersQueryMap = webRequest.queryMap("osm_tag");
         if (!new CheckIfFilteredRequest().execute(tagFiltersQueryMap)) {
-            return (R) new PhotonRequest(query, limit, locationForBias, scale, language);
+            return (R) new PhotonRequest(query, limit, bbox, locationForBias, scale, language);
         }
-        FilteredPhotonRequest photonRequest = new FilteredPhotonRequest(query, limit, locationForBias, scale, language);
+        FilteredPhotonRequest photonRequest = new FilteredPhotonRequest(query, limit, bbox, locationForBias, scale, language);
         String[] tagFilters = tagFiltersQueryMap.values();
         setUpTagFilters(photonRequest, tagFilters);
 

src/main/java/de/komoot/photon/query/ReverseQueryBuilder.java

@@ -1,6 +1,7 @@
 package de.komoot.photon.query;
 
 import com.google.common.collect.ImmutableSet;
+import com.vividsolutions.jts.geom.Envelope;
 import com.vividsolutions.jts.geom.Point;
 import org.elasticsearch.common.unit.DistanceUnit;
 import org.elasticsearch.index.query.BoolQueryBuilder;
@@ -45,6 +46,11 @@ public TagFilterQueryBuilder withLocationBias(Point point, double scale) {
         throw new RuntimeException(new NoSuchMethodException("this method is not implemented (NOOP)"));
     }
 
+    @Override
+    public TagFilterQueryBuilder withBoundingBox(Envelope bbox) {
+        throw new RuntimeException(new NoSuchMethodException("this method is not implemented (NOOP)"));
+    }
+
     @Override
     public TagFilterQueryBuilder withTags(Map<String, Set<String>> tags) {
         throw new RuntimeException(new NoSuchMethodException("this method is not implemented (NOOP)"));

src/main/java/de/komoot/photon/query/TagFilterQueryBuilder.java

@@ -1,5 +1,6 @@
 package de.komoot.photon.query;
 
+import com.vividsolutions.jts.geom.Envelope;
 import com.vividsolutions.jts.geom.Point;
 import org.elasticsearch.index.query.QueryBuilder;
 
@@ -21,6 +22,13 @@ public interface TagFilterQueryBuilder {
      */
     TagFilterQueryBuilder withLimit(Integer limit);
 
+    /**
+     * Search results will be filtered to places contained in the bounding box (WGS84) provided in the argument.
+     *
+     * @param bbox Geographical {@link Envelope}
+     */
+    TagFilterQueryBuilder withBoundingBox(Envelope bbox);
+
     /**
      * Location bias for query. By setting this, places found will be sorted by proximity to this point.
      *

src/main/java/de/komoot/photon/searcher/FilteredPhotonRequestHandler.java

@@ -35,7 +35,8 @@ public TagFilterQueryBuilder buildQuery(FilteredPhotonRequest photonRequest) {
                 withoutKeys(excludeKeys).
                 withoutValues(excludeValues).
                 withTagsNotValues(excludeTagValues).
-                withLocationBias(photonRequest.getLocationForBias(), photonRequest.getScaleForBias());
+                withLocationBias(photonRequest.getLocationForBias(), photonRequest.getScaleForBias()).
+                withBoundingBox(photonRequest.getBbox());
     }
 
 }

src/main/java/de/komoot/photon/searcher/SimplePhotonRequestHandler.java

@@ -15,6 +15,7 @@ public SimplePhotonRequestHandler(ElasticsearchSearcher elasticsearchSearcher) {
     @Override
     public TagFilterQueryBuilder buildQuery(PhotonRequest photonRequest) {
         return PhotonQueryBuilder.builder(photonRequest.getQuery(), photonRequest.getLanguage()).
-                withLocationBias(photonRequest.getLocationForBias(), photonRequest.getScaleForBias());
+                withLocationBias(photonRequest.getLocationForBias(), photonRequest.getScaleForBias()).
+                withBoundingBox(photonRequest.getBbox());
     }
 }

src/test/java/de/komoot/photon/query/FilteredPhotonRequestTest.java

@@ -14,7 +14,7 @@ public class FilteredPhotonRequestTest {
 
     @Test
     public void testNotKey() {
-        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, 0, null);
+        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, null, 0, null);
         filteredPhotonRequest.notKeys("exclude");
         filteredPhotonRequest.notKeys("exclude");
         filteredPhotonRequest.notKeys("anotherExclude");
@@ -27,7 +27,7 @@ public void testNotKey() {
 
     @Test
     public void testNotTag() {
-        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, 0, null);
+        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, null, 0, null);
         filteredPhotonRequest.notTags("aKey", ImmutableSet.of("aValue"));
         filteredPhotonRequest.notTags("anotherKey", ImmutableSet.of("anotherValue"));
         Map<String, Set<String>> excludeTags = filteredPhotonRequest.notTags();
@@ -37,7 +37,7 @@ public void testNotTag() {
 
     @Test
     public void testNotValue() {
-        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, 0, null);
+        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, null, 0, null);
         filteredPhotonRequest.notValues("exclude");
         filteredPhotonRequest.notValues("exclude");
         filteredPhotonRequest.notValues("anotherExclude");
@@ -48,7 +48,7 @@ public void testNotValue() {
 
     @Test
     public void testKey() {
-        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, 0, null);
+        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, null, 0, null);
         filteredPhotonRequest.keys("keyToInclude");
         filteredPhotonRequest.keys("keyToInclude");
         filteredPhotonRequest.keys("anotherKeyToInclude");
@@ -57,7 +57,7 @@ public void testKey() {
 
     @Test
     public void testTag() {
-        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, 0, null);
+        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, null, 0, null);
         filteredPhotonRequest.tags("aKey", ImmutableSet.of("aValue"));
         filteredPhotonRequest.tags("anotherKey", ImmutableSet.of("anotherValue"));
         Map<String, Set<String>> includeTags = filteredPhotonRequest.tags();
@@ -68,7 +68,7 @@ public void testTag() {
 
     @Test
     public void testValue() {
-        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, 0, null);
+        FilteredPhotonRequest filteredPhotonRequest = new FilteredPhotonRequest(null, 0, null, null, 0, null);
         filteredPhotonRequest.values("keyToInclude");
         filteredPhotonRequest.values("keyToInclude");
         filteredPhotonRequest.values("anotherKeyToInclude");

src/test/java/de/komoot/photon/query/PhotonRequestFactoryTest.java

@@ -2,6 +2,8 @@
 
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
+import com.vividsolutions.jts.geom.Envelope;
+
 import org.junit.Assert;
 import org.junit.Test;
 import org.mockito.Mockito;
@@ -197,4 +199,39 @@ public void testWithExcludeValueFilter() throws Exception {
         Mockito.verify(mockOsmTagQueryParm, Mockito.times(2)).values();
         Assert.assertEquals(ImmutableSet.of("aValue"), filteredPhotonRequest.notValues());
     }
+
+    @Test
+    public void testWithBboxFilter() throws Exception {
+        Request mockRequest = Mockito.mock(Request.class);
+        Mockito.when(mockRequest.queryParams("q")).thenReturn("hanover");
+        QueryParamsMap mockQueryParamsMap = Mockito.mock(QueryParamsMap.class);
+        Mockito.when(mockRequest.queryMap("osm_tag")).thenReturn(mockQueryParamsMap);
+        Mockito.when(mockRequest.queryParams("bbox")).thenReturn("9.6,52.4,9.8,52.3");   
+
+        PhotonRequestFactory photonRequestFactory = new PhotonRequestFactory(ImmutableSet.of("en"));
+        PhotonRequest photonRequest = photonRequestFactory.create(mockRequest); 
+
+        Mockito.verify(mockRequest, Mockito.times(1)).queryParams("bbox");
+        Assert.assertEquals(new Envelope(9.6, 9.8, 52.3, 52.4), photonRequest.getBbox());
+    }
+
+    @Test
+    public void testWithBadBboxFilter() throws Exception {
+        Request mockRequest = Mockito.mock(Request.class);
+        Mockito.when(mockRequest.queryParams("q")).thenReturn("hanover");
+        QueryParamsMap mockQueryParamsMap = Mockito.mock(QueryParamsMap.class);
+        Mockito.when(mockRequest.queryMap("osm_tag")).thenReturn(mockQueryParamsMap);
+        Mockito.when(mockRequest.queryParams("bbox")).thenReturn("9.6,91,9.8,93");   
+
+        try {
+            PhotonRequestFactory photonRequestFactory = new PhotonRequestFactory(ImmutableSet.of("en"));
+            photonRequestFactory.create(mockRequest); 
+            Assert.fail();
+        } catch (BadRequestException e) {
+            Assert.assertEquals("invalid search term 'bbox', expected format is: minLon,minLat,maxLon,maxLat", e.getMessage());
+        }
+        Mockito.verify(mockRequest, Mockito.times(1)).queryParams("bbox");
+    }
+
+
 }