BlogData

Why the route is called nearby

Search for nearby postal codes by keeping the starting postcode in the path and adjusting the radius with the miles query parameter.

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.