Yelp: geo discovery + reviews

<?php

declare(strict_types=1);

final readonly class SearchRequest
{
    /**
     * @param list<string> $categories
     */
    public function __construct(
        public ?string $query,
        public float $lat,
        public float $lon,
        public int $radiusM = 1000,
        public array $categories = [],
        public ?float $minRating = null,
        public ?string $priceLevel = null,  // $..$$$$
        public string $sort = 'best_match', // best_match|distance|rating|reviews
        public int $limit = 20,
        public ?string $cursor = null,
    ) {}
}

final readonly class BusinessDTO
{
    public function __construct(
        public string $id,
        public string $name,
        public string $categorySlug,
        public float $lat,
        public float $lon,
        public float $rating,
        public int $reviewsCount,
        public string $priceLevel,
        public string $photoUrl,
        public float $distanceM,
    ) {}
}

package api

type SearchRequest struct {
    Query      string   `json:"q,omitempty"`
    Lat        float64  `json:"lat"`
    Lon        float64  `json:"lon"`
    RadiusM    int      `json:"radius_m"`
    Categories []string `json:"categories,omitempty"`
    MinRating  float64  `json:"min_rating,omitempty"`
    Sort       string   `json:"sort,omitempty"`
    Limit      int      `json:"limit,omitempty"`
    Cursor     string   `json:"cursor,omitempty"`
}

type BusinessDTO struct {
    ID           string  `json:"id"`
    Name         string  `json:"name"`
    CategorySlug string  `json:"category"`
    Lat          float64 `json:"lat"`
    Lon          float64 `json:"lon"`
    Rating       float64 `json:"rating"`
    ReviewsCount int     `json:"reviews_count"`
    PriceLevel   string  `json:"price_level"`
    PhotoURL     string  `json:"photo_url"`
    DistanceM    float64 `json:"distance_m"`
}

using System.Text.Json.Serialization;

namespace Yelp.Api;

// Positional record: immutable value type, the C# analogue of a readonly PHP class.
public sealed record SearchRequest(
    double Lat,
    double Lon,
    string? Query = null,
    int RadiusM = 1000,
    IReadOnlyList<string>? Categories = null,
    double? MinRating = null,
    string? PriceLevel = null,   // $..$$$$
    string Sort = "best_match",  // best_match|distance|rating|reviews
    int Limit = 20,
    string? Cursor = null);

// [property: ...] puts the attribute on the generated property,
// which is the C# equivalent of Go struct tags.
public sealed record BusinessDto(
    [property: JsonPropertyName("id")] string Id,
    [property: JsonPropertyName("name")] string Name,
    [property: JsonPropertyName("category")] string CategorySlug,
    [property: JsonPropertyName("lat")] double Lat,
    [property: JsonPropertyName("lon")] double Lon,
    [property: JsonPropertyName("rating")] double Rating,
    [property: JsonPropertyName("reviews_count")] int ReviewsCount,
    [property: JsonPropertyName("price_level")] string PriceLevel,
    [property: JsonPropertyName("photo_url")] string PhotoUrl,
    [property: JsonPropertyName("distance_m")] double DistanceM);

from dataclasses import dataclass

# frozen=True gives immutability, slots=True cuts per-instance memory.
@dataclass(frozen=True, slots=True)
class SearchRequest:
    lat: float
    lon: float
    query: str | None = None
    radius_m: int = 1000
    categories: tuple[str, ...] = ()  # tuple, not list: default must be hashable
    min_rating: float | None = None
    price_level: str | None = None    # $..$$$$
    sort: str = "best_match"          # best_match|distance|rating|reviews
    limit: int = 20
    cursor: str | None = None

@dataclass(frozen=True, slots=True)
class BusinessDTO:
    id: str
    name: str
    category_slug: str
    lat: float
    lon: float
    rating: float
    reviews_count: int
    price_level: str
    photo_url: str
    distance_m: float

package search

import (
    "context"
    "database/sql"
)

type BusinessRow struct {
    ID           string
    Name         string
    CategorySlug string
    Lat          float64
    Lon          float64
    Rating       float64
    Reviews      int
    DistanceM    float64
}

type Repo struct {
    DB *sql.DB
}

