PBFX Query Guide

Quick Start

Choose feature typesnodes, ways, and relations limit what can match.

Limit to a local arealimitLocal keeps matching in the current map view, limitLocal(auto) reruns when the view changes, and limitLocal(...) can resolve GPS, bbox, places, streets, or addresses.

Draw resultscoords returns geometry so the result can be rendered on the map.

Explore valuescount(key) counts distinct values instead of returning full geometry.

ways
limitLocal
coords
highway=*

limitLocal("Zoo Leipzig")
building=*
coords

Lines starting with # are comments and ignored by the parser.

Core Directives

nodes, ways, relations: choose feature types
coords: include geometry
limitLocal: restrict to the current map view
limitLocal(gps, 2km): restrict to a radius around the current GPS position
limitLocal(bbox, west, south, east, north): use an explicit bounding box
limitLocal(auto): keep using the current map view and rerun automatically after significant map moves
limitLocal("Zoo Leipzig"): resolve a free-text local area first, then search inside it
limitLocal("Eldenaer Straße", 1km): resolve a free-text local area, add a radius, then search inside it
geocodeOnly("Trischenstraße, Wedel"): Webclient action for pure find/locate requests; it runs the geocoder and positions the map without executing a PBFX search
routeOnly("Danziger Straße 73", from="Alexa", profile=bike): Webclient action for pure route requests; it resolves GPS or a named start plus destination geocode, then runs the normal routing endpoint
coverage: return a raster coverage/heatmap layer instead of normal geometry results
coverage(log, blur=5): use logarithmic scaling and five blur passes for smoother density maps
show(condition): explicitly select the visible/returned feature set
vectorTiles, leanResults, and debugVectorTiles(query,timing,mvt,client,prio): render map-like results as HTTP MapLibre MVT tiles, strip bulky result metadata, and show selected tile diagnostics
external(water_polygons) or external(water_polygons, country_boundaries): include prepared external data sources from ~/temp/external
results 100000: raise or lower the result cap
numTags 5: include more tag information in result items
zoom 10 16: only activate following lines in that zoom range
routing or routing(highway=*|route=ferry): build a route graph, optionally restricted to matching ways (intersections is still accepted as an alias)
routeCost(highway=primary):1.8, routeCost(highway=traffic_signals):+25m, routeCost(oneway=yes):forward, routeCost(access=private):blocked, routeCost(highway=residential):defer(10km), or routeCost(refMaxspeed):20km/h: weight, penalize, set direction, exclude routing graph segments, defer low-priority road classes far away from start and target, or set the ETA reference speed
debugPages and debugTagSets: print debug information to the server log

ways
coords
limitLocal
results 200000

limitLocal(gps, 2km)
amenity=pharmacy
coords

Filters

Use show(...) to choose the returned feature set. Older bare filter lines still work, but show(...) keeps result selection separate from styling, labels, and overlays.

show(highway=*|building=*|natural=water)

Filters are mostly exact. The most common forms are:

key=value
key=*
*=value to match a value across any key
key=a|b|c for several values of the same key
!key=value to exclude matches
(a=b)|(c=d) for explicit OR across different conditions

highway=primary|secondary|trunk
building=*
*=Eldenaer Straße|Hübnerstraße
!highway=street_lamp|traffic_signals|crossing
(railway=station)|(highway=bus_stop)

*=value means: match if any tag value equals that value. This is useful when the same name or identifier may appear under different keys.

Spatial Queries

near(...) adds a simple proximity condition using a radius in meters.

Near, symmetric form

Returns matches from both sides. Outer feature-type directives such as ways apply to the left side.

near(100m, amenity=pharmacy, shop=bakery)
limitLocal

Near, filtering form

Keeps the main query only if it is near the second condition.

shop=bakery
near(100m, amenity=pharmacy)
limitLocal

Inside

Checks whether the left-side feature geometry lies inside matching polygon targets.

