Blog·Note·

Why the route is called nearby

A nearby search keeps the place in the path and the search radius in the query string.

When you look for postal codes near a place, the place stays the same while you try different distances. You might start at 10 miles, then widen the search to 25.

That's how I wanted the URL to read. The postal code goes in the path, followed by nearby. The distance is a setting on that search:

GET /postal/90210/nearby?country=US&miles=25

The naming discussion started with /radius/25. I went with nearby because it describes the results you're asking for. A radius describes how far to search. Keeping that in the query string makes the distinction easier to see.

This is a convention for making the API understandable, not a technical restriction on what can go in a URL. You can change the distance and still be making the same kind of nearby lookup.