// Nearby searches using PostGIS ST_DWithin + ST_Distance.
func (r *Repo) Nearby(ctx context.Context, lat, lon float64, radiusM int, cats []string, minRating float64, limit int) ([]BusinessRow, error) {
    rows, err := r.DB.QueryContext(ctx, `
        SELECT
            b.id, b.name, c.slug,
            ST_Y(b.location::geometry), ST_X(b.location::geometry),
            b.rating_avg, b.reviews_count,
            ST_Distance(b.location, ST_MakePoint($1, $2)::geography) AS dist
        FROM businesses b
        JOIN categories c ON c.id = b.category_id
        WHERE ST_DWithin(b.location, ST_MakePoint($1, $2)::geography, $3)
          AND b.status = 1
          AND ($4::text[] IS NULL OR c.slug = ANY($4))
          AND ($5::numeric IS NULL OR b.rating_avg >= $5)
        ORDER BY dist
        LIMIT $6
    `, lon, lat, radiusM, cats, minRating, limit)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    out := make([]BusinessRow, 0, limit)
    for rows.Next() {
        var b BusinessRow
        if err := rows.Scan(&b.ID, &b.Name, &b.CategorySlug,
            &b.Lat, &b.Lon, &b.Rating, &b.Reviews, &b.DistanceM); err != nil {
            return nil, err
        }
        out = append(out, b)
    }
    return out, nil
}

using Npgsql;

namespace Yelp.Search;

public sealed record BusinessRow(
    string Id,
    string Name,
    string CategorySlug,
    double Lat,
    double Lon,
    double Rating,
    int Reviews,
    double DistanceM);

public sealed class BusinessRepository(NpgsqlDataSource dataSource)
{
    private const string NearbySql = """
        SELECT
            b.id, b.name, c.slug,
            ST_Y(b.location::geometry), ST_X(b.location::geometry),
            b.rating_avg, b.reviews_count,
            ST_Distance(b.location, ST_MakePoint($1, $2)::geography) AS dist
        FROM businesses b
        JOIN categories c ON c.id = b.category_id
        WHERE ST_DWithin(b.location, ST_MakePoint($1, $2)::geography, $3)
          AND b.status = 1
          AND ($4::text[] IS NULL OR c.slug = ANY($4))
          AND ($5::numeric IS NULL OR b.rating_avg >= $5)
        ORDER BY dist
        LIMIT $6
        """;

    // Nearby searches using PostGIS ST_DWithin + ST_Distance.
    public async Task<IReadOnlyList<BusinessRow>> NearbyAsync(
        double lat,
        double lon,
        int radiusM,
        string[]? cats,
        double? minRating,
        int limit,
        CancellationToken ct = default)
    {
        await using var cmd = dataSource.CreateCommand(NearbySql);
        // Positional parameters are bound in declaration order ($1..$6).
        cmd.Parameters.Add(new NpgsqlParameter { Value = lon });
        cmd.Parameters.Add(new NpgsqlParameter { Value = lat });
        cmd.Parameters.Add(new NpgsqlParameter { Value = radiusM });
        cmd.Parameters.Add(new NpgsqlParameter { Value = (object?)cats ?? DBNull.Value });
        cmd.Parameters.Add(new NpgsqlParameter { Value = (object?)minRating ?? DBNull.Value });
        cmd.Parameters.Add(new NpgsqlParameter { Value = limit });

        await using var reader = await cmd.ExecuteReaderAsync(ct);

        var result = new List<BusinessRow>(limit);
        while (await reader.ReadAsync(ct))
        {
            result.Add(new BusinessRow(
                reader.GetString(0),
                reader.GetString(1),
                reader.GetString(2),
                reader.GetDouble(3),
                reader.GetDouble(4),
                (double)reader.GetDecimal(5),  // Npgsql maps NUMERIC to decimal
                reader.GetInt32(6),
                reader.GetDouble(7)));
        }
        return result;
    }
}

from dataclasses import dataclass
from decimal import Decimal

import asyncpg

NEARBY_SQL = """
    SELECT
        b.id, b.name, c.slug,
        ST_Y(b.location::geometry) AS lat, ST_X(b.location::geometry) AS lon,
        b.rating_avg, b.reviews_count,
        ST_Distance(b.location, ST_MakePoint($1, $2)::geography) AS dist
    FROM businesses b
    JOIN categories c ON c.id = b.category_id
    WHERE ST_DWithin(b.location, ST_MakePoint($1, $2)::geography, $3)
      AND b.status = 1
      AND ($4::text[] IS NULL OR c.slug = ANY($4))
      AND ($5::numeric IS NULL OR b.rating_avg >= $5)
    ORDER BY dist
    LIMIT $6
"""

