Design Yelp: Location-Based Business Discovery Platform

A Yelp-shaped proximity service is three loosely-coupled systems pretending to be one product: a geospatial index that answers “what’s nearby?”, a ranking layer that orders the candidates, and a content platform that ingests reviews, photos, and business edits. The interview question — and the production reality — is how to make those three move together at a 100:1 read/write ratio with a sub-100 ms p99 search budget. This article walks through the indexing trade-offs, an Elasticsearch-shaped reference design, the multi-signal ranking math, the review write path, and the operational footguns that show up at scale.

Mental model

Proximity search is unlike text search in one important way: the answer depends on where you are, not just what you typed. The query center moves with every request, so you cannot pre-compute rankings for it; instead you pre-compute spatial buckets and rank candidates inside the buckets you touch.

The four moving parts a senior engineer should hold in their head:

1. Spatial index — converts a (lat, lon, radius) tuple into a small candidate set. Geohash, quadtree/S2, H3, and BKD-tree-backed engines (Lucene/Elasticsearch) all do this, with different write-vs-read trade-offs.
2. Filter and rank — narrow the candidates by category/price/hours, then score them with distance + rating + recency + personalisation.
3. Source of truth + derived index — businesses and reviews live in an ACID store; the search index is a derived projection that is allowed to be a few seconds behind.
4. Write path — review and business updates use a transactional outbox so the search index, cache, and analytics warehouse stay consistent without distributed transactions.

Radius search vs k-NN. Two different question shapes show up in proximity products:

• Radius search — “everything within R metres of P”. The candidate count is unbounded; the engine returns a possibly empty set. This is what Yelp / Google Maps “nearby” surfaces, what ST_DWithin / Elasticsearch geo_distance answer natively, and what most caches assume.
• k-NN search — “the k closest things to P, regardless of distance”. The candidate count is bounded; the engine returns exactly k points (or fewer if the index is small). This matches ride-share dispatch (“nearest 5 drivers”), in-vehicle POI (“nearest gas station”), and Elasticsearch’s knn query with a geo_point vector.

In a discovery product, radius search is primary because the user’s mental model is “what’s nearby”. k-NN is the fallback for sparse areas — when fewer than k results land inside R, expand R until you have k or hit a hard cap. Mixing the two paradigms in the same query path is a common source of subtle bugs (k-NN sorted by distance ignores rating; radius search expanded for sparsity needs to be advertised to the UI so “showing nearby” copy can render).

Real-world frame of reference. Yelp publishes 330 million cumulative reviews and ~28 million monthly unique mobile devices as of 31 December 2025¹, with 308 million cumulative reviews at the end of 2024². Google Maps is widely cited as indexing more than 200 million businesses and places, although Google does not publish a single canonical figure³. Foursquare’s Movement (formerly Pilgrim) SDK ships a global database of ~100M+ POIs and was launched on top of more than 11 billion historical check-ins⁴. These services demonstrate that sub-100 ms p99 latency is achievable, but only with aggressive caching, denormalisation, and tightly bounded search spaces.

Requirements

Functional Requirements

Scope for this article. We design the core proximity search, the business data model, and the review pipeline. Check-ins and advanced personalisation are touched on briefly; advertising auctions and business analytics are out of scope.

Non-Functional Requirements

Scale Estimation

These are the planning assumptions for a single, plausible Yelp-shaped tenant — not Yelp’s actual numbers. They exist to drive sizing, not to claim accuracy.

Users.

• Monthly Active Users (MAU): 100 M
• Daily Active Users (DAU): 30 M
• Peak concurrent users: 3 M (10% of DAU)

Businesses.

• Total businesses: 10 M globally
• Active businesses (updated in last year): 5 M
• New businesses per day: 10 K

Traffic.

• Search queries: 30 M DAU × 5 searches/day = 150 M searches/day ≈ 1,700 QPS
• Peak search: 3× average ≈ 5,100 QPS
• Business profile views: 30 M × 10 views/day ≈ 3,500 QPS
• Review writes: 30 M × 0.01 reviews/day ≈ 300 K reviews/day ≈ 3.5 writes/sec
• Photo uploads: ~100 K/day

Storage.

• Business data: 10 M × 10 KB ≈ 100 GB
• Reviews: 200 M reviews × 2 KB ≈ 400 GB
• Photos: 500 M photos × 500 KB average ≈ 250 TB (object storage)
• Search index: ~50 GB (denormalised business + location data)
• 5-year projection: ~2 PB total (dominated by photos)

Design Paths

Path A: Geohash-based indexing

Best when: uniform business density, fixed search radius, and operational simplicity matter more than peak performance.

Architecture:

Key characteristics.

