Geo-centroid aggregation

Geo-centroid aggregation

A metric aggregation that computes the weighted centroid from all coordinate values for geo fields.

Example:

  1. resp = client.indices.create(
  2.     index="museums",
  3.     mappings={
  4.         "properties": {
  5.             "location": {
  6.                 "type": "geo_point"
  7.             }
  8.         }
  9.     },
  10. )
  11. print(resp)
  13. resp1 = client.bulk(
  14.     index="museums",
  15.     refresh=True,
  16.     operations=[
  17.         {
  18.             "index": {
  19.                 "_id": 1
  20.             }
  21.         },
  22.         {
  23.             "location": "POINT (4.912350 52.374081)",
  24.             "city": "Amsterdam",
  25.             "name": "NEMO Science Museum"
  26.         },
  27.         {
  28.             "index": {
  29.                 "_id": 2
  30.             }
  31.         },
  32.         {
  33.             "location": "POINT (4.901618 52.369219)",
  34.             "city": "Amsterdam",
  35.             "name": "Museum Het Rembrandthuis"
  36.         },
  37.         {
  38.             "index": {
  39.                 "_id": 3
  40.             }
  41.         },
  42.         {
  43.             "location": "POINT (4.914722 52.371667)",
  44.             "city": "Amsterdam",
  45.             "name": "Nederlands Scheepvaartmuseum"
  46.         },
  47.         {
  48.             "index": {
  49.                 "_id": 4
  50.             }
  51.         },
  52.         {
  53.             "location": "POINT (4.405200 51.222900)",
  54.             "city": "Antwerp",
  55.             "name": "Letterenhuis"
  56.         },
  57.         {
  58.             "index": {
  59.                 "_id": 5
  60.             }
  61.         },
  62.         {
  63.             "location": "POINT (2.336389 48.861111)",
  64.             "city": "Paris",
  65.             "name": "Musée du Louvre"
  66.         },
  67.         {
  68.             "index": {
  69.                 "_id": 6
  70.             }
  71.         },
  72.         {
  73.             "location": "POINT (2.327000 48.860000)",
  74.             "city": "Paris",
  75.             "name": "Musée d'Orsay"
  76.         }
  77.     ],
  78. )
  79. print(resp1)
  81. resp2 = client.search(
  82.     index="museums",
  83.     size="0",
  84.     aggs={
  85.         "centroid": {
  86.             "geo_centroid": {
  87.                 "field": "location"
  88.             }
  89.         }
  90.     },
  91. )
  92. print(resp2)
  1. response = client.indices.create(
  2.   index: 'museums',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         location: {
  7.           type: 'geo_point'
  8.         }
  9.       }
  10.     }
  11.   }
  12. )
  13. puts response
  15. response = client.bulk(
  16.   index: 'museums',
  17.   refresh: true,
  18.   body: [
  19.     {
  20.       index: {
  21.         _id: 1
  22.       }
  23.     },
  24.     {
  25.       location: 'POINT (4.912350 52.374081)',
  26.       city: 'Amsterdam',
  27.       name: 'NEMO Science Museum'
  28.     },
  29.     {
  30.       index: {
  31.         _id: 2
  32.       }
  33.     },
  34.     {
  35.       location: 'POINT (4.901618 52.369219)',
  36.       city: 'Amsterdam',
  37.       name: 'Museum Het Rembrandthuis'
  38.     },
  39.     {
  40.       index: {
  41.         _id: 3
  42.       }
  43.     },
  44.     {
  45.       location: 'POINT (4.914722 52.371667)',
  46.       city: 'Amsterdam',
  47.       name: 'Nederlands Scheepvaartmuseum'
  48.     },
  49.     {
  50.       index: {
  51.         _id: 4
  52.       }
  53.     },
  54.     {
  55.       location: 'POINT (4.405200 51.222900)',
  56.       city: 'Antwerp',
  57.       name: 'Letterenhuis'
  58.     },
  59.     {
  60.       index: {
  61.         _id: 5
  62.       }
  63.     },
  64.     {
  65.       location: 'POINT (2.336389 48.861111)',
  66.       city: 'Paris',
  67.       name: 'Musée du Louvre'
  68.     },
  69.     {
  70.       index: {
  71.         _id: 6
  72.       }
  73.     },
  74.     {
  75.       location: 'POINT (2.327000 48.860000)',
  76.       city: 'Paris',
  77.       name: "Musée d'Orsay"
  78.     }
  79.   ]
  80. )
  81. puts response
  83. response = client.search(
  84.   index: 'museums',
  85.   size: 0,
  86.   body: {
  87.     aggregations: {
  88.       centroid: {
  89.         geo_centroid: {
  90.           field: 'location'
  91.         }
  92.       }
  93.     }
  94.   }
  95. )
  96. puts response
  1. const response = await client.indices.create({
  2.   index: "museums",
  3.   mappings: {
  4.     properties: {
  5.       location: {
  6.         type: "geo_point",
  7.       },
  8.     },
  9.   },
  10. });
  11. console.log(response);
  13. const response1 = await client.bulk({
  14.   index: "museums",
  15.   refresh: "true",
  16.   operations: [
  17.     {
  18.       index: {
  19.         _id: 1,
  20.       },
  21.     },
  22.     {
  23.       location: "POINT (4.912350 52.374081)",
  24.       city: "Amsterdam",
  25.       name: "NEMO Science Museum",
  26.     },
  27.     {
  28.       index: {
  29.         _id: 2,
  30.       },
  31.     },
  32.     {
  33.       location: "POINT (4.901618 52.369219)",
  34.       city: "Amsterdam",
  35.       name: "Museum Het Rembrandthuis",
  36.     },
  37.     {
  38.       index: {
  39.         _id: 3,
  40.       },
  41.     },
  42.     {
  43.       location: "POINT (4.914722 52.371667)",
  44.       city: "Amsterdam",
  45.       name: "Nederlands Scheepvaartmuseum",
  46.     },
  47.     {
  48.       index: {
  49.         _id: 4,
  50.       },
  51.     },
  52.     {
  53.       location: "POINT (4.405200 51.222900)",
  54.       city: "Antwerp",
  55.       name: "Letterenhuis",
  56.     },
  57.     {
  58.       index: {
  59.         _id: 5,
  60.       },
  61.     },
  62.     {
  63.       location: "POINT (2.336389 48.861111)",
  64.       city: "Paris",
  65.       name: "Musée du Louvre",
  66.     },
  67.     {
  68.       index: {
  69.         _id: 6,
  70.       },
  71.     },
  72.     {
  73.       location: "POINT (2.327000 48.860000)",
  74.       city: "Paris",
  75.       name: "Musée d'Orsay",
  76.     },
  77.   ],
  78. });
  79. console.log(response1);
  81. const response2 = await client.search({
  82.   index: "museums",
  83.   size: 0,
  84.   aggs: {
  85.     centroid: {
  86.       geo_centroid: {
  87.         field: "location",
  88.       },
  89.     },
  90.   },
  91. });
  92. console.log(response2);
  1. PUT /museums
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "location": {
  6.         "type": "geo_point"
  7.       }
  8.     }
  9.   }
  10. }
  12. POST /museums/_bulk?refresh
  13. {"index":{"_id":1}}
  14. {"location": "POINT (4.912350 52.374081)", "city": "Amsterdam", "name": "NEMO Science Museum"}
  15. {"index":{"_id":2}}
  16. {"location": "POINT (4.901618 52.369219)", "city": "Amsterdam", "name": "Museum Het Rembrandthuis"}
  17. {"index":{"_id":3}}
  18. {"location": "POINT (4.914722 52.371667)", "city": "Amsterdam", "name": "Nederlands Scheepvaartmuseum"}
  19. {"index":{"_id":4}}
  20. {"location": "POINT (4.405200 51.222900)", "city": "Antwerp", "name": "Letterenhuis"}
  21. {"index":{"_id":5}}
  22. {"location": "POINT (2.336389 48.861111)", "city": "Paris", "name": "Musée du Louvre"}
  23. {"index":{"_id":6}}
  24. {"location": "POINT (2.327000 48.860000)", "city": "Paris", "name": "Musée d'Orsay"}
  26. POST /museums/_search?size=0
  27. {
  28.   "aggs": {
  29.     "centroid": {
  30.       "geo_centroid": {
  31.         "field": "location" 
  32.       }
  33.     }
  34.   }
  35. }

