Geometry & Spatial Filters

Geometry constructors

PlazaQL has four geometry constructors. All use lat, lng order (how humans say coordinates).

Points

// Keyword args (self-documenting)
$home = point(lat: 38.9, lng: -77.0);

// Positional args (concise)
$work = point(38.85, -77.05);

Line strings

$path = linestring(point(38.9, -77.0), point(38.88, -77.02), point(38.85, -77.05));

Polygons

Polygons auto-close — you don’t need to repeat the first point:

$zone = polygon(
  point(38.8, -77.1),
  point(38.8, -76.9),
  point(39.0, -76.9),
  point(39.0, -77.1)
);

Bounding boxes

A shortcut for a rectangular polygon:

// Keyword: south, west, north, east
$area = bbox(south: 40.7, west: -74.0, north: 40.8, east: -73.9);

// Positional: s, w, n, e
$area = bbox(40.7, -74.0, 40.8, -73.9);

For named places, prefer boundary() over hardcoded coordinates:

$manhattan = boundary(name: "Manhattan");

Composing with variables

Geometry constructors are composable — use variables to build complex shapes from simple ones:

$home = point(38.9, -77.0);
$work = point(38.85, -77.05);
$commute = linestring($home, $work);

search(amenity: "gas_station")
  .around(distance: 200, geometry: $commute);

Spatial filters

Spatial filters narrow results by location. They come after search() (or set operations) in the chain.

.around() — distance from geometry

// Within 500m of a point
search(amenity: "cafe")
  .around(distance: 500, geometry: point(48.85, 2.35));

// Within 200m of a route
$r = route(origin: point(40.748, -73.993), destination: point(40.755, -73.970), mode: "foot");
search(amenity: "bench")
  .around(distance: 200, geometry: $r);

.within() — inside a polygon or area

$paris = boundary(name: "Paris");
search(tourism: "museum").within(geometry: $paris);

// Inline polygon
search(building: *)
  .within(geometry: polygon(
    point(40.7, -74.0), point(40.7, -73.9),
    point(40.8, -73.9), point(40.8, -74.0)
  ));

.intersects() — overlaps with geometry

$river = search(way, waterway: "river", name: "Seine");
search(way, bridge: *).intersects(geometry: $river);

.bbox() — bounding box shortcut

search(amenity: "pub")
  .bbox(south: 51.50, west: -0.13, north: 51.53, east: -0.07);

.h3() — H3 cell filter

search(amenity: "cafe")
  .h3(cell: "8a2a1072b59ffff");

.contains() — feature fully contains geometry

$park = point(40.7829, -73.9654);
search(way, leisure: "park").contains(geometry: $park);

.crosses() and .touches()

$highway = search(way, highway: "motorway", ref: "I-95");
search(way, highway: "primary").crosses(geometry: $highway);

Negated spatial filters

Every spatial filter has a negated form:

$flood_zone = polygon(...);
search(building: "residential")
  .not_within(geometry: $flood_zone);

search(way, landuse: *)
  .not_intersects(geometry: $protected_area);

search(way, building: *)
  .not_contains(geometry: $exclusion_point);

Transforms

Transforms modify the geometry or properties of results.

.buffer() — expand geometries

Add a buffer zone around each feature:

// 50-meter buffer around each school
search(amenity: "school")
  .within(geometry: $city)
  .buffer(50);

Turns points into circles, expands polygons outward. Useful for proximity analysis.

.simplify() — reduce geometry detail

Simplify complex geometries using Douglas-Peucker tolerance:

// Simplify coastlines for overview display
search(way, natural: "coastline")
  .bbox(40.0, -75.0, 42.0, -72.0)
  .simplify(100);

The parameter is tolerance in meters — higher values produce simpler geometries.

.centroid() — replace with center point

Replace each feature’s geometry with its centroid:

// Get center points of all parks
search(way, leisure: "park")
  .within(geometry: $city)
  .centroid();

Converts any GeoSet to a PointSet.