Geo Bounded Polygon Query


The ability to perform text search with geo capabilities is a very powerful and effective feature from full text search(FTS). And we are bringing the more flexible geo bounded polygon query feature to FTS in the upcoming releases.


Until now, FTS supports two types of  geo queries. ie Point Distance queries and Bounded rectangle queriesPoint Distance query helps you in serving searches like – finding all points of interest near you in their sorted order of distance, where as the Bounded Rectangle query helps in finding all points of interest within the given rectangle boundary specified over the top_left and bottom_right corners.


We know that in most real life use cases the geospatial boundaries come in all random shapes. ie they don’t just show up like simple rectangle or square regions. Certainly rectangles/squares could be used as a first hand approximation for the given spatial query. But for better precision results, we should be able to specify the region boundaries in a more granular way.

And that leads to the introduction of geo bounded polygon queries in full text search.





This feature adds the capability to perform a random bounding polygon query to select documents falling within that polygon area.  Input parameters would be an array of coordinate pairs representing bounding polygon vertices that define the polygon area. (preferably in anticlockwise direction). Results should be a list of documents that lies within the area.

Few nitty gritty of the bounded polygon query are,

  • Orientation of polygon coordinates is governed by the geoJSON standard. ref – geojson
  • Coordinates could be specified in a closed format (giving the last coordinate same as the first one) as well, but not necessary. 
  • It uses the ray casting technique for finding the point inclusivity in the polygon.
  • No holes in the polygons are supported now. But there is a way users may perform such queries using boolean queries. (must_not clause for the inner polygons for querying  shapes like donuts).
  • The searchable geolocation field in the document needs to be indexed using the prebuilt “geopoint” type.



Modus Operandi


Let’s quickly explore on, how easy it is to try out a bounded polygon query with FTS.

It is just a 3 step process.

  1. Index the documents in the same as we do for bounded rectangle/point distance query.
  2. Identify a polygon area (vertices) you need to query upon.
  3. Try the query in any of the geojson formats mentioned in the example below.


For example, if you have a field named “geo” in the document which contains the geo location information, then first you need to include it in the index definition like below.

Once the indexing is completed, you are ready to try your searches!

Lets say, if you are interested in finding documents within a given region like below.


You may try the polygon queries like below.

curl -XPOST -H "Content-Type: application/json"
-u <username>:<password> http://<node>:<port>/api/index/<indexName>/query -d '

 "query": {
   "field": "geo",
   "polygon_points": [

All the geo queries in FTS supports geoJSON formats and hence any of the below polygon coordinate formats can be used in addition to the above sample

"polygon_points": [
     {“lat”: 37.79393211306212, “lon”: -122.44234633404847},
    { “lat”: 37.77995881733997, “lon”: -122.43977141339417},
     { “lat”: 37.788031092020155, “lon”: -122.4292571540557},
     { “lat”: 37.79026946582319,“lon”: -122.41149020154114},
     { “lat”: 37.79571192027403,“lon”: -122.40735054016113},
     { “lat”: 37.79393211306212, “lon”: -122.44234633404847}


"polygon_points": [
       [  -122.44234633404847,  37.79393211306212],
       [  -122.43977141339417, 37.77995881733997],
       [ -122.42925715405579, 37.78803109202015],
       [ -122.41149020154114, 37.79026946582319],
       [ -122.40735054016113, 37.79571192027403],
       [ -122.44234633404847,37.79393211306212]


"polygon_points": [“9q8zjbkp”, “9q8yvvdh”, “9q8yyp1e”, “9q8yyrw8”, “9q8zn83x”, “9q8zjb0j”]

Eager to get your hands dirty with bounded polygon queries?, please pay heed to the upcoming Couchbase server releases.


Posted by Sreekanth Sivasankaran

Sreekanth Sivasankaran is a Software Engineer, Couchbase. He is into the design and development of distributed and highly performant full text search functionality.

Leave a reply