The geo_centroid aggregation specifies the field to use for computing the centroid. (NOTE: field must be a Geopoint type)

The above aggregation demonstrates how one would compute the centroid of the location field for all museums’ documents.

The response for the above aggregation:

  1. {
  2.   ...
  3.   "aggregations": {
  4.     "centroid": {
  5.       "location": {
  6.         "lat": 51.00982965203002,
  7.         "lon": 3.9662131341174245
  8.       },
  9.       "count": 6
  10.     }
  11.   }
  12. }

The geo_centroid aggregation is more interesting when combined as a sub-aggregation to other bucket aggregations.

Example:

  1. resp = client.search(
  2.     index="museums",
  3.     size="0",
  4.     aggs={
  5.         "cities": {
  6.             "terms": {
  7.                 "field": "city.keyword"
  8.             },
  9.             "aggs": {
  10.                 "centroid": {
  11.                     "geo_centroid": {
  12.                         "field": "location"
  13.                     }
  14.                 }
  15.             }
  16.         }
  17.     },
  18. )
  19. print(resp)
  1. response = client.search(
  2.   index: 'museums',
  3.   size: 0,
  4.   body: {
  5.     aggregations: {
  6.       cities: {
  7.         terms: {
  8.           field: 'city.keyword'
  9.         },
  10.         aggregations: {
  11.           centroid: {
  12.             geo_centroid: {
  13.               field: 'location'
  14.             }
  15.           }
  16.         }
  17.       }
  18.     }
  19.   }
  20. )
  21. puts response
  1. const response = await client.search({
  2.   index: "museums",
  3.   size: 0,
  4.   aggs: {
  5.     cities: {
  6.       terms: {
  7.         field: "city.keyword",
  8.       },
  9.       aggs: {
  10.         centroid: {
  11.           geo_centroid: {
  12.             field: "location",
  13.           },
  14.         },
  15.       },
  16.     },
  17.   },
  18. });
  19. console.log(response);
  1. POST /museums/_search?size=0
  2. {
  3.   "aggs": {
  4.     "cities": {
  5.       "terms": { "field": "city.keyword" },
  6.       "aggs": {
  7.         "centroid": {
  8.           "geo_centroid": { "field": "location" }
  9.         }
  10.       }
  11.     }
  12.   }
  13. }