• Geohash interleaves latitude and longitude bits into a base-32 string; cells with a longer common prefix are spatially close (Wikipedia, Geohash).
• A 5-character cell is roughly 4.9 km × 4.9 km at the equator, and a 6-character cell is roughly 1.22 km × 0.61 km — width shrinks as you move toward the poles (OpenSearch geohash-grid table, movable-type.co.uk geohash precision).
• A query touches the target cell plus the 8 surrounding cells to cover points that fall just across a boundary; the final pass re-filters by exact great-circle distance.
• The on-disk index is a flat key-value map: geohash → [business_id...].

Trade-offs.

• Simple to implement and debug; nearby queries hit overlapping cache keys.
• Easy to shard by geohash prefix.
• Fixed precision creates density mismatches: a level-6 cell over Manhattan can hold thousands of businesses while the same cell over rural Wyoming holds zero.
• Variable-radius search needs queries at multiple precisions, which inflates work and complicates caching.
• Cell-boundary expansion (the “+8 neighbours” trick) is mandatory and easy to forget.

Real-world echo. Uber’s H3 hexagonal hierarchical spatial index was developed in part to escape the rectangular distortion and density problems of geohash, but kept the prefix-lookup ergonomics that make geohash so easy to operate. H3 has 16 resolutions and uses an aperture-7 subdivision: each finer resolution has cells with roughly one-seventh the area of the coarser one (edge length scales by ), per the official H3 cell-statistics table. Uniform hexagons make distance and neighbour math much cleaner than geohash rectangles — which is also why H3 is the default choice for heat-map aggregation of demand, supply, or visit data.

Path B: Quadtree / S2 geometry

Best when: density varies wildly across regions, the radius is variable, or queries include polygons (delivery zones, contraction-hierarchy tiles).

Architecture:

Key characteristics.

• Recursively subdivides 2-D space until each leaf cell contains at most N points; dense city blocks descend many levels, sparse rural cells stay shallow.
• Google’s S2 library projects the sphere onto a cube and indexes cells with a Hilbert space-filling curve, so spatially close cells stay numerically close. Cell sizes drop by ~4× per level: level-10 cells average ~81 km² (~9 km on a side) and level-16 cells average ~19,800 m² (~140 m on a side) per the official S2 cell statistics.
• Cell IDs encode the path from root, so a range scan on cell IDs yields all descendants of an ancestor — useful for region-wide queries.

Trade-offs.

• Adapts to density automatically and handles polygon/route queries natively.
• Cache locality is harder because cell sizes vary.
• Tree maintenance under heavy writes is more expensive than a flat geohash bucket.

Real-world echo. S2 and H3 are both production-grade choices: S2 is the foundation of Google Maps’ geometry layer, while H3 underpins Uber’s geofencing and supply/demand heatmaps.

Path C: BKD-tree / Elasticsearch (Lucene)

Best when: queries combine geo with full-text search, attribute filtering, and aggregations — the typical Yelp-shaped workload.

Architecture:

Key characteristics.

• Since Lucene 6.0, geo_point and (since 7.0) geo_shape are indexed using BKD trees — block-balanced k-d trees, a variant of k-d trees, not R-trees — that are highly efficient for multi-dimensional point and bounding-box lookups (Elastic blog: multi-dimensional points, Elastic blog: BKD-backed geo_shapes).
• The geo_distance query returns documents within a radius and defaults to the arc distance type (Haversine on WGS84), so boundary handling is correct out of the box.
• Geo, full-text, and structured attribute predicates compose naturally inside a single bool query, which lets one engine answer “espresso bars under $$ within 2 km that are open now”.

Trade-offs.

• Operational maturity: well-known sharding, snapshotting, and monitoring patterns.
• Combined geo + text + attribute queries in one round trip — the main reason to pick this path.
• Higher per-query latency than a hand-tuned geohash bucket cache (tens of milliseconds rather than single digits).
• Inverted-index memory overhead, and write amplification on every business update.

Real-world echo. Yelp ran their core business search on Elasticsearch from 2017 onward (Yelp Engineering, “Moving Yelp’s Core Business Search to Elasticsearch”). In 2021 they replaced it with Nrtsearch, an in-house Lucene-based engine with near-real-time segment replication, citing Elasticsearch’s CPU cost from document-replicated indexing and difficulty autoscaling under bursty load (Yelp Engineering, “Nrtsearch: Yelp’s Fast, Scalable and Cost Effective Search Engine”). The lesson is not “don’t use Elasticsearch” but “the BKD-tree geo primitive lives in Lucene; you can wrap it with whichever query layer fits your cost model”.

Path comparison

This article’s focus

We continue with Path C (BKD via Elasticsearch) because most discovery products need combined text + geo + attribute queries in a single round trip, and the additional latency is acceptable inside a 100 ms budget. For systems that need single-digit-ms geo lookups at extreme scale (e.g. ride-share dispatch), an in-process H3 / S2 index sitting next to the business data store is a better fit.

API Design

Search nearby businesses

Endpoint: GET /api/v1/businesses/search

Query parameters:

Response (200 OK):

