Migrating from public Nominatim
Moving from the public Nominatim server to TerraRelay takes two changes: the base URL, and an API key in a header. On /search you also add countrycodes.
- https://nominatim.openstreetmap.org/search?q=Damrak+1+Amsterdam
+ https://api.terrarelay.eu/search?q=Damrak+1+Amsterdam&countrycodes=nlAuthentication
Send your API key in the Authorization header. TerraRelay is meant for server-to-server use, so keys never belong in a URL, in browser code or in a mobile app.
Authorization: Bearer <api-key>A key in the query string is not accepted. That keeps keys out of access logs, proxies and browser history.
Required countrycodes on /search
/search requires the countrycodes parameter, for example countrycodes=nl or countrycodes=nl,be. Requests are routed to the data of the right countries based on it. Without it you get an error message that points to the documentation.
When the public server blocks you
The public Nominatim server is run by volunteers and has a strict usage policy. If you send too many requests, or do not identify your application, you may see 403 responses or a block of your IP address. The public service also offers no guarantees, and heavy or commercial use is not what it is meant for.
TerraRelay is built for that kind of use. You get your own API key, rate limits per key and the right to store results without a time limit, with the required attribution.
All deviations from public Nominatim
The endpoints, parameters and response formats are the same as those of the public Nominatim API. These are the deviations:
| Deviation | Reason |
|---|---|
| Authentication via an HTTP header | Server-to-server use; keys stay out of URLs and logs |
countrycodes is mandatory on /search |
Routes forward requests to the right shards |
Each deviation is a deliberate choice. If a request does not comply, the error message refers to the documentation.