ST_TileEnvelope

What is ST_TileEnvelope?

ST_TileEnvelope is a PostGIS function that returns the bounding box of an XYZ map tile as a Web Mercator POLYGON (SRID 3857). Added in PostGIS 3.0, it is the canonical way to derive a tile's extent for vector tile (MVT) generation.

1ST_TileEnvelope(integer zoom, integer x, integer y,
2                geometry bounds = default_world_bounds,
3                float margin = 0.0) → geometry

The bounds argument defines the extent of zoom level 0 (defaults to the standard Web Mercator world). margin (PostGIS 3.1+) expands the envelope by a fractional amount of tile width, useful for buffered tile generation.

When would you use ST_TileEnvelope?

Use ST_TileEnvelope at the heart of any vector-tile endpoint. A typical MVT pipeline composes it with ST_AsMVTGeom and ST_AsMVT:

1WITH bounds AS (
2  SELECT ST_TileEnvelope(:z, :x, :y) AS geom
3)
4SELECT ST_AsMVT(tile, 'parcels')
5FROM (
6  SELECT id, ST_AsMVTGeom(p.geom, bounds.geom) AS geom
7  FROM parcels p, bounds
8  WHERE p.geom && bounds.geom
9) AS tile;

It is also useful for tile-aligned cache keys, raster extraction by tile, and tile-based parallel processing. Always pass the geometry into spatial filters as geom && tile_env to benefit from the GiST index.

FAQs

Which SRID does ST_TileEnvelope return?

Always EPSG:3857 (Web Mercator). If your source data is in another SRID, wrap the envelope in ST_Transform or transform your data to 3857 for tile generation.

What is the margin parameter for?

margin (PostGIS 3.1+) expands the tile envelope by a fraction of its width — useful when labels or geometry near the tile border need to be included so adjacent tiles can render them cleanly. Typical values are 0.0 to 0.125.

How do ST_TileEnvelope and ST_AsMVTGeom work together?

ST_TileEnvelope produces the spatial extent, and ST_AsMVTGeom uses that extent to clip and snap geometries to the tile's pixel grid. Passing the same envelope to both ensures geometry is correctly localized to the tile.

Can I use custom tile bounds?

Yes. The optional bounds argument replaces the default world extent — useful for non-standard tile schemes or local grids. Supply any square polygon in the target SRID and ST_TileEnvelope will subdivide it at the given zoom.