Places and Geo Search
The places_* and geo_point_* blocks answer location questions from datasets on the node itself: no API keys, no per-call cost, no request leaving the building. They search places, filter your documents by what is nearby, and enrich them.
This guide covers the search and filtering flow. Location Blocks lists every block with its pins.
1. Text search handles accents, typos and partial words
places_search (search places) handles accents (Bréda finds Breda), typos (amsterdm centraal) and partial words as the user types, and collapses duplicate records from the source data. The outputs are a ranked results array, the best match and a count.
nearplusbias_radius_mbiases ranking toward a point without excluding anything farther away.limit,typo_toleranceandmin_confidencetune how much comes back and how forgiving the matching is.kindsandcategoriesrestrict the search to points of interest, settlements, or specific category groups.
A typed query, typos and all, goes into search places. A from city point biases the ranking toward Breda, a number caps the result count, and get fields reads the name off the best match for the reply.
2. Three blocks answer "what is here"
| Block | Answers | Notes |
|---|---|---|
places_nearest (nearest places) |
The closest points of interest to a geo point, ordered by distance, each with its distance in metres. | Leave max_distance empty for an unbounded search and apply your own cutoff later. |
places_within (places within radius) |
Every point of interest inside a radius, nearest first. | Compare count with raw_count to see how much duplication the source data carries at that spot; truncated flags a capped result. |
places_in_bbox (places in bounding box) |
Every point of interest inside a bounding box: the block for rendering what is currently on a map screen. | Results carry no distance (a box has no query point); use the nearest block when you need distances. |
3. Categories are folded into curated groups
The source dataset ships roughly 1700 raw categories, far too many to show a user, so they are folded into curated groups with Dutch and English labels.
places_categories(list place categories) lists those groups. Build a category dropdown from it.places_resolve_category(resolve place category) goes the other way: free text such askroegorsupermarktbecomes a category group id, with aconfidencescore andalternativeswhen a word spans several groups. Plurals are handled, sokroegenandbarsjust work.
4. Typed filters turn a sentence into a result
places_parse_query (parse places query) turns typed Dutch or English into a structured filter: binnen 300m van een basisschool becomes a proximity filter, niet bij scholen a negated one, minimaal 3 kroegen binnen 500m carries a minimum count. Two blocks consume that filter:
places_match(match places filter) tests one geo point against the filter. Itsdistance_mandcountcome back even when nothing matched, so you can re-answer a different radius without another call.places_filter(filter by places) keeps or removes items of a whole list by the filter, reading each item's point frompoint_path. Withannotateit writes the distance onto each item instead of removing anything.
5. Enrich and facet your own documents
places_enrich (enrich with nearby places) adds the nearest place per category to every item in a list in one call, no iterator needed. The usual pipeline:
Query your documents
Use
function_search.Run the enrich block
Pass the results to
places_enrich.Write the result back
Use
mutations_set_bp_field_multipleandfunction_update_document_mutations.
After that an ordinary range query filters on the stored distances, and the expensive proximity work happens once per document instead of once per page view.
places_facet(facet counts by places) answers "412 properties near a hospital" in one block: it counts how many items of a list are near each category. An item with three hospitals nearby still counts once, which is what a facet over your own inventory means.places_density(place density) profiles a single spot instead: totals, per km², and a classification.
6. Helpers create, check and resolve geo points
Every places block takes or returns a geo_point.
geo_point_lat_lng_to_pointbuilds a point from two numbers;geo_point_to_lat_lngsplits one back out.geo_point_from_cityresolves a city name to its centre point plus radius, optionally constrained by country code and province.geo_point_reverse_geocoderesolves a point to the nearest street, city, province and country.geo_point_snappins a point onto the nearest road or railway and reports how far it moved;geo_point_nearbychecks whether such a network is within a given distance.geo_point_validatechecks a point holds a valid latitude and longitude before you trust it.
Notes from practice
- Store a place id when you want to refer to it later, and re-resolve it with
places_get(get place by id). Branch on itsfoundpin: an id can disappear between dataset releases, and not finding it is a successful lookup, not an error. - Results carry a confidence; raising
min_confidencetrades recall for precision on messy source data. - All of this runs offline, so there is no rate limit to design around. The cost is dataset freshness: check the release with the dataset info block when results look stale.
Next steps
Location Blocks Every geo point, places and map block with its pins, in one lookup page. Storages The queries and mutations behind the enrich-and-write-back pipeline. Common Blueprint Patterns The endpoint and error-handling shapes to wrap around a places search.Frequently asked
Does the RUAL places search need an API key?
No. The places blocks run offline against an Overture dataset shipped with the node, so there is no API key, no rate limit and no per-call cost, and lookups are fast enough to run inside loops.
How do I search places by typed text in RUAL?
Use places_search. One search box covers points of interest and settlements, tolerates typos and accents, and can bias results toward a geo point without excluding farther matches. The results array, the best match and a count come back ranked.
How do I filter my own documents by nearby places in RUAL?
Turn a typed sentence into a filter with places_parse_query, then apply it with places_filter to keep or remove items of a list, or places_match to test a single point. To make the result queryable later, run places_enrich once and write the nearest-place distances back onto the documents.