1{2  "businesses": [3    {4      "id": "biz_abc123",5      "name": "Joe's Coffee",6      "slug": "joes-coffee-san-francisco",7      "location": {8        "lat": 37.7749,9        "lon": -122.4194,10        "address": "123 Market St",11        "city": "San Francisco",12        "state": "CA",13        "postal_code": "94102",14        "country": "US"15      },16      "distance_meters": 450,17      "categories": [{ "id": "coffee", "name": "Coffee & Tea" }],18      "rating": 4.5,19      "review_count": 1247,20      "price_level": 2,21      "hours": {22        "is_open_now": true,23        "today": "7:00 AM - 8:00 PM"24      },25      "photos": {26        "thumbnail": "https://cdn.example.com/photos/abc123/thumb.jpg",27        "count": 52328      },29      "attributes": {30        "wifi": true,31        "outdoor_seating": true,32        "takes_reservations": false33      }34    }35  ],36  "total": 847,37  "cursor": "eyJvZmZzZXQiOjIwfQ==",38  "search_metadata": {39    "center": { "lat": 37.7749, "lon": -122.4194 },40    "radius_meters": 5000,41    "query_time_ms": 4242  }43}

Error responses.

• 400 Bad Request — invalid coordinates, radius out of range
• 429 Too Many Requests — rate limit exceeded

Rate limits. 100 requests/minute per authenticated user, 20/minute per anonymous IP.

Get business details

Endpoint: GET /api/v1/businesses/{business_id}

1{2  "id": "biz_abc123",3  "name": "Joe's Coffee",4  "slug": "joes-coffee-san-francisco",5  "claimed": true,6  "location": {7    "lat": 37.7749,8    "lon": -122.4194,9    "address": "123 Market St",10    "city": "San Francisco",11    "state": "CA",12    "postal_code": "94102",13    "country": "US",14    "cross_streets": "Market & 4th"15  },16  "contact": {17    "phone": "+1-415-555-0123",18    "website": "https://joescoffee.com"19  },20  "categories": [21    { "id": "coffee", "name": "Coffee & Tea" },22    { "id": "breakfast", "name": "Breakfast & Brunch" }23  ],24  "rating": 4.5,25  "review_count": 1247,26  "price_level": 2,27  "hours": {28    "monday": [{ "open": "07:00", "close": "20:00" }],29    "tuesday": [{ "open": "07:00", "close": "20:00" }],30    "is_open_now": true,31    "special_hours": [{ "date": "2024-12-25", "is_closed": true }]32  },33  "photos": [34    {35      "id": "photo_xyz",36      "url": "https://cdn.example.com/photos/xyz.jpg",37      "caption": "Interior",38      "user_id": "user_123"39    }40  ],41  "attributes": {42    "wifi": true,43    "outdoor_seating": true,44    "parking": "street",45    "noise_level": "moderate",46    "good_for": ["working", "casual_dining"],47    "accepts": ["credit_cards", "apple_pay"]48  },49  "highlights": ["Great for working remotely", "Excellent espresso"]50}

Submit review

Endpoint: POST /api/v1/businesses/{business_id}/reviews

1{2  "rating": 4,3  "text": "Great coffee and atmosphere. The baristas are friendly and the WiFi is fast. Perfect spot for remote work.",4  "photos": ["upload_token_1", "upload_token_2"]5}

1{2  "id": "review_def456",3  "business_id": "biz_abc123",4  "user": {5    "id": "user_789",6    "name": "John D.",7    "review_count": 42,8    "photo_url": "https://cdn.example.com/users/789.jpg"9  },10  "rating": 4,11  "text": "Great coffee and atmosphere...",12  "photos": [{ "id": "photo_1", "url": "https://cdn.example.com/..." }],13  "created_at": "2024-01-15T10:30:00Z",14  "status": "pending_moderation"15}

Error responses.

• 400 Bad Request — rating out of range (1-5), text too short (<50 chars) or too long (>5000 chars)
• 401 Unauthorized — not authenticated
• 403 Forbidden — user has already reviewed this business
• 429 Too Many Requests — review rate limit (5/day per user)

Pagination strategy

We use cursor-based pagination over offset because:

• Offset breaks under concurrent writes — at 300 K new reviews/day, offset=1000 returns different rows seconds apart.
• A cursor encodes the last seen sort key ({score: 4.5, id: "biz_xyz"}), so the next page is deterministic for the duration of the snapshot.
• The trade-off is the loss of “jump to page N”, which is rarely useful in a discovery UI.

1{2  "cursor": "eyJzY29yZSI6NC41LCJpZCI6ImJpel94eXoifQ==",3  "has_more": true4}

API response optimisation

• The default response includes only the fields needed for list views; detail views opt in via ?expand=hours,attributes,photos. This trims search payloads by ~60%.
• distance_meters and is_open_now are returned even though the client could compute them — both require server state (geo center, business timezone) that the client does not have on hand.

Data modeling

Business schema

The source of truth for businesses is a SQL store with PostGIS extensions, chosen for ACID writes, foreign keys, and PostGIS’s mature geo functions (PostGIS docs, ST_GeoHash).

