PlazaQL

A LINQ-style query language for geospatial data. PlazaQL provides a composable, chainable syntax for searching, filtering, routing, geocoding, and transforming OpenStreetMap data through the Plaza API.

search(node, amenity: "cafe")
  .within(boundary(name: "Manhattan, New York"))
  .around(200, point(40.7484, -73.9856))
  .fields("name", "cuisine", "opening_hours")
  .sort(t["name"])
  .limit(10);

File Extension

.pql

Quick Examples

Find restaurants near a point:

search(node, amenity: "restaurant")
  .around(500, point(48.8566, 2.3522))
  .limit(20);

Walking isochrone with nearby parks:

$$.area = isochrone(center: point(40.71, -74.00), time: 900, mode: "foot");
$$.parks = search(way, leisure: "park").within($$.area);

Geocode and search nearby:

$home = geocode("350 Fifth Avenue, New York");
search(node, shop: "supermarket")
  .around(500, $home)
  .sort(distance($home))
  .limit(5);

Expression filter and aggregation:

search(way, building: "yes")
  .within(boundary(name: "Manhattan, New York"))
  .filter(is_number(t["height"]) && number(t["height"]) > 50)
  .group_by(t["building"])
  .count();

Global directive scoping:

#within(geometry: boundary(name: "Berlin"));
#filter(wheelchair: "yes");

$$.cafes = search(node, amenity: "cafe").limit(10);
$$.restaurants = search(node, amenity: "restaurant").limit(10);

---

Table of Contents

• Syntax Overview
• Comments
• Variables
• Output Assignment
• Type System
• Functions
• Geometry Constructors
• Methods
• Tag Filters
• Set Operations
• Global Directives
• Expression Language
• Aggregation
• Chain Ordering
• Argument Style
• Error Messages
• Grammar
• Using the Elixir library

---

Syntax Overview

A PlazaQL query is a sequence of statements, each terminated by ;. Statements are either:

• Bare expression: expression; (implicit output)
• Variable assignment: $name = expression;
• Output assignment: $$ = expression; or $$.name = expression;
• Global directive: #method(args); (applies to all subsequent queries)

Expressions are built from functions (which produce values), methods (which transform values via chaining), and operators (union +, difference -, intersection &).

// Variable — stores a value for reuse
$area = boundary(name: "Berlin, Germany");

// Bare expression — implicitly becomes the output
search(node, amenity: "cafe")
  .within($area)
  .limit(10);

---

Comments

// Line comment — everything after // is ignored

/* Block comment —
   can span multiple lines */

/* Nested comments are supported —
   /* inner comment */
   still inside the outer comment */

---

Variables

Variables store intermediate values for reuse. Names start with $ followed by a letter or underscore.

$center = point(40.7128, -74.0060);
$radius = 500;
$nyc = boundary(name: "New York City");

// Use in subsequent expressions
search(node, amenity: "cafe")
  .around($radius, $center)
  .within($nyc);

Variables are immutable — once assigned, they cannot be reassigned.

A variable holding a literal (point(...), linestring(...), polygon(...), bbox(...), circle(...) or a number) is replaced by that literal wherever it is used, so .around($radius, $center) compiles exactly like .around(500, point(40.7128, -74.0060)). A literal is a value, not a query: $center; on its own is a compile error. A variable holding a search, boundary or computation runs once, before the statements that use it.

Named output variables ($$.name) can also be used as values in later expressions — see Output Assignment.

---

Output Assignment

Every query must produce at least one output. This defines what gets returned.

Single output — bare expression (preferred):

search(node, amenity: "cafe").limit(10);

A bare expression statement is equivalent to $$ = expression;. The explicit $$ = prefix is supported but optional for single-output queries:

$$ = search(node, amenity: "cafe").limit(10);

Named outputs — return multiple result sets:

$$.cafes = search(node, amenity: "cafe").limit(5);
$$.parks = search(way, leisure: "park").limit(5);
$$.route = route(origin: point(40.71, -74.00), destination: point(40.75, -73.98));

Named output references — $$.name values can be referenced in later statements, eliminating the need for intermediate variables:

$$.route = route(origin: point(40.71, -74.00), destination: point(40.75, -73.98));
$$.stops = search(node, amenity: "cafe").around(200, $$.route);

This is equivalent to the more verbose:

$r = route(origin: point(40.71, -74.00), destination: point(40.75, -73.98));
$$.route = $r;
$$.stops = search(node, amenity: "cafe").around(200, $r);

Named outputs are immutable — once assigned, they cannot be reassigned.

---

Type System

Geometry Types

Value types used as arguments to spatial methods and constructors.

Type	Constructor	Description
Point	point(lat, lng)	Single coordinate
LineString	linestring(p1, p2, ...)	Ordered sequence of points
Polygon	polygon(p1, p2, p3, ...)	Closed ring of points
	bbox(south, west, north, east)	Bounding box (shorthand)

This is the beginning of the README. Read the rest at the original. Read the full README ↗