Suggest areas
suggest_areasRead-onlyIdempotent
Find neighborhoods reachable within travel-time budgets from up to three anchors, scored against your amenity and character requirements, and ranked by overall fit.
Instructions
Where within reach: neighborhoods ranked by travel budget + amenities.
The inverse of every other area tool — instead of "describe this place",
"find me a place". anchors is 1-3 {"lat", "lon", "mode"?, "minutes"?}
points (mode: walk/cycle/drive, default from stored preferences;
minutes: default 15). requirements is 1-8 free-text amenity/character
strings, scored the same way as area_score.score_locality — "parks",
"groceries", "coffee shop" resolve against the Overture taxonomy;
a subjective phrase ("quiet streets", "safe neighborhood", "good
schools") comes back {"measurable": false} rather than a guessed score
(see "honesty" in the response).
Method: the same street-graph reach analysis behind PlaceRoot's other
travel-time tools computes each anchor's reachable shed; with more than
one anchor, the sheds are intersected (a candidate must be reachable
within EVERY anchor's own time budget, not just one — "office" and
"gym" both mean both). divisions.divisions_in_polygon (#348) partitions
the (intersected) shed into candidate neighborhoods/localities; each
candidate is scored against requirements the same way
area_score.score_locality (#349) does. Returns {"anchors": [...],
"results": [{"division_id", "name", "subtype", "overlap_fraction",
"lat", "lon", "travel": [{"anchor_idx", "mode", "minutes_budget",
"travel_time_min", "distance_m"} or {..., "note": "unroutable"/
"no_graph_nearby"/...}, ...], "requirements": [...], "overall_score",
"reason"}, ...], "honesty"}, ranked by overall_score (unmeasurable-only
candidates sort last, never dropped) then overlap_fraction, capped at
`limit` (1-10, default 5). division_id is a stable GERS id — chain a
result into admin_lookup or summarize_area for more detail without
re-running the search. No polygons in the response by default.
An empty "results" list is a valid answer (e.g. two anchors' sheds don't
overlap at all, or nothing in the reachable area is a neighborhood/
locality) with a "note" saying which. A per-anchor travel leg that can't
be routed (the polygon-approximated shed boundary occasionally includes
a point routing itself can't reach) gets "note" instead of a time,
without dropping the whole candidate.
confirm=true after the user agreed to wait for a first-time street-graph
build (about 5-25 seconds per anchor that needs one). Every anchor is
checked before any graph is built, so a fan-out never starts some
anchors and then stalls needing confirm on the next. Omit confirm
unless you just asked and they said yes.
Returns a structured {"error": "bad_request", ...} if anchors isn't 1-3
points, a point is missing/non-numeric lat, lon, or minutes, minutes is
not > 0, or a mode isn't walk/cycle/drive; likewise if requirements
isn't 1-8 non-empty strings. Propagates the same structured errors as
the underlying reach analysis (unsupported_mode, no_graph_nearby,
radius_too_large) and divisions_in_polygon/score_locality (upstream_unavailable,
schema_degraded) — a partial shortlist from a failed anchor or scan is
never returned.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| anchors | Yes | ||
| confirm | No | ||
| requirements | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||