1CREATE TABLE businesses (2    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),3    name VARCHAR(255) NOT NULL,4    slug VARCHAR(255) UNIQUE NOT NULL,56    latitude DECIMAL(10, 8) NOT NULL,7    longitude DECIMAL(11, 8) NOT NULL,8    geohash VARCHAR(12) GENERATED ALWAYS AS (9        ST_GeoHash(ST_SetSRID(ST_MakePoint(longitude, latitude), 4326), 12)10    ) STORED,11    address_line1 VARCHAR(255),12    address_line2 VARCHAR(255),13    city VARCHAR(100),14    state VARCHAR(100),15    postal_code VARCHAR(20),16    country CHAR(2) NOT NULL,17    timezone VARCHAR(64) NOT NULL,1819    phone VARCHAR(20),20    website VARCHAR(500),21    price_level SMALLINT CHECK (price_level BETWEEN 1 AND 4),2223    rating_avg DECIMAL(2, 1) DEFAULT 0,24    review_count INTEGER DEFAULT 0,25    photo_count INTEGER DEFAULT 0,2627    claimed BOOLEAN DEFAULT FALSE,28    owner_id UUID REFERENCES users(id),29    status VARCHAR(20) DEFAULT 'active',3031    created_at TIMESTAMPTZ DEFAULT NOW(),32    updated_at TIMESTAMPTZ DEFAULT NOW()33);3435CREATE INDEX idx_businesses_location ON businesses36    USING GIST (ST_SetSRID(ST_MakePoint(longitude, latitude), 4326));3738CREATE INDEX idx_businesses_geohash ON businesses (geohash varchar_pattern_ops);3940CREATE INDEX idx_businesses_city_status ON businesses (city, status)41    WHERE status = 'active';

A few non-obvious choices:

• The PostGIS GiST index is a Generalised Search Tree that wraps an R-tree on bounding boxes; ST_DWithin and ST_Intersects automatically use it (PostGIS spatial indexes FAQ).
• We carry a generated geohash column for cheap prefix-based bucketing in queries that do not warrant the full GiST scan (e.g. cache key generation).
• timezone is stored on the business — this is the only sane way to evaluate “open now” for businesses outside the user’s locale.
• Aggregates (rating_avg, review_count, photo_count) are denormalised because every list view needs them; the write path keeps them in sync inside a single transaction.

Business hours schema

1CREATE TABLE business_hours (2    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,3    day_of_week SMALLINT NOT NULL CHECK (day_of_week BETWEEN 0 AND 6),4    open_minute  SMALLINT NOT NULL CHECK (open_minute  BETWEEN 0 AND 1439),5    close_minute SMALLINT NOT NULL CHECK (close_minute BETWEEN 0 AND 2879),6    PRIMARY KEY (business_id, day_of_week, open_minute)7);89CREATE TABLE business_special_hours (10    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,11    date DATE NOT NULL,12    is_closed BOOLEAN DEFAULT FALSE,13    open_minute  SMALLINT,14    close_minute SMALLINT,15    PRIMARY KEY (business_id, date)16);

Categories schema

1CREATE TABLE categories (2    id VARCHAR(50) PRIMARY KEY,3    name VARCHAR(100) NOT NULL,4    parent_id VARCHAR(50) REFERENCES categories(id),5    level SMALLINT NOT NULL DEFAULT 06);78CREATE TABLE business_categories (9    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,10    category_id VARCHAR(50) REFERENCES categories(id),11    is_primary BOOLEAN DEFAULT FALSE,12    PRIMARY KEY (business_id, category_id)13);1415CREATE INDEX idx_business_categories_category ON business_categories (category_id);

Reviews schema

1CREATE TABLE reviews (2    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),3    business_id UUID NOT NULL REFERENCES businesses(id),4    user_id UUID NOT NULL REFERENCES users(id),5    rating SMALLINT NOT NULL CHECK (rating BETWEEN 1 AND 5),6    text TEXT NOT NULL CHECK (char_length(text) BETWEEN 50 AND 5000),78    status VARCHAR(20) DEFAULT 'pending',9    moderation_score DECIMAL(3, 2),10    moderated_at TIMESTAMPTZ,1112    useful_count INTEGER DEFAULT 0,13    funny_count INTEGER DEFAULT 0,14    cool_count INTEGER DEFAULT 0,1516    created_at TIMESTAMPTZ DEFAULT NOW(),17    updated_at TIMESTAMPTZ DEFAULT NOW(),1819    UNIQUE (business_id, user_id)20);2122CREATE INDEX idx_reviews_business ON reviews (business_id, created_at DESC)23    WHERE status = 'approved';24CREATE INDEX idx_reviews_user ON reviews (user_id, created_at DESC);25CREATE INDEX idx_reviews_pending ON reviews (status, created_at)26    WHERE status = 'pending';

Elasticsearch index mapping

