Self-Hosted Geocoding System

Nominatim 5.3 (Belgium + Tanzania) + Golang API gateway with SQLite API key authentication, rate limiting, and web testing UI.

Quick Start

# Start everything
bash scripts/start.sh

# Or manually:
cd nominatim && docker compose up -d
cd ../api-gateway && ./api-gateway

Web UI

Open http://localhost:9000 in your browser for an interactive testing interface with:

• Click-to-reverse geocode on the map
• Search with all Nominatim parameters
• Visual results display

API Endpoints

All public endpoints require an API key via ?key= parameter or X-API-Key header.

Reverse Geocode

GET /reverse?key=<key>&lat=<lat>&lon=<lon>

Nominatim parameters (all supported):

• lat (required), lon (required)
• zoom (1-18, default: 18)
• format (json, jsonv2, geojson, geocodejson, xml)
• accept-language (comma-separated, e.g. en,fr)
• addressdetails (0/1)
• namedetails (0/1)
• extratags (0/1)
• polygon_geojson (0/1)
• polygon_kml (0/1)
• polygon_svg (0/1)
• polygon_text (0/1)

Search

GET /search?key=<key>&q=<query>

Nominatim parameters (all supported):

• q (required) - search query
• limit (1-50, default: 10)
• exclude_place_ids - comma-separated OSM IDs to exclude
• featuretype - country, state, city, settlement, street, etc.
• format (json, jsonv2, geojson, geocodejson, xml)
• accept-language
• addressdetails, namedetails, extratags
• polygon_geojson, polygon_kml, polygon_svg, polygon_text
• viewbox - bounding box to restrict results
• bounded (0/1) - restrict to viewbox
• countrycodes - comma-separated country codes (e.g. be,tz)
• dedupe (0/1) - deduplicate results
• debug (0/1)

Lookup

GET /lookup?key=<key>&osm_ids=<ids>

• osm_ids - comma-separated OSM IDs (e.g. R12345,W67890)

Admin Endpoints

POST /admin/keys?admin_key=<key> - Create API key
GET  /admin/keys?admin_key=<key> - List keys
PUT  /admin/keys/toggle?id=<id>&admin_key=<key> - Enable/disable
DELETE /admin/keys?id=<id>&admin_key=<key> - Delete

Test

bash tests/test_api.sh

PHP Integration

require_once 'php-integration/nominatim.php';

// Uses $gsValues['GEOCODING_API_KEY'] from your config
// Returns same format as original gc/nominatim.php

Configuration

Edit api-gateway/.env:

NOMINATIM_URL=http://nominatim:8080    # Docker: use container name
SERVER_PORT=9000                       # Local: use localhost
SQLITE_PATH=/app/api_keys.db          # Docker path
RATE_LIMIT_RPM=1000                    # Per API key
ADMIN_API_KEY=<secret>                 # For admin endpoints

Stop Services

# API gateway
kill $(cat /tmp/geocoding-api-gateway.pid)

# Nominatim
cd nominatim && docker compose down

Nominatim Parameters Reference

Full parameter documentation:

• Reverse API
• Search API