Address search¶

Typing a place name into a location and getting coordinates back is address search, and it works out of the box: CARAVEL_GEOCODER_URL defaults to OpenStreetMap's Nominatim, the same project the map tiles come from.

The value stub is a third option: an in-process fixture geocoder that answers a handful of Reykjavík places from a table and nothing else. It exists so the browser test suite does not ask a volunteer-run service for the same coordinates on every run, and it is never a real answer.

It is called from the server, not the browser¶

Caravel proxies address search through /api/geocode rather than letting the browser call Nominatim directly, for two reasons. OSM's usage policy wants an identifying User-Agent and no more than one request a second, neither of which a browser can promise. And a self-hosted app should not hand a user's typing to a third party without a single place to turn that off.

That proxy is rate limited to 20 requests a minute per client address — deliberately stricter than it needs to be for Caravel's own protection, because what it is protecting is somebody else's service.

Turning it off¶

Set it empty:

CARAVEL_GEOCODER_URL=

The API then reports address search as unavailable and the UI hides the control rather than offering one that cannot work. Coordinates can still be entered by hand, and locations without coordinates simply do not appear on the map.

Running your own¶

Any endpoint with Nominatim's response shape works, so a self-hosted Nominatim — or anything that imitates it — can be pointed at instead:

CARAVEL_GEOCODER_URL=https://nominatim.example.org/search

Worth doing if you use address search heavily. The public instance is a volunteer-funded service with a usage policy that asks bulk users to host their own, and it is entitled to refuse an instance that leans on it.