1{2  "mappings": {3    "properties": {4      "id": { "type": "keyword" },5      "name": {6        "type": "text",7        "analyzer": "standard",8        "fields": {9          "keyword": { "type": "keyword" },10          "autocomplete": {11            "type": "text",12            "analyzer": "autocomplete"13          }14        }15      },16      "location": { "type": "geo_point" },17      "geohash": { "type": "keyword" },18      "city": { "type": "keyword" },19      "country": { "type": "keyword" },20      "categories": { "type": "keyword" },21      "price_level": { "type": "integer" },22      "rating_avg": { "type": "float" },23      "review_count": { "type": "integer" },24      "attributes": {25        "type": "object",26        "properties": {27          "wifi": { "type": "boolean" },28          "outdoor_seating": { "type": "boolean" },29          "parking": { "type": "keyword" }30        }31      },32      "hours": {33        "type": "nested",34        "properties": {35          "day": { "type": "integer" },36          "open_minute": { "type": "integer" },37          "close_minute": { "type": "integer" }38        }39      },40      "updated_at": { "type": "date" }41    }42  },43  "settings": {44    "index": {45      "refresh_interval": "1s"46    },47    "analysis": {48      "analyzer": {49        "autocomplete": {50          "type": "custom",51          "tokenizer": "standard",52          "filter": ["lowercase", "autocomplete_filter"]53        }54      },55      "filter": {56        "autocomplete_filter": {57          "type": "edge_ngram",58          "min_gram": 2,59          "max_gram": 2060        }61      }62    }63  }64}

The geo_point field is stored using Lucene’s BKD-tree implementation, so geo_distance and geo_bounding_box queries hit the multi-dimensional index directly. refresh_interval: 1s matches the Elasticsearch default and gives near-real-time visibility — newly indexed documents become searchable within ~1 second of an indexing call (Elasticsearch near real-time docs).

Database selection rationale

Sharding strategy

PostgreSQL. When a single primary stops being enough, shard by country or region. The vast majority of queries are region-local (people search near where they are), and the rare cross-region query goes through a query router that fans out to relevant shards.

Elasticsearch. Shard by geohash prefix, e.g. the first two characters yields up to 1024 routing keys (32^2). Coupled with _routing on writes and queries, this lets a search request hit a small subset of shards rather than fanning out across the cluster.

Write throughput across many writers. The visible review write rate is small (~3.5/s in the planning model), but the latent write rate is much higher once you fold in business edits, photo metadata updates, hours/menu changes pushed in by partners, check-ins, and reaction counts (useful_count etc.). A single business document can take dozens of updates per day, and Elasticsearch reindexes the full document on every update. Three operational levers matter:

• Coalesce updates per business in a short window (5–30 s) before flushing to ES; the ratings worker reads the latest aggregates from PostgreSQL once instead of replaying every increment.
• Separate hot and cold writers onto different Kafka consumer groups so a backlog of photo-derive events does not delay the rating-aggregate stream.
• Watch outbox lag as a first-class SLO. The transactional outbox guarantees correctness, not freshness; lag silently degrades search relevance long before it shows up as user-visible breakage.

Low-level design: geospatial search

Search flow

Elasticsearch query construction

Basic geo query:

1{2  "query": {3    "bool": {4      "must": [{ "match": { "status": "active" } }],5      "filter": [6        {7          "geo_distance": {8            "distance": "5km",9            "location": {10              "lat": 37.7749,11              "lon": -122.419412            }13          }14        }15      ]16    }17  },18  "sort": [19    {20      "_geo_distance": {21        "location": { "lat": 37.7749, "lon": -122.4194 },22        "order": "asc",23        "unit": "m"24      }25    }26  ]27}

geo_distance defaults to the arc distance type, which uses the Haversine formula on WGS84 — boundary-correct without geohash neighbour expansion (geo_distance reference).

With category and attribute filters:

1{2  "query": {3    "bool": {4      "must": [{ "match": { "status": "active" } }],5      "filter": [6        {7          "geo_distance": {8            "distance": "5km",9            "location": { "lat": 37.7749, "lon": -122.4194 }10          }11        },12        { "terms": { "categories": ["coffee", "cafe"] } },13        { "term": { "attributes.wifi": true } },14        { "range": { "price_level": { "lte": 2 } } }15      ]16    }17  }18}

“Open now” filter (nested hours):

The “open now” predicate needs both the day-of-week and minute-of-day in the business’s local timezone, not the user’s:

1{2  "query": {3    "bool": {4      "filter": [5        {6          "nested": {7            "path": "hours",8            "query": {9              "bool": {10                "must": [11                  { "term": { "hours.day": 1 } },12                  { "range": { "hours.open_minute":  { "lte": 630 } } },13                  { "range": { "hours.close_minute": { "gt":  630 } } }14                ]15              }16            }17          }18        }19      ]20    }21  }22}

Geospatial caching strategy

1Key  : geo:search:{geohash6}:{category}:{filters_hash}2Value: [business_id_1, business_id_2, ...]3TTL  : 5 minutes

