Nominatim Authentication: Methods, Credentials & Security (2026)

Authentication overview

Nominatim, an open-source geocoding engine built on OpenStreetMap data, approaches authentication differently than most commercial APIs. Because Nominatim is primarily software that users can self-host and configure, its authentication mechanisms are largely dependent on the specific deployment context.

For independent developers or organizations running their own Nominatim instance, authentication is often handled at the infrastructure level. This means that access control is managed through web server configurations (e.g., Nginx, Apache), network firewalls, or application-level logic built around the Nominatim service. Instead of a centralized API key system inherent to the software, the administrator of a self-hosted instance defines how users can access it.

Conversely, when interacting with public Nominatim instances (such as the one provided by OpenStreetMap Foundation or various third-party providers), authentication typically involves an API key or adherence to specific usage policies. These public instances implement their own authentication and rate-limiting mechanisms to manage server load and prevent abuse. Users are expected to respect these policies and often include an API key or an identifying user-agent string with their requests.

The core Nominatim software does not include an intrinsic authentication layer like OAuth 2.0 or bearer tokens. Instead, it relies on external systems or custom implementations for securing access. This design choice gives deployers flexibility but shifts the responsibility for security and access management to the operator.

Supported authentication methods

The authentication methods for Nominatim vary significantly based on whether you are using a public instance or a self-hosted deployment.

Public Instances

• API Keys: Many public Nominatim services require an API key to identify users and enforce rate limits. This key is typically passed as a query parameter (e.g., ?key=YOUR_API_KEY) or sometimes as a custom HTTP header. The specific parameter name and key format are determined by the provider of the public instance.
• User-Agent String: Some public instances, particularly the OpenStreetMap Foundation's free service, request that users provide a descriptive User-Agent HTTP header. While not a direct authentication method, it helps operators understand usage patterns and contact users if issues arise, acting as a form of identification.
• IP-Based Rate Limiting: Public instances frequently employ IP-based rate limiting, even with API keys. Repeated requests from a single IP address beyond a certain threshold may result in temporary blocks or errors without requiring an explicit authentication credential.

Self-Hosted Deployments

• IP Whitelisting/Firewall Rules: This is a common and effective method for self-hosted instances. By configuring network firewalls or web server rules (e.g., Nginx's allow directive), access to the Nominatim service can be restricted to a predefined list of IP addresses or networks, ensuring only authorized servers or clients can connect.
• HTTP Basic Authentication: While not part of Nominatim itself, HTTP Basic Auth can be implemented at the web server level (e.g., Nginx, Apache) in front of the Nominatim application. This requires clients to send a username:password pair encoded in Base64 in the Authorization header. This method provides a basic layer of access control but should always be used over HTTPS.
• Client Certificates (Mutual TLS): For higher security environments, mutual TLS (mTLS) can be configured at the web server or load balancer level. This requires both the client and server to present and validate cryptographic certificates, establishing a strong, authenticated and encrypted connection. This is typically used in enterprise settings.
• Custom Application-Level Authentication: Developers running self-hosted instances can build their own authentication layers on top of Nominatim using frameworks or custom code. This might involve implementing token-based authentication (like JWTs) or integrating with existing identity providers.

Here's a summary of common authentication approaches for Nominatim:

Getting your credentials

The process for obtaining credentials for Nominatim depends entirely on the specific deployment you are using:

For Public Nominatim Instances

• OpenStreetMap Foundation (OSMF) Instance: The OSMF provides a public Nominatim service, but its usage policy explicitly states it is not for heavy commercial use. While it doesn't typically require an API key for basic use, a descriptive User-Agent header is requested, and significant rate limits apply. For higher volumes, users are encouraged to run their own instance or use a third-party provider.
• Third-Party Providers: Numerous companies offer Nominatim as a service, often with dedicated APIs and rate limits. For these services (e.g., OpenCage Geocoding API, Mapbox Geocoding API), you would typically sign up on their respective websites, which would then provide you with an API key. This key is usually available in a developer dashboard after registration. For example, Mapbox Geocoding API provides access tokens through their account settings.

For Self-Hosted Nominatim Instances

• No Intrinsic Credentials: If you are installing and managing your own Nominatim server, the software itself does not generate API keys or require specific user credentials. Your 'credentials' are the access controls you implement at the infrastructure level.
• IP Whitelist Setup: To implement IP whitelisting, you would configure your web server (e.g., Nginx or Apache) or firewall rules to only permit connections from specific IP addresses. You define these allowed IPs directly in your server's configuration files.
• HTTP Basic Auth Setup: For HTTP Basic Authentication, you would create a .htpasswd file (or similar, depending on your web server) containing hashed usernames and passwords. Your web server configuration would then be updated to reference this file for authentication. Tools like htpasswd are commonly used to generate these files.
• Client Certificate Generation: Implementing mTLS requires generating and managing client certificates, often through a Public Key Infrastructure (PKI) or self-signed certificates for internal use. This is an advanced setup requiring cryptographic expertise.

Authenticated request example

Since Nominatim's authentication varies by deployment, examples will differ. Here are common scenarios:

Example 1: Public Instance with API Key (Hypothetical)

Assuming a public Nominatim-as-a-service provider requires an API key passed as a query parameter called api_key:

curl "https://api.example.com/nominatim/search?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&format=json&api_key=YOUR_API_KEY"

Replace https://api.example.com/nominatim/search with the actual endpoint and YOUR_API_KEY with your assigned key.

Example 2: Public Instance Requesting User-Agent

When accessing the OpenStreetMap Foundation's public Nominatim instance, a descriptive User-Agent header is recommended:

curl -H "User-Agent: MyApplication/1.0 ([email protected])" \
     "https://nominatim.openstreetmap.org/search?q=Eiffel+Tower&format=json"

Ensure your User-Agent provides contact information, as recommended in the OSMF Nominatim Usage Policy.

Example 3: Self-Hosted Instance with HTTP Basic Authentication

If your self-hosted Nominatim is protected by HTTP Basic Auth via your web server (e.g., Nginx), you would include the -u flag with curl:

curl -u "username:password" \
     "https://your-nominatim.example.com/search?q=Berlin&format=json"

The username:password string will be Base64 encoded by curl and sent in the Authorization header.

Security best practices

Regardless of whether you use a public instance or self-host Nominatim, adhering to general API security principles is crucial:

Always Use HTTPS

All Nominatim requests, especially those involving any form of identification or authentication (like API keys or Basic Auth), should always be made over HTTPS. This encrypts the communication channel, protecting sensitive data from eavesdropping and man-in-the-middle attacks. For self-hosted instances, configure your web server (Nginx, Apache) with SSL/TLS certificates.

Protect API Keys and Credentials

• Environment Variables: Store API keys and other sensitive credentials in environment variables rather than hardcoding them directly into your application code. This prevents accidental exposure in source control.
• Configuration Management: Use secure configuration management tools (e.g., HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) for managing secrets in production environments.
• Restrict Access: Ensure that only authorized personnel and systems have access to API keys and server configuration files containing authentication details.
• Never Expose Client-Side: Do not embed API keys for rate-limited public instances directly into client-side code (e.g., JavaScript in a web browser) where they can be easily extracted by end-users. Route requests through a secure backend server that adds the API key.

Implement Strict Access Control for Self-Hosted Instances

• IP Whitelisting: If your self-hosted Nominatim is for internal use, restrict access to a predefined list of trusted IP addresses or networks using firewall rules or web server configurations.
• Strong Passwords: If using HTTP Basic Authentication, enforce strong, unique passwords and consider password rotation policies.
• Least Privilege: Only grant the necessary permissions to users or services accessing Nominatim.

Monitor and Log Access

Regularly monitor access logs for your Nominatim instance (or review usage reports from public providers). Look for unusual request patterns, high volumes from unexpected IPs, or repeated authentication failures, which could indicate malicious activity or abuse. Implement logging for all requests and responses, especially for self-hosted deployments, to aid in auditing and debugging.

Rate Limiting

Whether using a public service or self-hosting, be aware of and respect rate limits. Public services impose them to maintain availability. For self-hosted instances, configure rate limiting on your web server to protect against denial-of-service attacks and manage resource consumption.

Regular Updates and Maintenance

For self-hosted Nominatim, keep the software, its dependencies, and the underlying operating system updated to patch security vulnerabilities. Regularly review and update your web server configurations and access control policies.

By following these best practices, you can help ensure the security and reliability of your Nominatim integration.