Blog·Note·

Nearby is a list, radius is a knob

/postal/{code}/nearby takes a miles query param instead of a /radius/25 path segment, because 25 is a setting, not an id.

A number in the URL path makes a promise: this is an id, bookmark it, cache it forever. 25 miles was never that.

The path holds nouns and ids. /postal/{code} is an id. /postal/{a}/distance/{b} is two ids. The radius on a nearby search is neither, it is a dial someone turns per request, 10 miles for one call and 50 for the next, so it lives in the query string, ?miles=25, right where settings belong.

The route name needed its own decision on top of that. radius was the first instinct and got demoted to the query param name for exactly the reason it could not also be the route: radius reads as the knob, not the list of results coming back. nearby is the noun for what the list actually contains, places found near a point, and it does that job whether the caller asks for 5 miles or 50.

Try it

Call /postal/{code}/nearby?miles=25 and picture the alternative, /postal/{code}/radius/25, decide which one survives someone changing the number.