Why bucket by 6-character geohash:

• Two queries with centres less than ~1 km apart usually land in the same prefix, so they share a cache line.
• Different filter combinations get distinct keys, so we never serve a cached result that misses a filter.

Invalidation:

• A business update enqueues an event that drops every cache entry whose geohash prefix matches the business’s current location and the previous location (so a moved business does not linger).
• New businesses are not invalidated explicitly; the 5-minute TTL absorbs them. This is acceptable because discovery is not a real-time UX.

Ranking algorithm

The pipeline is two-phase by design — cheap retrieval narrows the candidate set so the expensive multi-signal scoring runs on hundreds of documents, not millions. Diversification (no five Starbucks in a row) and dedup (the same operator across two storefronts in the same plaza) sit downstream of scoring because they need the full ranked list to make sensible swaps.

We blend signals into a single score:

Where:

• (closer = higher score)
• (normalised 0–1)
• (log-scaled to defang very popular outliers)
• (exponential decay)
• — personalisation signal in [0, 1]

Default weights (tuned via A/B testing, treat as starting point not gospel):

Elasticsearch function_score implementation:

1{2  "query": {3    "function_score": {4      "query": { "bool": { "filter": [ /* geo + attribute filters */ ] } },5      "functions": [6        {7          "gauss": {8            "location": {9              "origin": { "lat": 37.77, "lon": -122.41 },10              "scale": "2km",11              "decay": 0.512            }13          },14          "weight": 2515        },16        {17          "field_value_factor": {18            "field": "rating_avg",19            "factor": 1,20            "modifier": "none",21            "missing": 322          },23          "weight": 3024        },25        {26          "field_value_factor": {27            "field": "review_count",28            "factor": 1,29            "modifier": "log1p",30            "missing": 131          },32          "weight": 2033        }34      ],35      "score_mode": "sum",36      "boost_mode": "replace"37    }38  }39}

The gauss decay over geo_point is the official idiom for distance-aware ranking; log1p on review_count is the recommended modifier when the field can be 0 (it computes , avoiding log(0) blow-ups) (function_score reference).

Handling edge cases

Sparse areas (few results):

• If fewer than 10 results land within the requested radius, expand to 2× radius automatically.
• Cap expansion at 50 km so a search in rural Wyoming does not turn into a continental scan.
• Surface the expansion in the response (expanded_radius: true) so the client can show “showing nearby results” copy.

Dense areas (too many results):

• Pre-filter by quality threshold (rating >= 3.0, review_count >= 5) before scoring.
• Cap the candidate set at 1,000 documents per shard; the ranker does not want to score the entire neighbourhood.
• For map-view UIs, switch from per-business markers to heat-map aggregation at low zoom: roll counts up into H3 (or geohash) cells with Elasticsearch’s geohex_grid / geohash_grid aggregation and render polygons coloured by density. This both saves payload (one polygon per cell vs hundreds of pins) and avoids marker-cluster jitter as the user pans.

Boundary problems. Because geo_distance defaults to the arc/Haversine calculation, you do not need the geohash “+8 neighbours” trick — a single bounding-box-then-distance pass is correct.

Low-level design: review system

Review submission flow

Spam detection signals

Thresholds.

• Score < 0.3 → auto-approve.
• Score 0.3–0.7 → auto-approve with a flag for sampling-based human review.
• Score > 0.7 → manual review required.

These weights and thresholds are not principled in the statistical sense; they are starting points to be tuned against a labelled dataset and an FN/FP cost model.

Rating aggregation

A naive arithmetic mean breaks down on small samples: a business with one 5-star review ranks above a business with a thousand reviews averaging 4.8. Two well-known fixes:

Bayesian weighted average (Wikipedia: Bayesian average, Evan Miller, “Bayesian Average Ratings”):

Where:

• = confidence parameter (typically 10–50)
• = prior mean (the global average rating, ~3.7 for Yelp-style platforms)
• = number of reviews

Worked example with , :

• New business with 2 reviews, both 5 stars.
• Naive mean: 5.0.
• Bayesian: .

The Bayesian shrinkage pulls under-evidenced businesses toward the prior, which is exactly what you want at the top of a discovery list.

Wilson lower bound (Evan Miller, “How Not To Sort By Average Rating”) is an alternative when the rating space is binary (upvote/downvote). For 5-star ratings, you have to map stars to fractional positives, which is plausible but introduces tuning of its own. Bayesian shrinkage is the more common pick for star-rated discovery surfaces.

Review update consistency — the transactional outbox

When a review is approved, four systems need to converge:

1. PostgreSQL — review status flips to approved.
2. PostgreSQL — businesses.rating_avg and review_count are updated.
3. Elasticsearch — the business document is reindexed.
4. Redis — affected cache entries are invalidated.

Doing all four inside a single distributed transaction would require XA or saga compensation. The cheaper, well-established alternative is the transactional outbox (microservices.io: Pattern: Transactional outbox):

