jerzykrlk / geohash-facet

Geohash Facet Plugin for elasticsearch

Original project: https://github.com/zenobase/geocluster-facet

Installation (latest version): run

bin/plugin --url https://github.com/triforkams/geohash-facet/releases/download/geohash-facet-0.0.17/geohash-facet-0.0.19.jar --install geohash-facet

For usage see this blog post.

Versions

geohash-facet	elasticsearch compatibility	notes
0.0.19	1.4.1	upgraded to ES 1.4.1
0.0.18	1.3.6	upgraded to ES 1.3.6
0.0.17	1.2.1	upgraded to ES 1.2.1
0.0.16	1.0.0	fix for triforkams#9
0.0.15	1.0.0	merged triforkams#6
0.0.14	1.0.0	implemented triforkams#7
0.0.13	1.0.0	bug fixing, added a facet builder for use on the client side
0.0.12	0.90.6+, 1.0.0+	implemented triforkams#4
0.0.11	0.90.6+, 1.0.0+	fixed triforkams#3
0.0.10	0.90.6+, 1.0.0+	updated to stay compatible with latest ES
0.0.9	0.90.5	updated to stay compatible with latest ES
0.0.8	0.90.3	updated to stay compatible with latest ES
0.0.7	0.90.2

Parameters

</tbody>

