Support grouping aggregations by geographic tile

[zandt-square]

Feature request

I'd like to explore adding geographic grouping for GeoLocation fields.

For some context, we can currently group records by dimensions such as status, category, country, region, etc. I'd like to group by smaller geographic areas so we can visualize how activity varies by location.

Geographic filtering helps when we already know which area to look at. A grouping would help us figure out where to look in the first place.

There's a few use cases where I think this could add value:

• Visualize periods of low and high activity across geographic areas based on time of day.
• Monitor adoption during geographically targeted feature rollouts.

Proposed API

Would it be feasible to expose an asGeoTile grouping on GeoLocation fields? For example, using an illustrative event schema:

query ActivityByGeoTile {
  eventAggregations(
    filter: {
      createdAt: {
        gte: "2026-09-29T00:00:00Z"
        lt: "2026-09-30T00:00:00Z"
      }
    }
  ) {
    nodes {
      count
      groupedBy {
        status
        location {
          asGeoTile(precision: 8)
        }
      }
    }
  }
}

The result could be a tile key such as 8/x/y, which the client can use to visualize the results on a map.

Precision corresponds to a Web Mercator zoom level. Precision 8 produces tiles about 98 miles wide at the equator, though the size varies by latitude. That seems like a reasonable starting point, with the precision configurable depending on the query.

How this might fit

Looking at the existing date/time grouping API, asGeoTile seems like it could follow a similar pattern through a GeoLocationGroupedBy type.

Root aggregations already use composite sources to combine grouping dimensions and paginate results. Both Elasticsearch and OpenSearch support a geotile_grid composite source, so that seems like a possible way to add this while preserving the existing behavior.

We'd need to explicitly enable grouping for GeoLocation, since objects with custom mappings aren't currently included in groupedBy. Precision limits and support for nested sub-aggregations would also need some thought.

I'm open to a different API shape, but wanted to raise this for discussion before getting into an implementation.

References:

• OpenSearch composite aggregation
• ElasticGraph date/time grouping

[myronmarston]

I'm on board with this idea. Some random thoughts/questions...

• I like asGeoTile as an analog to asDateTime/asDate/asTimeOfDay/etc on the DateTime grouping API. In general, I think that we should always adopt a asXyz API when the type returned by the grouping differs from the field's raw type. That makes it explicit and leaves open the door for other representations.
• When we introduced asDateTime/asDate/asTimeOfDay/etc we had to roll it out carefully because it was a breaking change to our query API. (We offered a schema option to continue generating the old legacy schema for DateTime grouping). Luckily, we don't have that issue here--it looks like GeoLocation fields are not included under groupedBy today, so this would be a net-new field.
• Elasticsearch/OpenSearch return the geo tile values as a string in this format: {{zoom}}/{x}/{{y}}. I'm not sure why the docs use one set of curlies around x but 2 sets around zoom and y--do you know? What does that mean?
• With the richer type system of GraphQL, I'd like us to return it as an object. Maybe something like this?

type GeoTile {
  latitude: Float
  longitude: Float
  zoomLevel: Int
}

Although now I'm thinking this might make more sense:

type GeoTile {
  centerPoint: GeoLocation
  zoomLevel: Int
}

I think I lean that way, but let me know which you prefer.

• For the argument, I'd rather it be called zoomLevel instead of precision--while precision is the term Elasticsearch/OpenSearch use, we don't always want to match their API exactly--our API is meant to stand-alone and not make it super obvious that it translates to Elasticsearch queries. And I think zoomLevel reads better and allows us to reference https://wiki.openstreetmap.org/wiki/Zoom_levels from the docs.
• You mention defaulting the zoom level to 8. Elasticsearch/OpenSearch both default it to 7: https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-geotilegrid-aggregation#_options_5 / https://docs.opensearch.org/latest/aggregations/bucket/geotile-grid/#supported-parameters. I'd lean towards the same default.

@zandt-square are you planning to implement this?

[zandt-square]

Thanks @myronmarston. I'd like to put together an implementation.

asGeoTile(zoomLevel: ...) makes sense to me, and I'm good with defaulting to 7. I prefer the centerPoint: GeoLocation shape too. That seems more convenient for clients plotting the results, and clients could calculate the tile bounds if needed.

For example, with asGeoTile(zoomLevel: 8), the response could look like this:

{
  "data": {
    "eventAggregations": {
      "nodes": [
        {
          "count": 1250,
          "groupedBy": {
            "status": "SUCCESS",
            "location": {
              "asGeoTile": {
                "centerPoint": {
                  "latitude": 37.1603,
                  "longitude": -123.046875
                },
                "zoomLevel": 8
              }
            }
          }
        }
      ]
    }
  }
}

We should document that this is the center of a Web Mercator XYZ tile, rather than the average location of the records in the bucket. That would also make it clear how to interpret the zoom level.

On the curly braces, I think that's just inconsistent placeholder notation in the docs. The actual value would look like 8/40/99.

[myronmarston]

I think GeoTile should expose more than the zoom/x/y key. The key is only the compact form that the datastore returns.

Here's what I'd recommend:

type GeoTile {
  zoomLevel: Int!
  x: Int!
  y: Int!
  centerPoint: GeoLocation!
  bounds: GeoTileBounds!
  corners: GeoTileCorners!
}