1BEGIN;2  UPDATE reviews SET status = 'approved' WHERE id = $1;34  UPDATE businesses5  SET rating_avg = (6        SELECT AVG(rating) FROM reviews7        WHERE business_id = $2 AND status = 'approved'),8      review_count = (9        SELECT COUNT(*) FROM reviews10        WHERE business_id = $2 AND status = 'approved')11  WHERE id = $2;1213  INSERT INTO outbox (event_type, payload)14  VALUES ('ReviewApproved',15          jsonb_build_object('review_id', $1, 'business_id', $2));16COMMIT;

A separate outbox relay — either a CDC stream off the WAL via Debezium, or a polling worker — reads the outbox table, publishes to Kafka, and downstream consumers reindex Elasticsearch and invalidate Redis. The trade-off is at-least-once delivery: consumers must be idempotent (key on review_id) because the relay can crash after publishing but before marking the row processed.

Consistency window. PostgreSQL is immediately consistent for the business profile read path. The search index trails by ~1–5 seconds (Elasticsearch refresh + outbox propagation). The author of the review sees their own pending review immediately via a “read your writes” override on the user-scoped review feed, so the eventual consistency is invisible to them.

Frontend considerations

Search results data structure

Optimised for list rendering and detail-view reuse:

1interface SearchState {2  businesses: Record<string, Business>3  resultIds: string[]4  cursor: string | null5  hasMore: boolean6  searchParams: {7    lat: number8    lon: number9    radius: number10    filters: Record<string, unknown>11  }12  isLoading: boolean13  error: string | null14}

Why normalised (entity map plus an ID list):

• Moving between list and detail views does not duplicate data.
• A field updated from the detail view (e.g. is_open_now flipping at 5pm) propagates to the list.
• React renders are cheap because reference equality holds for unchanged entities.

Mobile location accuracy

The lat/lon the client hands you is not a point — it is a probability cloud. Phones derive position from GPS / GNSS, Wi-Fi BSSID lookups, cell-tower triangulation, and IP geolocation, in roughly that order of accuracy. Typical reported accuracies (from the W3C Geolocation API coords.accuracy and the iOS / Android platform docs) are 5–20 m outdoors with a clean GPS fix, 20–100 m on Wi-Fi-only positioning indoors, and >1 km when the device falls back to IP.

Three implications for proximity search:

• Treat accuracy as a search input, not a debug field. When the radius the user requested is smaller than the location uncertainty (e.g. radius=200m, accuracy=500m), expand the server-side search radius to max(radius, 2 × accuracy) and surface a “showing nearby” hint. Returning an empty result when the device is just unsure is a worse UX than returning slightly farther matches.
• Snap “use my location” to the IP-region for cold-start. First-paint of the search page often runs before the GPS fix arrives; degrade to coarse (city-level) results from IP, then re-issue the query when the precise fix lands.
• Throttle on the client. GPS deltas under ~30 m within a 10 s window almost never change the result list. Debounce both the geolocation watcher and the search request, and never refetch on every watchPosition callback.

Map integration

• Cluster markers when more than ~30 businesses are visible in the viewport; 50+ raw markers on mobile drop animation FPS noticeably.
• Debounce map move events (~300 ms). Only refetch when the visible bounds change by more than ~20% of the previous viewport area.

1interface MapSearchParams {2  bounds: {3    ne: { lat: number; lon: number }4    sw: { lat: number; lon: number }5  }6  zoom: number7}

Offline considerations

• Cache the last 5 search results (entity map + list of IDs) plus the top-10 detail payloads.
• Budget ~50 MB on mobile so the offline cache does not crowd out the OS.

1// Search results: network-first, cache fallback.2// Business details: stale-while-revalidate.3// Review submission: never cached - must succeed online.

Real-time updates

• Poll review counts and ratings every ~5 minutes; users do not benefit from sub-minute granularity.
• Recompute is_open_now client-side every minute when the user is within ±15 minutes of an open/close transition.
• Do not stream live reviews into the UI — it is volatile, low-signal, and confusing.

Infrastructure

Cloud-agnostic architecture

AWS reference implementation

Multi-region strategy

Active-active for reads. Each region holds full read replicas of the data plane and serves search queries locally to the user.

Primary region for writes. Reviews and business edits land in a primary region and replicate asynchronously elsewhere. Lag is typically under 5 seconds and is acceptable because business content changes infrequently.

Failover. Route 53 health checks detect a regional outage and shift traffic to a healthy region; RTO target ~1 minute, RPO target ~30 seconds. Run the failover game day at least quarterly — the only failovers that work are the ones you have rehearsed.

Cost optimisation

Common pitfalls

1. Geohash boundary issues

Problem. A query at a cell boundary misses nearby businesses that fall into the adjacent cell. Cause. Querying only the target geohash cell. Fix. Query the target cell plus the 8 neighbours, or use a true geo_distance query (PostGIS ST_DWithin, ES geo_distance) that handles boundaries on the geometry itself.