field	The name of a field of type `geo_point`.
factor	Controls the amount of clustering, from 0.0 (don't cluster any points) to 1.0 (create a single cluster containing all points). Defaults to 0.1. The value determines the size of the cells used to cluster together points. Starting from version 0.0.14, the clustering is computed using a bit-string geohash instead of the traditional alphanumeric geohash. This gives you more fine grained selection of the level of clustering.
show_geohash_cell	Boolean. If true, for each cluster included in the reply the coordinates of the corresponding geohash cell are provided (top left and bottom right corner. Defaults to false.
show_doc_id	Boolean. If true, for each cluster composed of a single document the document ID is returned. Defaults to false.

Index configuration

In the mapping, you need to declare the field containing the location as a type geo_point.

{
  "venues" : {
    "properties" : {
      "location" : {
        "type" : "geo_point"
      }
    }
  }
}

Querying (HTTP)

Example document:

{
    "took" : 42,
    "timed_out" : false,
    "_shards" : {
        "total" : 5,
        "successful" : 5,
        "failed" : 0
    },
    "hits" : {
        "total" : 1,
        "max_score" : 1.0,
        "hits" : [ {
            "_index" : "myindex",
            "_type" : "venues",
            "_id" : "abc",
            "_score" : 1.0,
            "_source" : {
                "location":{ "lat":"52.01010835419531","lon":"4.722006599999986" }
            }
        }]
    }
}

Query:

{
    "query" : { ... },
    "facets" : {
        "places" : {
            "geohash" : {
                "field" : "location",
                "factor" : 0.9
            }
        }
    }
}

Result:

{
    "took" : 67,
    "timed_out" : false,
    "_shards" : {
        "total" : 5,
        "successful" : 5,
        "failed" : 0
    },
    "hits" : {
        "total" : 1372947,
        "max_score" : 0.0,
        "hits" : [ ]
    },
    "facets" : {
        "places" : {
            "_type" : "geohash",
            "factor" : 0.9,
            "clusters" : [ {
                "total" : 8,
                "center" : {
                    "lat" : 16.95292075,
                    "lon" : 122.036081375
                },
                "top_left" : {
                    "lat" : 33.356026,
                    "lon" : 121.00589
                },
                "bottom_right" : {
                    "lat" : 14.60962,
                    "lon" : 129.247421
                }
            }, {
                "total" : 191793,
                "center" : {
                    "lat" : 52.02785559813162,
                    "lon" : 4.921446953767902
                },
                "top_left" : {
                    "lat" : 64.928595,
                    "lon" : 3.36244
                },
                "bottom_right" : {
                    "lat" : 45.468945,
                    "lon" : 26.067386
                }
            } ]
        }
    }
}

Query with show_geohash_cell enabled:

{
    "query" : { ... },
    "facets" : {
        "places" : {
            "geohash" : {
                "field" : "location",
                "factor" : 0.9,
                "show_geohash_cell" : true
            }
        }
    }
}

Result:

{
    "took" : 61,
    "timed_out" : false,
    "_shards" : {
        "total" : 5,
        "successful" : 5,
        "failed" : 0
    },
    "hits" : {
        "total" : 1372947,
        "max_score" : 0.0,
        "hits" : [ ]
    },
    "facets" : {
        "places" : {
            "_type" : "geohash",
            "factor" : 0.9,
            "clusters" : [ {
                "total" : 8,
                "center" : {
                    "lat" : 16.95292075,
                    "lon" : 122.036081375
                },
                "top_left" : {
                    "lat" : 33.356026,
                    "lon" : 121.00589
                },
                "bottom_right" : {
                    "lat" : 14.60962,
                    "lon" : 129.247421
                },
                "geohash_cell" : {
                    "top_left" : {
                        "lat" : 45.0,
                        "lon" : 90.0
                    },
                    "bottom_right" : {
                        "lat" : 0.0,
                        "lon" : 135.0
                    }
                }
            }, {
                "total" : 191793,
                "center" : {
                    "lat" : 52.02785559813162,
                    "lon" : 4.921446953767902
                },
                "top_left" : {
                    "lat" : 64.928595,
                    "lon" : 3.36244
                },
                "bottom_right" : {
                    "lat" : 45.468945,
                    "lon" : 26.067386
                },
                "geohash_cell" : {
                    "top_left" : {
                        "lat" : 90.0,
                        "lon" : 0.0
                    },
                    "bottom_right" : {
                        "lat" : 45.0,
                        "lon" : 45.0
                    }
                }
            } ]
        }
    }
}

Querying (Java)

You can also do facet requests using the GeoFacetBuilder class included in the library:

public class Example {

    public static void main(String[] args) {
    
        GeoFacetBuilder facetBuilder = new GeoFacetBuilder("monuments").
                field("location").
                factor(0.9)
                .showGeohashCell(false)
                .showDocId(true);

        Client client = ... // instantiate
        
        SearchResponse response = client.prepareSearch("poi")
                .setSearchType(SearchType.COUNT)
                .addFacet(facetBuilder)
                .execute()
                .actionGet();

        GeohashFacet geohashFacet = (GeohashFacet) response.getFacets().facetsAsMap().get("monuments");
        
        for (Cluster cluster: geohashFacet.getEntries()) {
        
            // do something 	
        }
    }

}

Size of the cells

The table below shows the size of the cells defined by various values of the factor parameter. These data can be useful if you want to find the factor value which returns at most n clusters given a bounding box to search on.

Factor	Latitude delta (degrees)	Longitude delta (degrees)
1	180	360
0.98	180	180
0.97	90	180
0.95	90	90
0.93	45	90
0.92	45	45
0.9	22.5	45
0.88	22.5	22.5
0.87	11.25	22.5
0.85	11.25	11.25
0.83	5.625	11.25
0.82	5.625	5.625
0.8	2.8125	5.625
0.78	2.8125	2.8125
0.77	1.40625	2.8125
0.75	1.40625	1.40625
0.73	0.703125	1.40625
0.72	0.703125	0.703125
0.7	0.3515625	0.703125
0.68	0.3515625	0.3515625
0.67	0.17578125	0.3515625
0.65	0.17578125	0.17578125
0.63	0.087890625	0.17578125
0.62	0.087890625	0.087890625
0.6	0.0439453125	0.087890625
0.58	0.0439453125	0.0439453125
0.57	0.02197265625	0.0439453125
0.55	0.02197265625	0.02197265625
0.53	0.01098632813	0.02197265625
0.52	0.01098632813	0.01098632813
0.5	0.005493164063	0.01098632813
0.48	0.005493164063	0.005493164063
0.47	0.002746582031	0.005493164063
0.45	0.002746582031	0.002746582031
0.43	0.001373291016	0.002746582031
0.42	0.001373291016	0.001373291016
0.4	0.0006866455078	0.001373291016
0.38	0.0006866455078	0.0006866455078
0.37	0.0003433227539	0.0006866455078
0.35	0.0003433227539	0.0003433227539
0.33	0.000171661377	0.0003433227539
0.32	0.000171661377	0.000171661377
0.3	0.00008583068848	0.000171661377
0.28	0.00008583068848	0.00008583068848
0.27	0.00004291534424	0.00008583068848
0.25	0.00004291534424	0.00004291534424
0.23	0.00002145767212	0.00004291534424
0.22	0.00002145767212	0.00002145767212
0.2	0.00001072883606	0.00002145767212
0.18	0.00001072883606	0.00001072883606
0.17	0.00000536441803	0.00001072883606
0.15	0.00000536441803	0.00000536441803
0.13	0.000002682209015	0.00000536441803
0.12	0.000002682209015	0.000002682209015
0.1	0.000001341104507	0.000002682209015
0.08	0.000001341104507	0.000001341104507
0.07	0.0000006705522537	0.000001341104507
0.05	0.0000006705522537	0.0000006705522537
0.03	0.0000003352761269	0.0000006705522537
0.02	0.0000003352761269	0.0000003352761269
0	0.0000001676380634	0.0000003352761269

License

This software is licensed under the Apache 2 license, quoted below.

Copyright 2012-2013 Trifork Amsterdam BV

Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.