Geo centroid aggregation #

A metrics aggregation computing the centroid (mean latitude and longitude) of all geo_point values.

How it works #

The engine sums latitudes and longitudes across the bucket’s geo_point values and divides by the count:

{
  "location": { "lat": .., "lon": .. },
  "count": 15
}

• The mean is arithmetic per axis (a planar average, not spherical) — exact enough at city or country scale, drifting only for extents that cross the 180th meridian or span hemispheres.
• Every parseable point counts once; there is no weight field. The result is null when the bucket holds no points.
• Under distributed fan-out the coordinator keeps its own shard’s value (geo metrics have no mergeable intermediate), so single-node results are the exact ones.
• Like every geo_point consumer, the aggregation sees points normalized at ingestion: {"lat": .., "lon": ..}, [lon, lat] (longitude first) or a "lat,lon" string, all stored as two-dimensional BKD points.

Examples #

Returns the count of points and their centroid — the natural center point for map placement. Over the 15 places: count: 15, location about {lat 31.7484, lon 111.2181}.

A centroid per city — the usual bucketed form:

POST /places/_search
{
  "size": 0,
  "aggs": {
    "cities": {
      "terms": { "field": "city" },
      "aggs": {
        "pin": { "geo_centroid": { "field": "location" } }
      }
    }
  }
}

Beijing’s bucket averages its two stores; every other city has one point and its centroid is that point.

Use cases #

• Center the map — the initial camera position over a result set, cheaper than fetching every point.
• Per-city anchors — terms(city) with a geo_centroid inside derives each city’s pin from its own member points (Beijing’s two stores, Shanghai’s two, and so on).
• Facility siting sketch — the mean point of customer or store locations as a first approximation for a depot.
• Cluster labels — pair with geohash grid to place each cell’s label at the cell’s own center.

Parameters for geo_centroid #

• field
  (Required, string) geo_point field you wish to aggregate.

Related #

• geo_bounds — the extent around the same points.
• geohash grid — cluster first, then centroid each cell.
• geo_distance buckets — ring buckets around a point.