2. Rating manipulation

Problem. Business owners create fake accounts to inflate ratings. Cause. No detection of review authenticity. Fix. Multi-signal spam scoring (the table above), IP/device fingerprinting, account-age requirements, sampling-based manual review, and a Bayesian prior so a handful of perfect reviews cannot dominate the leaderboard.

3. Stale search results

Problem. Newly added businesses do not appear in search for hours. Cause. Index refresh_interval set too high under indexing pressure, or the outbox relay is backed up. Fix. Keep refresh_interval at the 1-second default for hot indices; monitor outbox lag as a first-class SLO; trigger an explicit _refresh for critical writes.

4. “Open now” timezone bugs

Problem. Businesses show as open or closed at the wrong times, especially around DST transitions. Cause. Storing only a UTC offset, or doing timezone math by adding hours. Fix. Store the IANA timezone (America/Los_Angeles) on the business; convert at query time using a real timezone library; store time-of-day as minutes-since-midnight rather than HHMM.

5. Photo storage cost explosion

Problem. Photo storage costs grow much faster than user growth. Cause. Storing originals at the resolution the phone uploaded, with no resize, compression, or lifecycle. Fix. Resize on ingest (max ~2048 px on long edge), generate thumbnail/medium variants, prefer modern codecs (AVIF/WebP), apply S3 Intelligent-Tiering and a lifecycle that archives photos older than N years.

6. Review consistency lag

Problem. A user submits a review, refreshes, and does not see it. Cause. Async processing creates a visibility delay that the user reads as “the system lost my review”. Fix. Read-your-writes for the author: surface their own pending review on user-scoped views immediately, with a “pending moderation” badge.

Conclusion

This design treats search latency and result quality as the primary optimisation targets, accepting complexity in the write path and eventual consistency where the user cannot tell.

Key architectural decisions.

1. Lucene BKD via Elasticsearch (or Nrtsearch) rather than a hand-rolled geo index — the 20–30 ms latency overhead is comfortable inside a 100 ms budget and avoids running a second specialised store.
2. Denormalised aggregates (rating_avg, review_count) on the business row — trades write complexity for read performance.
3. Transactional outbox for the review write path — gives eventual consistency across PostgreSQL, Elasticsearch, and Redis without distributed transactions, with idempotent consumers absorbing the at-least-once delivery.
4. Multi-signal ranking with tunable weights — A/B-able without code changes, and Bayesian-shrinkage on rating defangs the small-sample-size pathology.

What this design sacrifices.

• Real-time consistency for search results — a 1–5 second window is acceptable.
• Single-digit-millisecond geo lookups — would require an in-process H3/S2 store next to the business data.
• Perfect spam detection — manual review is still required for the long tail.

Future improvements.

• Personalised ranking using user history and contextual bandits, à la Yelp’s home personalisation.
• “Popular times” using check-in and visit data.
• Voice search and image search for mobile.
• Business insights dashboard for owners.

Appendix

Prerequisites

• Distributed-systems fundamentals (CAP theorem, consistency models).
• Database indexing concepts (B-trees, inverted indexes, k-d trees).
• Geospatial basics (latitude/longitude, great-circle distance, WGS84).
• Familiarity with Elasticsearch or a similar inverted-index search engine.

Terminology

Summary

• Proximity search needs a spatial index; the right shape (geohash vs S2/H3 vs BKD) depends on density variance, query mix, and latency budget.
• Multi-signal ranking — distance + rating + review count + recency — beats sorting by distance alone, and Bayesian shrinkage stops new businesses with two perfect reviews from dominating the page.
• Reviews flow through a transactional outbox so the search index, cache, and analytics warehouse stay in step without distributed transactions.
• Denormalisation and aggressive caching are non-negotiable inside a 100 ms p99 search budget.
• Eventual consistency under ~5 seconds is fine for discovery, but the author of new content needs read-your-writes to trust the system.

References

• Elasticsearch geo queries reference — geo_distance, geo_bounding_box, geo_shape.
• Elastic blog: Multi-dimensional points coming in Apache Lucene 6.0 — BKD-tree introduction.
• Elastic blog: BKD-backed geo_shapes — modern geo indexing.
• Elasticsearch near-real-time search — refresh_interval semantics.
• Elasticsearch function_score reference — gauss decay and field_value_factor.
• Google S2 Geometry library and S2 cell statistics.
• Uber H3: Hexagonal Hierarchical Spatial Index.
• PostGIS documentation — ST_GeoHash, GIST indexes, ST_DWithin.
• Yelp Engineering: Moving Yelp’s core business search to Elasticsearch.
• Yelp Engineering: Nrtsearch — why Yelp moved off Elasticsearch.
• microservices.io: Transactional outbox pattern.
• Wikipedia: Bayesian average and Evan Miller: Bayesian Average Ratings.
• Evan Miller: How Not To Sort By Average Rating — Wilson lower-bound interval.