The above example uses geo_centroid as a sub-aggregation to a terms bucket aggregation for finding the central location for museums in each city.

The response for the above aggregation:

  1. {
  2.   ...
  3.   "aggregations": {
  4.     "cities": {
  5.       "sum_other_doc_count": 0,
  6.       "doc_count_error_upper_bound": 0,
  7.       "buckets": [
  8.         {
  9.           "key": "Amsterdam",
  10.           "doc_count": 3,
  11.           "centroid": {
  12.             "location": {
  13.               "lat": 52.371655656024814,
  14.               "lon": 4.909563297405839
  15.             },
  16.             "count": 3
  17.           }
  18.         },
  19.         {
  20.           "key": "Paris",
  21.           "doc_count": 2,
  22.           "centroid": {
  23.             "location": {
  24.               "lat": 48.86055548675358,
  25.               "lon": 2.3316944623366
  26.             },
  27.             "count": 2
  28.           }
  29.         },
  30.         {
  31.           "key": "Antwerp",
  32.           "doc_count": 1,
  33.           "centroid": {
  34.             "location": {
  35.               "lat": 51.22289997059852,
  36.               "lon": 4.40519998781383
  37.             },
  38.             "count": 1
  39.           }
  40.         }
  41.       ]
  42.     }
  43.   }
  44. }

