Performance Analysis of /search and /reverse on macOS

[div-dev123]

1. Setup Issues on macOS (Apple Silicon)

The README covers installation steps well, but macOS (especially Apple Silicon / ARM64) has a few pitfalls that will affect mac users

1.1 ICU4C is keg-only on Homebrew

Nominatim depends on pyicu, which requires the ICU library headers. On macOS with Homebrew, ICU (icu4c) is installed as keg-only (not symlinked into /opt/homebrew/), so pip install of the Nominatim packages fails with:

Package icu-uc was not found in the pkg-config search path.

Fix — Export the pkg-config path before installing:

export PKG_CONFIG_PATH="/opt/homebrew/opt/icu4c/lib/pkgconfig"
pip install packaging/nominatim-{api,db}

The exact suffix (e.g. icu4c@78) may vary with Homebrew versions. Run brew info icu4c to find your path.

1.2 PostGIS availability is tied to a specific PostgreSQL major version

Homebrew's PostGIS formula only builds against one or two PostgreSQL major versions at a time. At the time of writing, postgis is built for PostgreSQL 17 and 18. If you have PostgreSQL 15 or 16 from an older install, CREATE EXTENSION postgis will fail with:

ERROR: could not open extension control file ...postgis.control: No such file or directory

Fix — Install the matching PostgreSQL version:

brew install postgresql@17 postgis
brew services start postgresql@17
export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"

1.3 The www-data PostgreSQL role doesn't exist on macOS

The Nominatim import expects a www-data PostgreSQL user (common on Linux where the web server runs as www-data). On macOS this user doesn't exist, causing:

ERROR: role "www-data" does not exist

Fix:

createuser www-data

1.4 wget is not available by default

The README examples use wget to download OSM data extracts. macOS does not ship with wget.

Fix — Use curl instead:

curl -L -o monaco.osm.pbf https://download.geofabrik.de/europe/monaco-latest.osm.pbf

or use Brew install wget

---

2. Profiling Approach

Instead of just timing HTTP responses manually, I built a small profiling setup with two layers.

A. Internal Profiling (cProfile)

• Directly call the Nominatim API from Python
• Wrap calls with cProfile
• Measure:
  • Function-level time
  • DB vs Python runtime split
  • Call counts

This helps identify whether time is spent in:

• PostgreSQL
• Tokenization
• Python application logic

---

B. HTTP-Level Benchmarking

• Send actual /search and /reverse requests
• Measure end-to-end latency
• Repeat queries multiple times
• Calculate:
  • Mean
  • Median
  • P95
  • P99

This reflects real-world API performance.

---

3. Query Generation

To avoid hardcoded test queries, I added a small script that:

• Connects to PostgreSQL
• Extracts real place names from placex
• Generates:
  • Search queries
  • Reverse coordinates
  • Some fuzzy/variant inputs

This makes testing:

• Reproducible
• Dataset-independent
• More realistic

4. Profiling Results

4.1 Monaco (Small Dataset — 2.3MB PBF)

Import time: ~16 seconds
Database size: ~5,700 indexed places
Queries: 30 search + 20 reverse, 1 repetition (library), 1 repetition (HTTP)

Library Profiling

Metric	/search	/reverse
Mean	40.51ms	16.35ms
Median	7.14ms	14.49ms
P95	25.31ms	31.35ms
P99	686.45ms	40.00ms
DB time %	99.7%	99.4%
Python time %	0.3%	0.6%

HTTP Profiling (first run — cold caches)

Metric	/search	/reverse
Mean	31.55ms	27.65ms
Median	16.65ms	19.15ms
P95	133.28ms	42.85ms

Key Observations — Monaco

• First query dominance: "Monte Carlo" took 954ms on the first call due to cold-start overhead (tokenizer config loading, YAML parsing, DB connection setup). After warm-up, the same type of query takes ~5–15ms.
• YAML config loading is expensive: The ICU tokenizer calls yaml.safe_load to parse icu_tokenizer.yaml which includes 31+ sub-files. This single operation accounts for ~510ms of cumulative time — it happens once but dominates the first-query latency.
• Database queries are 99.7% of runtime: After warm-up, Python processing adds only ~100–120µs per call. The bottleneck is entirely in PostgreSQL.

---

4.2 North-Eastern India (Medium Dataset — 96MB PBF)

Import time: ~4.3 minutes (259 seconds)
Database size: ~270,000 indexed places (18M nodes, 2M ways, 3.9K relations)
Queries: 50 search + 30 reverse, 3 repetitions each
Coverage: 8 states — Assam, Arunachal Pradesh, Manipur, Meghalaya, Mizoram, Nagaland, Sikkim, Tripura

Library Profiling

Metric	/search	/reverse
Mean	11.87ms	12.26ms
Median	5.17ms	11.74ms
P95	18.71ms	21.99ms
P99	53.30ms	37.47ms
DB time %	99.1%	99.1%
Python time %	0.9%	0.9%

HTTP Profiling (warm server)

Metric	/search	/reverse
Mean	7.08ms	10.20ms
Median	5.85ms	8.80ms
P95	12.82ms	18.72ms

Key Observations — North-Eastern India

• Cold-start cost persists: "Madan Kamdev" (first query, rep 1) took 652ms, dropping to 4.6ms on rep 2 — a 140× improvement after warm-up.
• Non-Latin scripts are slower: The Chinese-script query ("扎日至形穷普张边防公路") averaged 22.8ms vs ~5ms for typical English queries — the ICU tokenizer does more work for CJK text.
• Multi-word/comma queries are slower: "Council Veng, Road-2" and "State Dispensary, Dampur" averaged 14–23ms, likely due to multiple search strategies being tried.
• Out-of-region reverse lookups are expensive: Coordinates far from the dataset (lat 32–34°, outside NE India) took 20–41ms vs 5–7ms for in-region points — the DB has to scan more before concluding no nearby street exists.

---

4.3 Comparison: Monaco vs North-Eastern India (warm, steady-state)

Metric	Monaco (warm)	NE India (warm, reps 2–3)
Search median	7.14ms	~5ms
Search P95	25.31ms	~13ms
Reverse median	14.49ms	~6ms
Reverse P95	31.35ms	~15ms
Dataset size	~5,700 places	~270,000 places

The larger dataset appears faster in steady-state because:

1. Monaco's single-repetition data is skewed by cold-start
2. NE India's 3-repetition averaging dilutes the cold-start penalty
3. Both datasets fit comfortably in PostgreSQL's shared buffers on this machine

---

5. Top Performance Bottlenecks Identified (cProfile)

Looking at the cProfile output for both datasets, the same functions show up at the top each time:

Rank	Function	What it does	Impact
1	kqueue.control / selectors.select	Async I/O waiting for PostgreSQL responses	~1.1s cumulative — this IS the DB wait
2	yaml.safe_load → compose_node	Parsing ICU tokenizer YAML config (31+ files)	~510ms — one-time cold start
3	place_search.lookup	The actual SQL search execution	~900ms — the core search work
4	reverse.lookup_country	Country-level fallback for reverse queries	~617ms — expensive for out-of-region points
5	reverse._find_closest_street_or_pois	Spatial lookup for nearby streets/POIs	~340ms — the core reverse work
6	icu_tokenizer.analyze_query	Tokenizing and normalizing the search input	~274ms — per-query tokenizer work
7	geocoder.build_searches	Building search strategy tree from tokens	~896ms — multiple strategies tried
8	greenlet.switch	SQLAlchemy async context switching overhead	~272ms — framework overhead

---

6. Screenshots from Implementation

---

AI Usage: Used for generating a structured .md report and to understand the requirements and some errors that popped along the way