type GeoTileBounds {
  north: Float!  # latitude
  south: Float!  # latitude
  east: Float!   # longitude
  west: Float!   # longitude
}

type GeoTileCorners {
  northWest: GeoLocation!
  northEast: GeoLocation!
  southWest: GeoLocation!
  southEast: GeoLocation!
}

Each field above comes from the key with one or two lines of math. The client selects only the fields it needs.

How each field is calculated

With n = 2^zoomLevel:

Field	Formula
zoomLevel, x, y	Split the zoom/x/y key
bounds.west	x / n * 360 - 180
bounds.east	(x + 1) / n * 360 - 180
bounds.north	atan(sinh(π * (1 - 2y / n))), in degrees
bounds.south	Same as bounds.north, with y + 1
centerPoint	Same formulas, with x + 0.5 and y + 0.5
corners	One latitude bound with one longitude bound. No new math.

Both datastores use these formulas: Elasticsearch GeoTileUtils (toBoundingBox, zxyToGeoPoint) and OpenSearch GeoTileUtils. Our values will match theirs:

• Below zoom level 20, the values match exactly, except for small differences from their approximate sinh/atan functions.
• At zoom level 20 and above, Elasticsearch moves latitude bounds to the nearest Lucene coordinate. The difference is less than 1 cm.

Example tile 8/40/99:

Field	Value
centerPoint	37.160317, -123.046875 (the same as @zandt-square's example above)
bounds.north / bounds.south	37.718590 / 36.597889
bounds.west / bounds.east	-123.75 / -122.34375

Why each field is included

• x and y: Map tile libraries and tile URL templates (.../{z}/{x}/{y}.png) use them. To get them from centerPoint, the client must run the projection math in reverse.
• bounds: The common map APIs take a bounding box: Leaflet L.rectangle, Mapbox LngLatBounds, Google LatLngBounds. The client cannot get the bounds from centerPoint and zoomLevel without the Mercator formula.
• corners: These repeat the bounds in a different shape. They do not add new math, so they cannot be wrong. But they let a client make a polygon (GeoJSON, deck.gl) without having to assemble the points.

Naming

• bounds { north south east west } uses the same names as GeoJSON bbox ([west, south, east, north]) and Leaflet/Mapbox (getNorth(), getWest()). The nested object also keeps the four values together for clients that give them directly to a map API. We should not use northBound, because "northbound" usually means "moving north", as in traffic.

• corners { northWest ... } has the same shape as bounds, for the same reasons.

• centerPoint is the center of the tile on a Web Mercator map. It is NOT the midpoint of bounds.north and bounds.south. At high zoom levels the two values are almost the same, but at low zoom levels they are very different. For tile 1/0/0:

  • centerPoint latitude: 66.51°
  • Midpoint of the two latitudes: 42.53°

  Elasticsearch and OpenSearch also use the Web Mercator center. We should document this.

Fields I recommend we do not include

Field	Why not
width / height / side length as a distance	A tile is square only in projected Web Mercator meters (40,075,016.686 m / 2^zoom), and that is not a distance on the ground. The ground width changes across the tile because it depends on cos(latitude). For 8/40/99, the north edge is 123.7 km and the south edge is 125.5 km. For 1/0/0, they are 1,727 km and 20,015 km. A single number would be wrong for most of the tile.
Width or height in degrees	The longitude span is always 360 / 2^zoom, and the client gets it with bounds.east - bounds.west. The latitude span is different for each row. A tile never crosses the antimeridian, so the subtraction is always correct.
area	On a sphere the formula is simple (R² · Δλ · (sin φN − sin φS)). But the result depends on which Earth model we use (sphere or WGS84 ellipsoid). It is not a value we can calculate "accurately" without making that choice.
Grid size (2^zoomLevel)	The grid is always square, so this is one value. It is the same for every tile at a zoom level, and the client calculates it from zoomLevel.
key ("8/40/99" string)	This shows the datastore format in our API. It is also easy to make from zoomLevel, x, and y.
quadkey (Bing format)	Easy to calculate, but few clients use it. We can add it later if a client asks.
Parent or child tiles	Easy to calculate (z - 1, x >> 1, y >> 1), but there is no use case yet. We can add it later.

Behavior to document

• The range of x and y is 0 to 2^zoomLevel − 1. x = 0 is the west edge (−180°) and y = 0 is the north edge (85.0511°).
• The tile bounds do not include the poles. Web Mercator stops at ±85.0511°. The datastore puts points north of 85.0511° in row y = 0, and points south of -85.0511° in the last row. Because of this, a point can be outside the bounds of the tile it is grouped into.
• Points on a boundary go to the tile to the east or the south. The datastore uses floor to calculate x and y. A point exactly on bounds.west or bounds.north is in this tile. A point on bounds.east or bounds.south is in the next tile.

[zandt-square]

Thanks @myronmarston. I put together a draft PR following your suggested API: #1436

It supports root and nested aggregations and returns the tile coordinates, center point, bounds, and corners. The docs also clarify that the center point is the Web Mercator center, not the average record location.

Would appreciate your feedback on the API shape before I mark it ready for review.