Geo Centroid Aggregation on geo_shape fields

The centroid metric for geoshapes is more nuanced than for points. The centroid of a specific aggregation bucket containing shapes is the centroid of the highest-dimensionality shape type in the bucket. For example, if a bucket contains shapes comprising of polygons and lines, then the lines do not contribute to the centroid metric. Each type of shape’s centroid is calculated differently. Envelopes and circles ingested via the Circle are treated as polygons.

Geometry TypeCentroid Calculation

[Multi]Point

equally weighted average of all the coordinates

[Multi]LineString

a weighted average of all the centroids of each segment, where the weight of each segment is its length in degrees

[Multi]Polygon

a weighted average of all the centroids of all the triangles of a polygon where the triangles are formed by every two consecutive vertices and the starting-point. holes have negative weights. weights represent the area of the triangle in deg^2 calculated

GeometryCollection

The centroid of all the underlying geometries with the highest dimension. If Polygons and Lines and/or Points, then lines and/or points are ignored. If Lines and Points, then points are ignored

Example:

  1. resp = client.indices.create(
  2.     index="places",
  3.     mappings={
  4.         "properties": {
  5.             "geometry": {
  6.                 "type": "geo_shape"
  7.             }
  8.         }
  9.     },
  10. )
  11. print(resp)
  13. resp1 = client.bulk(
  14.     index="places",
  15.     refresh=True,
  16.     operations=[
  17.         {
  18.             "index": {
  19.                 "_id": 1
  20.             }
  21.         },
  22.         {
  23.             "name": "NEMO Science Museum",
  24.             "geometry": "POINT(4.912350 52.374081)"
  25.         },
  26.         {
  27.             "index": {
  28.                 "_id": 2
  29.             }
  30.         },
  31.         {
  32.             "name": "Sportpark De Weeren",
  33.             "geometry": {
  34.                 "type": "Polygon",
  35.                 "coordinates": [
  36.                     [
  37.                         [
  38.                             4.965305328369141,
  39.                             52.39347642069457
  40.                         ],
  41.                         [
  42.                             4.966979026794433,
  43.                             52.391721758934835
  44.                         ],
  45.                         [
  46.                             4.969425201416015,
  47.                             52.39238958618537
  48.                         ],
  49.                         [
  50.                             4.967944622039794,
  51.                             52.39420969150824
  52.                         ],
  53.                         [
  54.                             4.965305328369141,
  55.                             52.39347642069457
  56.                         ]
  57.                     ]
  58.                 ]
  59.             }
  60.         }
  61.     ],
  62. )
  63. print(resp1)
  65. resp2 = client.search(
  66.     index="places",
  67.     size="0",
  68.     aggs={
  69.         "centroid": {
  70.             "geo_centroid": {
  71.                 "field": "geometry"
  72.             }
  73.         }
  74.     },
  75. )
  76. print(resp2)
  1. response = client.indices.create(
  2.   index: 'places',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         geometry: {
  7.           type: 'geo_shape'
  8.         }
  9.       }
  10.     }
  11.   }
  12. )
  13. puts response
  15. response = client.bulk(
  16.   index: 'places',
  17.   refresh: true,
  18.   body: [
  19.     {
  20.       index: {
  21.         _id: 1
  22.       }
  23.     },
  24.     {
  25.       name: 'NEMO Science Museum',
  26.       geometry: 'POINT(4.912350 52.374081)'
  27.     },
  28.     {
  29.       index: {
  30.         _id: 2
  31.       }
  32.     },
  33.     {
  34.       name: 'Sportpark De Weeren',
  35.       geometry: {
  36.         type: 'Polygon',
  37.         coordinates: [
  38.           [
  39.             [
  40.               4.965305328369141,
  41.               52.39347642069457
  42.             ],
  43.             [
  44.               4.966979026794433,
  45.               52.391721758934835
  46.             ],
  47.             [
  48.               4.969425201416015,
  49.               52.39238958618537
  50.             ],
  51.             [
  52.               4.967944622039794,
  53.               52.39420969150824
  54.             ],
  55.             [
  56.               4.965305328369141,
  57.               52.39347642069457
  58.             ]
  59.           ]
  60.         ]
  61.       }
  62.     }
  63.   ]
  64. )
  65. puts response
  67. response = client.search(
  68.   index: 'places',
  69.   size: 0,
  70.   body: {
  71.     aggregations: {
  72.       centroid: {
  73.         geo_centroid: {
  74.           field: 'geometry'
  75.         }
  76.       }
  77.     }
  78.   }
  79. )
  80. puts response
  1. const response = await client.indices.create({
  2.   index: "places",
  3.   mappings: {
  4.     properties: {
  5.       geometry: {
  6.         type: "geo_shape",
  7.       },
  8.     },
  9.   },
  10. });
  11. console.log(response);
  13. const response1 = await client.bulk({
  14.   index: "places",
  15.   refresh: "true",
  16.   operations: [
  17.     {
  18.       index: {
  19.         _id: 1,
  20.       },
  21.     },
  22.     {
  23.       name: "NEMO Science Museum",
  24.       geometry: "POINT(4.912350 52.374081)",
  25.     },
  26.     {
  27.       index: {
  28.         _id: 2,
  29.       },
  30.     },
  31.     {
  32.       name: "Sportpark De Weeren",
  33.       geometry: {
  34.         type: "Polygon",
  35.         coordinates: [
  36.           [
  37.             [4.965305328369141, 52.39347642069457],
  38.             [4.966979026794433, 52.391721758934835],
  39.             [4.969425201416015, 52.39238958618537],
  40.             [4.967944622039794, 52.39420969150824],
  41.             [4.965305328369141, 52.39347642069457],
  42.           ],
  43.         ],
  44.       },
  45.     },
  46.   ],
  47. });
  48. console.log(response1);
  50. const response2 = await client.search({
  51.   index: "places",
  52.   size: 0,
  53.   aggs: {
  54.     centroid: {
  55.       geo_centroid: {
  56.         field: "geometry",
  57.       },
  58.     },
  59.   },
  60. });
  61. console.log(response2);
  1. PUT /places
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "geometry": {
  6.         "type": "geo_shape"
  7.       }
  8.     }
  9.   }
  10. }
  12. POST /places/_bulk?refresh
  13. {"index":{"_id":1}}
  14. {"name": "NEMO Science Museum", "geometry": "POINT(4.912350 52.374081)" }
  15. {"index":{"_id":2}}
  16. {"name": "Sportpark De Weeren", "geometry": { "type": "Polygon", "coordinates": [ [ [ 4.965305328369141, 52.39347642069457 ], [ 4.966979026794433, 52.391721758934835 ], [ 4.969425201416015, 52.39238958618537 ], [ 4.967944622039794, 52.39420969150824 ], [ 4.965305328369141, 52.39347642069457 ] ] ] } }
  18. POST /places/_search?size=0
  19. {
  20.   "aggs": {
  21.     "centroid": {
  22.       "geo_centroid": {
  23.         "field": "geometry"
  24.       }
  25.     }
  26.   }
  27. }
  1. {
  2.   ...
  3.   "aggregations": {
  4.     "centroid": {
  5.       "location": {
  6.         "lat": 52.39296147599816,
  7.         "lon": 4.967404240742326
  8.       },
  9.       "count": 2
  10.     }
  11.   }
  12. }

Using geo_centroid as a sub-aggregation of geohash_grid

The geohash_grid aggregation places documents, not individual geopoints, into buckets. If a document’s geo_point field contains multiple values, the document could be assigned to multiple buckets, even if one or more of its geopoints are outside the bucket boundaries.

If a geocentroid sub-aggregation is also used, each centroid is calculated using all geopoints in a bucket, including those outside the bucket boundaries. This can result in centroids outside of bucket boundaries.