inside(highway=path, natural=wood)
limitLocal

inside(A, B) means A inside B. For example, paths in parks should be written as inside($paths,$green), not the other way around.

near(...) samples decoded line geometry for distance checks. inside(...) is a separate, more expensive polygon containment check. Both are supported as top-level query lines, not as fully nestable boolean expressions.

Alpha limitation: top-level spatial filters replace the query result set. Context layers that are not part of the spatial expression are not fetched automatically, so inside($paths,$green) plus show($paths|$green|$water) will not add unrelated water features. Named result sets for expressions like set @pathsInGreen = inside($paths,$green) are planned, but not implemented yet.

Count and Coverage

Use count(key) to count distinct values instead of returning full geometry.

ways
limitLocal
count(surface)

Use coverage when you want a density/coverage raster layer instead of normal geometry results.

nodes
limitLocal
coverage(log, blur=5)
amenity=pharmacy

coverage supports linear, sqrt, and log scaling. The explicit form is coverage(scale=log, blur=5, resolution=256); only resolution=256 is currently supported.

Styles and Labels

Current base style forms:

color(condition):#rrggbb; width=1.5; opacity=0.8
style(condition):#rrggbb; width=1.5; opacity=0.8 as a legacy alias
overlay(condition):#rrggbb; width=1.5; opacity=0.8 for an additional top layer

color(highway=primary):#ed8f54; opacity=0.98; width=3.6
color(building=*):#99948f; opacity=0.42; fill
overlay(surface=cobblestone|sett):#9073dd; opacity=0.35; width=4; line=dash

color() and style() are normal render styles and also act as style filters. overlay() duplicates already visible features as an extra marking and does not replace the base style.

Style options can limit geometry types, choose line patterns, disable picking, or add an outline/casing:

color(highway=primary):#e0613d; opacity=0.98; width=3.8; for=ways; casing=2
color(building=*):#85807a; opacity=0.30; fill; for=ways|relations; casing=1; hit=no
color(railway=rail):#2e2e33c7; width=1.8; for=ways; line=dashdot

Line width and casing use pixels by default. Append m for meters or px explicitly:

color(highway=primary):#e0613d; opacity=0.98; width=6m; casing=1.5m

The map view background can be set with a hex or RGBA color. A color background hides the raster base map for the query:

background:#14171a

The raster base map can also be controlled by the query. Opacity is optional and only applies when the base map is shown:

background:base; opacity=0.55
background:none

When DEM tiles are available, the background can also be drawn from elevation data. Missing tiles are requested in the background and appear after rerunning the query:

background:hillshade; opacity=0.45; azimuth=315; altitude=45; exaggeration=1.4; resolution=384; smooth=3
background:relief; opacity=0.55; exaggeration=1.2

Routing overlays can be styled client-side when routing is active:

color(route):#0059ff; opacity=0.9; width=6; line=dash
color(route:start):#00b340; width=7
color(route:end):#e61a1a; width=7

Routing costs are independent from visual style. Factors multiply weighted meters. A factor of 1 is neutral, lower values are preferred, higher values are avoided. Multiple matching factors multiply. Additive +Xm values add meter-equivalent penalties, blocked removes a segment or node from the route graph, and defer(Xm|Xkm) postpones matching segments while both start and target are farther away than that distance:

routeCost(highway=cycleway):0.45
routeCost(highway=secondary):1.8
routeCost(highway=traffic_signals):+25m
routeCost(barrier=bollard):+12m
routeCost(access=private):blocked
routeCost(highway=residential):defer(10km)
routeCost(refMaxspeed):20km/h
routeCost(elevationProfile):1

Spatial route costs can prefer or avoid routing ways inside matching polygon targets or near matching geometry:

$green = leisure=park|natural=wood|landuse=forest
routeCost(inside($green)):0.5
routeCost(near(20m, highway=primary|highway=secondary)):2.0

