Location Blocks

Everything RUAL knows about where something is, and what is near it. Coordinate maths, address lookup and points of interest, all answered from datasets on the node.

These blocks run offline, against datasets shipped with the node. No API keys, no rate limits, no per-call cost, and no request leaving the building. Lookups take microseconds, so you can run them inside loops and over whole inventories without thinking about it.

Working With Coordinates

A geo point is an object with lat and lon. These blocks make and manipulate one. None of them touch a dataset: they are pure arithmetic.

Use geo_point_validate as a guard before anything that costs work: a missing or malformed point is the most common reason a location flow silently does nothing. Use geo_point_random_in_radius to anonymise a location before showing it publicly, or to generate plausible test data.

Geocoding: Coordinates To Places, And Back

A coordinate becomes an address

geo_point_reverse_geocode takes a geo_point and returns street, city, neighborhood, province, country, country_code, success and error.

• neighborhood is filled only when the point sits inside a larger city. A point in Ittersum returns city Zwolle and neighbourhood Ittersum, while a point in Siebengewald returns that as the city, because it is a village in its own right rather than part of one.
• street is the nearest named road and needs the road network dataset loaded.

Many coordinates at once

array_reverse_geocode enriches a whole array in one call, with no loop. You give it the path to the geo point inside each item (for example location.location) and the paths to write each result to. Leave an output key empty to skip that field.

A place name becomes a coordinate

geo_point_from_city takes city and country_code, and returns geo_point, radius, province, country, country_code, success and error.

• radius is the city's approximate extent in metres, derived from population. Handy for "is this roughly in Breda" without needing a boundary.
• Pass country_code to disambiguate: there is a Bergen in NL, NO and DE.

Terrain and infrastructure

On geo_point_snap, distance tells you how far the point moved. A large value means the original point was nowhere near a road, which usually means the input was wrong.

Places: Points Of Interest

The places_* blocks are backed by Overture Maps Places, a source of roughly 60 million points of interest in total. The Netherlands is what a node loads by default: roughly 737,000 Dutch shops, schools, stations, restaurants, hospitals and so on. Three ideas explain most of how these blocks behave, and they are worth reading before wiring anything.

Distances, never yes or no

Every spatial block returns the distance in metres, not a boolean. That is deliberate: holding the distances, every question is arithmetic you can do yourself, with no second query.

within 200 m of a school?         nearest_distance_m <= 200
within 317 m?                     nearest_distance_m <= 317
at least 3 schools within 500 m?  results[2].distance_m <= 500
NOT within 500 m of a school?     nearest_distance_m > 500

So a radius slider in your UI never re-queries, and no radius is ever baked into stored data where changing it would mean reprocessing everything.

Categories accept plain Dutch

Anywhere a block has a categories pin, you can pass group ids or ordinary words. Regular plurals are handled.

places_categories lists everything available, and places_resolve_category turns one word into a group id.

Duplicates are collapsed, and the result says so

Overture is not deduplicated. Around Breda station the raw data holds three separate records for one station: Station Breda Centraal, Gare de Bréda and NS Station Breda. With dedup on (the default) those merge into one result, reported as merged_count: 3 with merged_names listing all three. Meanwhile the bike shed, the car park, the park called Happy Station, the Playmobil museum and the neighbourhood council all stay separate: they are different things that happen to share a word.

places_within reports both raw_count and count. The gap between them tells you how much duplication the source data carries at that spot. Treat count as a tidy search result, not a census: nationally the data holds 1,432 train_station records against roughly 400 real stations.

Finding places

Results from places_in_bbox carry no distance: a box has no centre. Use places_nearest when you need distances. On places_density, classification is dense_urban, urban, suburban or rural, driven by the per square kilometre rate, so it does not change when you change the radius.

Working over a whole inventory

These blocks exist so you never write a loop.

Each item that places_enrich touches gets one entry per category:

{
  "places": {
    "hospital": {
      "count": 0,
      "distance_m": 1840,
      "id": "...",
      "name": "..."
    },
    "primary_education": {
      "count": 3,
      "distance_m": 212,
      "id": "...",
      "name": "..."
    }
  }
}

Items are copied, never modified in place, and every item comes back whether or not it had a usable coordinate. Check unresolved before writing back. places_facet counts items, not places: an object with three hospitals nearby counts once.

Search and typed questions

places_search is one search box over places and towns. It takes query (required), near, bias_radius_m (25000), kinds (poi/settlement), categories, limit (10), typo_tolerance (2), min_confidence and dedup, and returns results, best, count, success and error.

• Handles accents (Bréda finds Breda), typos (amsterdm centraal) and partial words as you type.
• Towns outrank businesses, so Breda gives you the municipality rather than one of the roughly 2,000 companies with Breda in the name.
• Pass near (your map centre) to prefer nearby results.
• Results carry kind (poi or settlement), subtitle (Breda, Noord-Brabant, or treinstation · Amsterdam) and score: enough to render a dropdown without a second lookup.

places_parse_query turns typed Dutch or English into a filter. It takes query (required), language (auto), default_radius_m (500) and near, and returns kind, filter, negated, category_group, category_label, radius_m, min_count, geo_point, place_name, confidence, unparsed, success and error.

Parsing is rule-based and deterministic: no model call, no network, the same answer every time. It never guesses silently, so anything it could not read comes back in unparsed with a lower confidence, and you can fall back to plain search rather than acting on half a filter.

places_match tests one point against a filter. It takes geo_point (required), filter (required) and max_distance, and returns matches, distance_m, count, nearest, reason, success and error. Both distance_m and count come back whether or not it matched, so a radius slider can re-answer from the result without calling again. reason is a readable Dutch line you can show the user, for example 3× basisschool binnen 500m; dichtstbij 212m.

Categories and dataset info

Map Geometry

osmworld_tile (in z, x, y, kinds) and osmworld_bbox (in bbox, or south/west/north/east, plus kinds and simplify) both return a GeoJSON FeatureCollection of roads, buildings, water and greenery for drawing a map, on a geojson out-pin alongside count.

Recipes

Store how far every object is from a school

query objects
  -> places_enrich   items=results, point_path=general.location,
                     categories=basisschool, output_path=places
  -> mutations       write items back

Afterwards an ordinary query_bool_range_field on places.primary_education.distance_m filters your inventory. No further place lookups, and any radius works, because the distance is stored rather than a flag.

A search box that understands what was typed

places_parse_query  query = <what the user typed>
  |- kind = place / area  -> geo_point   -> move the map
  |- kind = proximity     -> filter      -> places_filter over your objects

Use confidence and unparsed to decide whether to trust the filter or fall back to places_search.

How many of my objects are near a hospital?

query objects -> places_facet  categories = ziekenhuis, apotheek
                               radius_m   = 500

counts gives you the number per category, and total the number of items evaluated.

Guarding a location flow

geo_point_validate -> if not valid, stop
  -> geo_point_reverse_geocode   (address)
  -> places_nearest              (what is around it)

Reading The Results Honestly

The data is good, but it is not a register. These are properties of the source, so meet them here rather than in front of a client.

Every block on this page reports failures on its error pin rather than stopping the blueprint, so branch on success and handle the code.

The Datasets Behind All This

The datasets are shared by every entity on the node and loaded from disk at startup. They are gated by geo.require_data: with that on (the default) a node refuses to boot rather than quietly serving blocks backed by missing data.

Because the files are loaded rather than compiled in, refreshing the data needs no new binary: just the file and a restart. You do not have to remember to refresh the places data either. The node checks the published Overture releases at startup and once a day after, and warns when it has fallen three releases behind.

places dataset is STALE: running release 2026-01-01.0, latest is 2026-07-22.0
(6 releases behind). Refresh it.

Next Steps

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem