Deploying Nominatim

Introduction

Nominatim is an open-source geocoding software that powers the search functionality on OpenStreetMap.org. It enables you to search for places by name or address (geocoding) and to find the address of a specific geographic location (reverse geocoding). Self-hosting Nominatim gives you complete control over your geocoding infrastructure without relying on third-party APIs.

Originally developed by the OpenStreetMap project, Nominatim uses OSM data to provide accurate, up-to-date geographic information. The search engine supports complex queries including street addresses, points of interest, administrative boundaries, and natural features.

Key highlights of Nominatim:

Full-Text Search: Search for places by name, address, or type
Reverse Geocoding: Convert coordinates to human-readable addresses
Address Parsing: Understand various address formats from different countries
Structured Queries: Search using structured address components
Polygon Support: Return geographic boundaries as polygons
Multilingual: Support for place names in multiple languages
Free-Form Queries: Natural language address searches
API Compatible: JSON, XML, and GeoJSON output formats
Batch Processing: Handle multiple geocoding requests efficiently
Open Data: Powered by OpenStreetMap community data

This guide walks through deploying Nominatim on Klutch.sh using Docker.

Why Deploy Nominatim on Klutch.sh

Deploying Nominatim on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the complex build process for Nominatim without manual configuration.

Persistent Storage: Attach persistent volumes for your geographic database. The preprocessed data survives container restarts.

HTTPS by Default: Automatic SSL certificates ensure secure API access.

GitHub Integration: Version-controlled deployments through your GitHub repository.

Scalable Resources: Allocate CPU and memory based on your query volume and coverage area.

Environment Variable Management: Securely configure your Nominatim instance.

Custom Domains: Use your own domain for your geocoding API.

Always-On Availability: Your geocoding service remains accessible 24/7.

Prerequisites

Before deploying Nominatim on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Understanding of geocoding concepts
Sufficient storage for your geographic region (varies by coverage)
(Optional) A custom domain for your Nominatim instance

Understanding Nominatim Architecture

Nominatim consists of several components:

PostgreSQL Database: Stores all geographic data with PostGIS extensions for spatial queries.

Nominatim API: Python-based API server handling search and reverse geocoding requests.

OSM Data Importer: Tools for importing and updating OpenStreetMap data.

Address Parser: Analyzes and normalizes address queries for accurate matching.

Indexer: Maintains search indexes for fast query performance.

Deploying Nominatim on Klutch.sh

Create Your GitHub Repository

Create a new GitHub repository for your Nominatim deployment configuration.

Create the Dockerfile

Create a Dockerfile in your repository root. This example uses Monaco as a small region for initial setup:

FROM mediagis/nominatim:4.4

# Set the geographic region to import
# For testing, use a small region like Monaco
# For production, use your desired region
ENV PBF_URL=https://download.geofabrik.de/europe/monaco-latest.osm.pbf
ENV REPLICATION_URL=https://download.geofabrik.de/europe/monaco-updates

# Import settings
ENV IMPORT_WIKIPEDIA=false
ENV IMPORT_TIGER_ADDRESSES=false

# Runtime settings
ENV NOMINATIM_PASSWORD=nominatim_password

EXPOSE 8080

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

Configure the following environment variables:

Variable	Value
`PBF_URL`	URL to your region’s OSM data file
`REPLICATION_URL`	URL for data updates
`NOMINATIM_PASSWORD`	Database password
`THREADS`	Number of import threads

Attach Persistent Volumes

Add persistent storage (sizes vary by region):

Mount Path	Recommended Size	Purpose
`/var/lib/postgresql/14/main`	50-500 GB	PostgreSQL database
`/nominatim/data`	10 GB	Nominatim data files

Deploy Your Application

Click Deploy to start the build process. Initial import can take significant time depending on region size.

Verify the API

Once deployed, test the API:

Search: https://your-app.klutch.sh/search?q=Monaco
Reverse: https://your-app.klutch.sh/reverse?lat=43.73&lon=7.42

API Usage

Search (Geocoding)

Convert addresses to coordinates:

GET /search?q=10+Downing+Street,+London

Parameters:

q: Free-form query string
format: Output format (json, xml, geojson)
limit: Maximum number of results
addressdetails: Include address breakdown

Reverse Geocoding

Convert coordinates to addresses:

GET /reverse?lat=51.501&lon=-0.142&format=json

Parameters:

lat: Latitude
lon: Longitude
zoom: Level of detail (0-18)

Structured Search

Search with structured address components:

GET /search?street=10+Downing+Street&city=London&country=UK

Region Selection

Choose your data region based on your needs:

Region	Size	Import Time	Use Case
Monaco	~10 MB	Minutes	Testing
Single Country	1-50 GB	Hours	Country-specific
Continent	50-100 GB	Days	Regional coverage
Planet	500+ GB	Weeks	Global coverage

Download regions from Geofabrik.

Production Best Practices

Performance Optimization

Import only the regions you need
Allocate sufficient memory for PostgreSQL
Use SSD storage for the database
Enable connection pooling for high traffic

Data Updates

Keep your data current:

Configure replication URL in environment variables
Set up scheduled update jobs
Monitor update logs for errors

Security Recommendations

Use strong database passwords
Implement rate limiting for public APIs
Monitor for abuse patterns
Keep the system updated

Troubleshooting Common Issues

Import Fails

Verify PBF URL is accessible
Check available disk space
Ensure sufficient memory allocation
Review import logs for specific errors

Slow Queries

Check if indexing completed successfully
Verify PostgreSQL has adequate resources
Analyze query patterns for optimization

No Results

Verify data import completed
Check that the query location is within imported region
Try simpler search terms

Additional Resources

Conclusion

Deploying Nominatim on Klutch.sh gives you a powerful, self-hosted geocoding solution with full control over your geographic data. Whether building location-based applications or providing address search functionality, Nominatim offers accurate, privacy-respecting geocoding powered by OpenStreetMap data.