Spatial route costs currently annotate the matched route feature. Because route metadata is serialized per returned way, a long way can carry the factor beyond the exact local section that matched the spatial radius or polygon.

Routing direction is another independent routeCost dimension. Later direction rules override earlier ones, without changing the numeric cost:

routeCost(oneway=yes):forward
routeCost(oneway=-1):backward
routeCost(oneway:bicycle=no):both
routeCost(cycleway=opposite):both

When routing is active, start/end placement snaps to the nearest segment. The route overlay reports length, average route cost, type shares, and counted traffic-signal nodes. Server routing applies node-via turn restrictions for car-like profiles and discourages U-turns with an additional turn penalty.

Global output keys use ->name or ->name|ref|maxspeed.

Conditional labels use label(condition):keys with optional label options:

label(place=city):name; prefer=name:de,int_name,name:en,ref; priority=320
label(place=town):name; priority=240
label(highway=primary|secondary):name; priority=120; size=11
label(highway=primary|trunk|motorway):ref; priority=180; shield=road; size=11
label(place=city):name; icon=city; iconSize=14; color=#333333; halo=#ffffffcc; priority=320
label(amenity=restaurant):name; icon=restaurant; iconSize=15; priority=120

prefer=key1,key2 tries preferred label keys first, then falls back to the keys after :.

Common label options: priority=..., size=..., color=#rrggbb, halo=#rrggbbaa, haloWidth=..., placement=point|line|polygon, anchor=..., offset=x,y, icon=..., iconSize=..., and shield=road. Legacy r,g,b,a label colors are still accepted.

icon=name shows a local Maki SVG icon with the label; common names include city, town, village, suburb, capital, restaurant, cafe, pharmacy, hospital, lodging, parking, fuel, bicycle, rail, airport, and museum.

shield=road renders a road ref label horizontally as a shield-style point label on the selected road geometry. Labels do not select features by themselves; keep a matching show(...) or selected filter for the roads.

Image overlays can load Commons thumbnails via Wikidata entity tags:

limitLocal
coords
tourism=museum
->name
->image(64):wikidata

->image(size):wikidata requests the wikidata output key automatically and shows up to a small number of image markers on the map when matching results contain a Wikidata Q-id with a Commons image.

Macros

Macros start with $ and are expanded before normal parsing.

$roads = highway=*
$major = highway=primary|secondary|trunk|motorway

show($roads)
style($major):#ed8f54; opacity=0.98; width=3.6

Function-like macros are also supported:

$road($type,$width)=style(highway=$type):#f2b87a; opacity=0.95; width=$width
$road(primary,3.6)
$road(secondary,2.8)

Examples

Minimal local road map

ways
limitLocal
coords
show(highway=*)
color(highway=*):#ffffff; width=2; for=ways; casing=0.8

Resolve a local place first

ways
relations
limitLocal("Zoo Leipzig")
coords
show(building=*)
color(building=*):#bdbdbd; opacity=0.8; fill; for=ways|relations

Places only

nodes
limitLocal
coords

show(place=city|town|village)
color(place=city|town|village):#333333; width=3; for=nodes; hit=no
label(place=city|town|village):name; priority=260

QA example

nodes
ways
limitLocal
coords

show(addr:housenumber=*)
!addr:street=*
!addr:place=*
!addr:city=*

color(addr:housenumber=*):#ff0000; width=4; for=nodes|ways
->addr:housenumber|addr:city|addr:place|addr:street

Symmetric near

near(100m, amenity=pharmacy, shop=bakery)
color(amenity=pharmacy):#ff0000; width=3
color(shop=bakery):#00ff00; width=3
limitLocal

Not Supported Yet

numeric comparisons such as maxspeed >= 50
regex matching
full boolean expression precedence
multiple simultaneous top-level near(...) / inside(...) filters
named result sets and set algebra such as set @a = inside(...) or show((@a & !@b)|$buildings)
context layers that bypass a top-level spatial filter