@dataclass(frozen=True, slots=True)
class BusinessRow:
    id: str
    name: str
    category_slug: str
    lat: float
    lon: float
    rating: float
    reviews: int
    distance_m: float

class BusinessRepo:
    def __init__(self, pool: asyncpg.Pool) -> None:
        self._pool = pool

    # Nearby searches using PostGIS ST_DWithin + ST_Distance.
    async def nearby(
        self,
        lat: float,
        lon: float,
        radius_m: int,
        cats: list[str] | None,
        min_rating: float | None,
        limit: int,
    ) -> list[BusinessRow]:
        # asyncpg binds NUMERIC strictly: float would be rejected, so wrap in Decimal.
        rating = Decimal(str(min_rating)) if min_rating is not None else None
        rows = await self._pool.fetch(
            NEARBY_SQL, lon, lat, radius_m, cats, rating, limit
        )
        return [
            BusinessRow(
                id=str(r["id"]),
                name=r["name"],
                category_slug=r["slug"],
                lat=r["lat"],
                lon=r["lon"],
                rating=float(r["rating_avg"]),
                reviews=r["reviews_count"],
                distance_m=r["dist"],
            )
            for r in rows
        ]

<?php

declare(strict_types=1);

final class SearchController
{
    public function __construct(
        private readonly \Elastic\Elasticsearch\Client $es,
        private readonly CityCache $cityCache,   // top categories per city
    ) {}

    public function search(SearchRequest $req): array
    {
        $filter = [
            ['geo_distance' => [
                'distance' => $req->radiusM . 'm',
                'location' => ['lat' => $req->lat, 'lon' => $req->lon],
            ]],
        ];
        if (!empty($req->categories)) {
            $filter[] = ['terms' => ['categories' => $req->categories]];
        }
        if ($req->minRating !== null) {
            $filter[] = ['range' => ['rating' => ['gte' => $req->minRating]]];
        }

        $must = [];
        if ($req->query !== null && $req->query !== '') {
            $must[] = ['multi_match' => [
                'query' => $req->query,
                'fields' => ['name^3', 'description', 'categories'],
                'fuzziness' => 'AUTO',
            ]];
        }

        $sort = match ($req->sort) {
            'distance' => [['_geo_distance' => ['location' => ['lat' => $req->lat, 'lon' => $req->lon], 'order' => 'asc', 'unit' => 'm']]],
            'rating'   => [['rating' => 'desc'], ['reviews_count' => 'desc']],
            'reviews'  => [['reviews_count' => 'desc']],
            default    => [
                // best_match: combination of _score + rating + distance penalty
                '_score',
                ['rating' => 'desc'],
                ['_geo_distance' => ['location' => ['lat' => $req->lat, 'lon' => $req->lon], 'order' => 'asc', 'unit' => 'm']],
            ],
        };

        $resp = $this->es->search([
            'index' => 'businesses',
            'body'  => [
                'size'  => $req->limit,
                'query' => ['bool' => ['must' => $must, 'filter' => $filter]],
                'sort'  => $sort,
            ],
        ]);

        return array_map(
            static fn(array $hit) => [
                'id'           => $hit['_source']['id'],
                'name'         => $hit['_source']['name'],
                'rating'       => $hit['_source']['rating'],
                'reviews_count'=> $hit['_source']['reviews_count'],
                'photo_url'    => $hit['_source']['photo_url'] ?? null,
                'distance_m'   => $hit['sort'][1] ?? null,
            ],
            $resp['hits']['hits'] ?? [],
        );
    }
}

using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.AspNetCore.Mvc;

namespace Yelp.Search;

public sealed record SearchHit(
    string Id,
    string Name,
    double Rating,
    int ReviewsCount,
    string? PhotoUrl,
    double? DistanceM);

