Skip to content

triforkams/geohash-facet

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

94 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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 #9
0.0.15 1.0.0 merged #6
0.0.14 1.0.0 implemented #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 #4
0.0.11 0.90.6+, 1.0.0+ fixed #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)
1180360
0.98180180
0.9790180
0.959090
0.934590
0.924545
0.922.545
0.8822.522.5
0.8711.2522.5
0.8511.2511.25
0.835.62511.25
0.825.6255.625
0.82.81255.625
0.782.81252.8125
0.771.406252.8125
0.751.406251.40625
0.730.7031251.40625
0.720.7031250.703125
0.70.35156250.703125
0.680.35156250.3515625
0.670.175781250.3515625
0.650.175781250.17578125
0.630.0878906250.17578125
0.620.0878906250.087890625
0.60.04394531250.087890625
0.580.04394531250.0439453125
0.570.021972656250.0439453125
0.550.021972656250.02197265625
0.530.010986328130.02197265625
0.520.010986328130.01098632813
0.50.0054931640630.01098632813
0.480.0054931640630.005493164063
0.470.0027465820310.005493164063
0.450.0027465820310.002746582031
0.430.0013732910160.002746582031
0.420.0013732910160.001373291016
0.40.00068664550780.001373291016
0.380.00068664550780.0006866455078
0.370.00034332275390.0006866455078
0.350.00034332275390.0003433227539
0.330.0001716613770.0003433227539
0.320.0001716613770.000171661377
0.30.000085830688480.000171661377
0.280.000085830688480.00008583068848
0.270.000042915344240.00008583068848
0.250.000042915344240.00004291534424
0.230.000021457672120.00004291534424
0.220.000021457672120.00002145767212
0.20.000010728836060.00002145767212
0.180.000010728836060.00001072883606
0.170.000005364418030.00001072883606
0.150.000005364418030.00000536441803
0.130.0000026822090150.00000536441803
0.120.0000026822090150.000002682209015
0.10.0000013411045070.000002682209015
0.080.0000013411045070.000001341104507
0.070.00000067055225370.000001341104507
0.050.00000067055225370.0000006705522537
0.030.00000033527612690.0000006705522537
0.020.00000033527612690.0000003352761269
00.00000016763806340.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.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 92.0%
  • JavaScript 8.0%