[ApiController]
[Route("api/v1")]
public sealed class SearchController(HttpClient elastic) : ControllerBase
{
    // Elastic.Clients.Elasticsearch ships a typed DSL, but an anonymous-object
    // body maps 1:1 onto the ES query shown above and stays readable.
    [HttpGet("search")]
    public async Task<IReadOnlyList<SearchHit>> Search(
        [FromQuery] SearchRequest req,
        CancellationToken ct)
    {
        var filter = new List<object>
        {
            new { geo_distance = new
            {
                distance = $"{req.RadiusM}m",
                location = new { lat = req.Lat, lon = req.Lon },
            }},
        };
        if (req.Categories is { Count: > 0 } categories)
        {
            filter.Add(new { terms = new { categories } });
        }
        if (req.MinRating is { } minRating)
        {
            filter.Add(new { range = new { rating = new { gte = minRating } } });
        }

        var must = new List<object>();
        if (!string.IsNullOrEmpty(req.Query))
        {
            must.Add(new { multi_match = new
            {
                query = req.Query,
                fields = new[] { "name^3", "description", "categories" },
                fuzziness = "AUTO",
            }});
        }

        object geoSort = new { _geo_distance = new
        {
            location = new { lat = req.Lat, lon = req.Lon },
            order = "asc",
            unit = "m",
        }};

        object[] sort = req.Sort switch
        {
            "distance" => [geoSort],
            "rating"   => [new { rating = "desc" }, new { reviews_count = "desc" }],
            "reviews"  => [new { reviews_count = "desc" }],
            // best_match: combination of _score + rating + distance penalty
            _          => ["_score", new { rating = "desc" }, geoSort],
        };

        var body = new
        {
            size = req.Limit,
            query = new { @bool = new { must, filter } },  // bool is a keyword, hence @
            sort,
        };

        using var response = await elastic.PostAsJsonAsync("/businesses/_search", body, ct);
        response.EnsureSuccessStatusCode();
        using var json = JsonDocument.Parse(await response.Content.ReadAsStreamAsync(ct));

        return json.RootElement.GetProperty("hits").GetProperty("hits")
            .EnumerateArray()
            .Select(hit =>
            {
                var src = hit.GetProperty("_source");
                return new SearchHit(
                    src.GetProperty("id").GetString()!,
                    src.GetProperty("name").GetString()!,
                    src.GetProperty("rating").GetDouble(),
                    src.GetProperty("reviews_count").GetInt32(),
                    src.TryGetProperty("photo_url", out var photo) ? photo.GetString() : null,
                    hit.TryGetProperty("sort", out var s) && s.GetArrayLength() > 1
                        ? s[1].GetDouble()
                        : null);
            })
            .ToList();
    }
}

from typing import Any

from elasticsearch import AsyncElasticsearch

class SearchService:
    def __init__(self, es: AsyncElasticsearch) -> None:
        self._es = es

    async def search(self, req: SearchRequest) -> list[dict[str, Any]]:
        filters: list[dict[str, Any]] = [
            {"geo_distance": {
                "distance": f"{req.radius_m}m",
                "location": {"lat": req.lat, "lon": req.lon},
            }},
        ]
        if req.categories:
            filters.append({"terms": {"categories": list(req.categories)}})
        if req.min_rating is not None:
            filters.append({"range": {"rating": {"gte": req.min_rating}}})

        must: list[dict[str, Any]] = []
        if req.query:
            must.append({"multi_match": {
                "query": req.query,
                "fields": ["name^3", "description", "categories"],
                "fuzziness": "AUTO",
            }})

        geo_sort = {"_geo_distance": {
            "location": {"lat": req.lat, "lon": req.lon},
            "order": "asc",
            "unit": "m",
        }}

        match req.sort:
            case "distance":
                sort: list[Any] = [geo_sort]
            case "rating":
                sort = [{"rating": "desc"}, {"reviews_count": "desc"}]
            case "reviews":
                sort = [{"reviews_count": "desc"}]
            case _:
                # best_match: combination of _score + rating + distance penalty
                sort = ["_score", {"rating": "desc"}, geo_sort]

        resp = await self._es.search(
            index="businesses",
            size=req.limit,
            query={"bool": {"must": must, "filter": filters}},
            sort=sort,
        )

        return [
            {
                "id": hit["_source"]["id"],
                "name": hit["_source"]["name"],
                "rating": hit["_source"]["rating"],
                "reviews_count": hit["_source"]["reviews_count"],
                "photo_url": hit["_source"].get("photo_url"),
                "distance_m": hit["sort"][1] if len(hit.get("sort", [])) > 1 else None,
            }
            for hit in resp["hits"]["hits"]
        ]