lacspace-leads 1.2.1 → 1.4.0

package/README.md

@@ -12,6 +12,7 @@ That opens a browser, searches Maps for *"restaurants in Baneshwor, Kathmandu"*,
 
 - **Free & keyless** — uses a real browser (via [Playwright](https://playwright.dev)), not a paid Places API.
 - **Sweep a whole city** — comma-separate areas and it runs each search, then **merges and de-duplicates** into one list: `--area "Thamel,Baneshwor,Patan"`.
+- **Search by radius** — centre on a coordinate and keep only what's within range: `--near "27.72,85.32" --radius 2km`. Each lead gets a `distanceKm`, sorted nearest-first.
 - **Accumulate a master list** — `--append` merges each run into your existing file and de-duplicates, so daily runs build one clean database.
 - **Rich enrichment** — visit each website to pull an **email** and links for **Facebook, Instagram, WhatsApp, LinkedIn, X, YouTube, TikTok and Telegram** — a few sites in parallel.
 - **Verified emails** — `--verify-emails` checks each address's domain has **MX records** (no message sent) and tags it `valid`/`no-mx`; `--has-valid-email` keeps only deliverable ones.
@@ -42,7 +43,9 @@ npx lacspace-leads [type] [options]
 | `--city <text>` | City, e.g. `Kathmandu`. Comma-separate for several. |
 | `--area <text>` | Area / neighbourhood, e.g. `Baneshwor`. Comma-separate to **sweep a whole city**. |
 | `-q, --query <text>` | Raw query, used verbatim (overrides city/area/type) |
-| `--fields <list>` | Columns: `name,category,rating,reviews,priceLevel,address,phone,website,email,facebook,instagram,whatsapp,linkedin,twitter,youtube,tiktok,telegram,emailStatus,plusCode,latitude,longitude,hours,mapsUrl` |
+| `--near <lat,lng>` | Centre the search on a coordinate (radius search) |
+| `--radius <dist>` | Keep only leads within this of `--near`, e.g. `2km`, `500m`, `1mi` |
+| `--fields <list>` | Columns: `name,category,rating,reviews,priceLevel,address,phone,website,email,facebook,instagram,whatsapp,linkedin,twitter,youtube,tiktok,telegram,emailStatus,plusCode,latitude,longitude,distanceKm,hours,mapsUrl` |
 | `--preset <name>` | Field bundle: `minimal` · `outreach` · `contact` · `geo` · `full` · `everything` |
 | `-f, --format <fmt>` | `json` · `ndjson` · `csv` · `xlsx` (default `json`) |
 | `-o, --out <file>` | Output file, or `-` for **stdout** (default: a slug + date) |
@@ -51,8 +54,8 @@ npx lacspace-leads [type] [options]
 | `-n, --limit <n>` | Max listings **per search** (default `60`) |
 | `--total <n>` | Cap the merged result when sweeping several searches |
 | `--no-details` | Skip opening each listing — names + Maps URLs only, much faster |
-| `--sort <key>` | `rating` · `reviews` · `name` · `priceLevel` (missing values last) |
-| `--desc` / `--asc` | Sort direction (default: `desc` for numbers, `asc` for name) |
+| `--sort <key>` | `rating` · `reviews` · `name` · `priceLevel` · `distance` (missing values last) |
+| `--desc` / `--asc` | Sort direction (default: `desc` for quality keys, `asc` for name/distance) |
 | `--delay <ms>` | Pause between listings (default `700`) |
 | `--jitter` | Randomise the delay ±40% (more human) |
 | `--retries <n>` | Retry a listing that fails to open (default `1`) |
@@ -108,6 +111,17 @@ npx lacspace-leads "coffee shop" \
 npx lacspace-leads --type "gym,fitness studio" --city Pokhara --total 100 -f csv
 ```
 
+## Search by radius
+
+Centre the search on a coordinate and keep only what's within range — precise catchment-area targeting for delivery zones, field sales or store-radius research:
+
+```bash
+# Restaurants within 2 km of a point, nearest first, with a distance column
+npx lacspace-leads restaurants --near "27.7172,85.3240" --radius 2km -f csv
+```
+
+Every kept lead gains a `distanceKm` column and results are sorted **nearest-first** by default (override with `--sort`). `--radius` accepts `km`, `m` or `mi` (a bare number is metres); omit it to just centre the search without a hard cutoff. Under the hood it points Google Maps at the coordinate, then filters by real great-circle (haversine) distance.
+
 ## Field presets
 
 Skip spelling out `--fields` with a ready-made bundle:
@@ -140,29 +154,90 @@ npx lacspace-leads cafes --city Kathmandu --area "Thamel,Baneshwor,Patan" \
 
 `--verify-emails` does a DNS **MX lookup** on each email's domain (no message is sent) and adds an `emailStatus` column of `valid` · `no-mx` · `invalid-format`. `--append` reads the existing file back, merges, and de-duplicates with the **`smart`** key (website → phone → name) so even website-less businesses don't pile up on re-runs.
 
-## Convert anything (JSON ↔ CSV ↔ Excel)
+## Convert your leads to any format
 
-A general converter is built in — it works on any tabular file, not just leads:
+Collected leads as JSON and now need them in Excel? A general converter is built in — it reads and writes **JSON · NDJSON · CSV · Excel** in any direction, and works on *any* tabular file, not just leads:
 
 ```bash
-npx lacspace-leads convert leads.json -f xlsx        # JSON → Excel
-npx lacspace-leads convert data.csv  -o data.json    # CSV → JSON
-npx lacspace-leads convert sheet.xlsx -f csv         # Excel → CSV
+npx lacspace-leads convert leads.json  -f xlsx          # JSON  → Excel
+npx lacspace-leads convert leads.json  -o leads.csv     # JSON  → CSV   (format from the -o extension)
+npx lacspace-leads convert data.csv    -o data.json     # CSV   → JSON
+npx lacspace-leads convert sheet.xlsx  -f csv           # Excel → CSV
+npx lacspace-leads convert leads.ndjson -f xlsx         # NDJSON → Excel
+npx lacspace-leads convert big.csv     -f ndjson        # CSV → NDJSON (stream-friendly)
+```
+
+The output format comes from `-f` (or is inferred from the `-o` filename's extension); if you give neither, it defaults to JSON. Use `--sheet "My Leads"` to name the Excel tab.
+
+**What converts to what** — every combination works, both ways:
+
+| From \ To | JSON | NDJSON | CSV | Excel |
+| --- | :---: | :---: | :---: | :---: |
+| **JSON** | – | ✓ | ✓ | ✓ |
+| **NDJSON** | ✓ | – | ✓ | ✓ |
+| **CSV** | ✓ | ✓ | – | ✓ |
+| **Excel** | ✓ | ✓ | ✓ | – |
+
+**Sample.** `leads.json` in:
+
+```json
+[
+  { "name": "Himalayan Java", "phone": "+9779801234567", "rating": 4.6, "website": "https://himalayanjava.com" },
+  { "name": "Cafe Soma", "phone": "+9779807654321", "rating": 4.4 }
+]
+```
+
+`npx lacspace-leads convert leads.json -o leads.csv` → `leads.csv` out (missing cells become blank; `+` is escaped so spreadsheets don't treat it as a formula):
+
+```csv
+name,phone,rating,website
+Himalayan Java,'+9779801234567,4.6,https://himalayanjava.com
+Cafe Soma,'+9779807654321,4.4,
 ```
 
-Programmatically: `convertFile(input, { format, out, sheetName })`, or `readRows(file)` + `serializeRows(rows, format)`.
+**In code** — convert a file, or turn any `Lead[]` into a downloadable buffer:
+
+```ts
+import { convertFile, readRows, serializeRows, serialize } from "lacspace-leads";
 
-### Examples
+// 1. Convert a file on disk (returns { out, format, count }).
+await convertFile("leads.json", { format: "xlsx", sheetName: "Prospects" });
+
+// 2. Read rows from any format, transform, write to another.
+const rows = await readRows("leads.csv");                 // → array of objects
+const filtered = rows.filter((r) => Number(r.Rating) >= 4.5);
+const { data, binary } = serializeRows(filtered, "xlsx"); // → bytes for xlsx
+// (write `data` yourself, or in a server route send it as a download)
+
+// 3. Serialize Lead[] straight from a search — pick the columns and order.
+const { data: csv } = serialize(leads, "csv", ["name", "phone", "email"]);
+```
+
+## Recipes
 
 ```bash
 # Excel of restaurants in a specific area
 npx lacspace-leads restaurants --city Kathmandu --area Baneshwor -f xlsx
 
-# Just the essentials for outreach, as CSV
-npx lacspace-leads --type "dental clinic" --city Pokhara --fields name,phone,website -f csv -n 40
+# Outreach list: name/phone/email/website/address, MX-verified, deliverable only
+npx lacspace-leads "dental clinic" --city Pokhara --preset outreach \
+  --verify-emails --has-valid-email --country NP -f csv
+
+# Cover a whole city, sorted best-reviewed first, into one Excel file
+npx lacspace-leads cafes --city Kathmandu --area "Thamel,Baneshwor,Patan" \
+  --sort reviews --desc -f xlsx
+
+# Everything within 1.5 km of a point, nearest first
+npx lacspace-leads salons --near "27.7172,85.3240" --radius 1.5km -f csv
+
+# Build a master list you top up daily (accumulate + dedupe)
+npx lacspace-leads gyms --city Lalitpur -o gyms-master.xlsx --append
 
-# Fast name + URL sweep, no per-listing opening
+# Fast name + Maps-URL sweep, no per-listing opening
 npx lacspace-leads gyms --city Lalitpur --no-details -n 100
+
+# Pipe straight into jq (JSON on stdout, logs on stderr)
+npx lacspace-leads bakeries --city Pokhara -f json -o - -y | jq '.[].phone'
 ```
 
 ## Library
@@ -213,6 +288,7 @@ const leads = await searchLeadsBatch(
 | `toRows(leads, fields?)` | Header-keyed rows, for your own exporter. |
 | `enrichContacts(website)` / `extractEmails` / `extractSocials` | Website enrichment, on tap. |
 | `cleanWebsite` / `normalizePhone` / `sortLeads` | Pure data-cleaning helpers (unit-tested). |
+| `haversineMeters` / `parseLatLngPair` / `parseDistance` | Pure geo helpers for radius search. |
 | `filterLeads` / `dedupeLeads` | Pure post-processing over any `Lead[]`. |
 | `expandQueries` / `resolvePreset` / `FIELD_PRESETS` | Batch expansion + field presets. |
 | `composeQuery` / `mapsSearchUrl` / `normalizeFields` / `defaultFilename` | Query + helper utilities. |

package/dist/cli.js

@@ -32,9 +32,11 @@ var ALL_FIELDS = [
   "plusCode",
   "latitude",
   "longitude",
+  "distanceKm",
   "hours",
   "mapsUrl"
 ];
+var DERIVED_FIELDS = ["distanceKm"];
 var ENRICHED_FIELDS = [
   "email",
   "facebook",
@@ -57,11 +59,13 @@ var FIELD_PRESETS = {
   /** Map/geo columns for plotting. */
   geo: ["name", "address", "latitude", "longitude", "plusCode", "mapsUrl"],
   /** Everything Maps shows, no website enrichment. */
-  full: ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f)),
+  full: ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f) && !DERIVED_FIELDS.includes(f)),
   /** Every field, including enriched ones. */
   everything: [...ALL_FIELDS]
 };
-var DEFAULT_FIELDS = ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f));
+var DEFAULT_FIELDS = ALL_FIELDS.filter(
+  (f) => !ENRICHED_FIELDS.includes(f) && !DERIVED_FIELDS.includes(f)
+);
 
 // src/query.ts
 function composeQuery(opts) {
@@ -75,7 +79,9 @@ function mapsSearchUrl(query, opts = {}) {
   const hl = (opts.hl ?? "en").split("-")[0] || "en";
   const params = new URLSearchParams({ hl });
   if (opts.gl) params.set("gl", opts.gl.toLowerCase());
-  return `https://www.google.com/maps/search/${encodeURIComponent(query)}?${params.toString()}`;
+  const base = `https://www.google.com/maps/search/${encodeURIComponent(query)}`;
+  const at = opts.center ? `/@${opts.center.lat},${opts.center.lng},${Math.round(opts.center.zoom ?? 14)}z` : "";
+  return `${base}${at}?${params.toString()}`;
 }
 function expandQueries(opts) {
   if (opts.query && opts.query.trim()) return [{ query: opts.query.trim() }];
@@ -375,12 +381,14 @@ function plausible(digits) {
   return digits.length >= 8 && digits.length <= 15;
 }
 var priceRank = (p) => p ? p.replace(/[^$€£₹¥₩]/g, "").length : 0;
+var ASC_BY_DEFAULT = /* @__PURE__ */ new Set(["name", "distance"]);
 function sortLeads(leads, by, dir) {
   if (!by) return [...leads];
-  const desc = dir ? dir === "desc" : by !== "name";
+  const desc = dir ? dir === "desc" : !ASC_BY_DEFAULT.has(by);
   const val = (l) => {
     if (by === "name") return l.name?.toLowerCase();
     if (by === "priceLevel") return l.priceLevel ? priceRank(l.priceLevel) : void 0;
+    if (by === "distance") return l.distanceKm;
     return l[by];
   };
   return [...leads].map((lead, i) => ({ lead, i })).sort((a, b) => {
@@ -448,6 +456,43 @@ async function verifyEmails(leads, opts = {}) {
   return leads;
 }
 
+// src/geo.ts
+var R_EARTH_M = 63710088e-1;
+var toRad = (deg) => deg * Math.PI / 180;
+function haversineMeters(a, b) {
+  const dLat = toRad(b.lat - a.lat);
+  const dLng = toRad(b.lng - a.lng);
+  const lat1 = toRad(a.lat);
+  const lat2 = toRad(b.lat);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+  return 2 * R_EARTH_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+function parseLatLngPair(input) {
+  if (!input) return void 0;
+  const m = input.replace(/^@/, "").match(/(-?\d+(?:\.\d+)?)\s*[, ]\s*(-?\d+(?:\.\d+)?)/);
+  if (!m) return void 0;
+  const lat = parseFloat(m[1]);
+  const lng = parseFloat(m[2]);
+  if (!Number.isFinite(lat) || !Number.isFinite(lng)) return void 0;
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) return void 0;
+  return { lat, lng };
+}
+function parseDistance(input) {
+  if (!input) return void 0;
+  const m = input.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(km|m|mi|mile|miles|meters?|metres?)?$/);
+  if (!m) return void 0;
+  const value = parseFloat(m[1]);
+  if (!Number.isFinite(value) || value <= 0) return void 0;
+  const unit = m[2] ?? "m";
+  const metres = unit === "km" ? value * 1e3 : unit.startsWith("mi") ? value * 1609.344 : value;
+  return metres;
+}
+function zoomForRadius(radiusM, lat = 0) {
+  const mpp = 2 * Math.max(50, radiusM) / 600;
+  const zoom = Math.log2(156543.03392 * Math.cos(toRad(lat)) / mpp);
+  return Math.max(3, Math.min(19, Math.round(zoom)));
+}
+
 // src/export.ts
 import { stringify as csvStringify } from "@lacspace/csv";
 import { jsonToXlsx } from "@lacspace/xlsx";
@@ -473,6 +518,7 @@ var HEADERS = {
   plusCode: "Plus Code",
   latitude: "Latitude",
   longitude: "Longitude",
+  distanceKm: "Distance (km)",
   hours: "Hours",
   mapsUrl: "Maps URL"
 };
@@ -533,7 +579,7 @@ var FIELD_BY_KEY = (() => {
   }
   return m;
 })();
-var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude"]);
+var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude", "distanceKm"]);
 function rowsToLeads(rows) {
   return rows.map((row) => {
     const lead = {};
@@ -744,8 +790,13 @@ async function scrapeLeads(opts) {
   const pauseMs = () => opts.jitter ? Math.round(delayMs * (0.6 + Math.random() * 0.8)) : delayMs;
   const wantVerify = Boolean(opts.verifyEmails) || Boolean(opts.filters?.hasValidEmail) || fields.has("emailStatus");
   const wantEnrich = Boolean(opts.enrich) || ENRICHED_FIELDS.some((f) => fields.has(f)) || Boolean(opts.filters?.hasEmail) || wantVerify;
+  const near = opts.near;
   const collect = new Set(fields);
   if (wantEnrich) collect.add("website");
+  if (near) {
+    collect.add("latitude");
+    collect.add("longitude");
+  }
   const detailOnly = ["name", "mapsUrl"];
   const wantDetails = (opts.details ?? true) && ([...collect].some((f) => !detailOnly.includes(f)) || wantEnrich);
   onProgress?.(`searching Google Maps for "${query}"\u2026`);
@@ -759,6 +810,7 @@ async function scrapeLeads(opts) {
     const page = await context.newPage();
     const urlOpts = { hl: locale };
     if (opts.region) urlOpts.gl = opts.region;
+    if (near) urlOpts.center = { lat: near.lat, lng: near.lng, zoom: zoomForRadius(opts.radiusM ?? 2e3, near.lat) };
     await page.goto(mapsSearchUrl(query, urlOpts), { waitUntil: "domcontentloaded", timeout: 45e3 });
     await dismissConsent(page);
     await loadResults(page, limit, delayMs, onProgress, signal);
@@ -836,6 +888,19 @@ async function scrapeLeads(opts) {
         if (lead.website) lead.website = cleanWebsite(lead.website);
       }
     }
+    if (near) {
+      for (const lead of leads) {
+        if (typeof lead.latitude === "number" && typeof lead.longitude === "number") {
+          const m = haversineMeters(near, { lat: lead.latitude, lng: lead.longitude });
+          lead.distanceKm = Math.round(m / 1e3 * 100) / 100;
+        }
+      }
+      if (opts.radiusM !== void 0) {
+        const r = opts.radiusM;
+        leads = leads.filter((l) => l.distanceKm !== void 0 && l.distanceKm * 1e3 <= r);
+        onProgress?.(`within ${Math.round(r)} m: ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
+      }
+    }
     leads = dedupeLeads(leads, opts.dedupe ?? "website");
     if (wantEnrich) {
       const socialFields = ENRICHED_FIELDS.filter((f) => f !== "email");
@@ -876,6 +941,16 @@ async function scrapeLeads(opts) {
     if (opts.filters) leads = filterLeads(leads, opts.filters);
     if (opts.sort) leads = sortLeads(leads, opts.sort, opts.sortDir);
     if (wantVerify && !fields.has("emailStatus")) for (const l of leads) delete l.emailStatus;
+    if (near) {
+      const keepLat = fields.has("latitude");
+      const keepLng = fields.has("longitude");
+      const keepDist = fields.has("distanceKm");
+      for (const l of leads) {
+        if (!keepLat) delete l.latitude;
+        if (!keepLng) delete l.longitude;
+        if (!keepDist) delete l.distanceKm;
+      }
+    }
     onProgress?.(`collected ${leads.length} lead${leads.length === 1 ? "" : "s"}.`);
     return leads;
   } finally {
@@ -946,9 +1021,10 @@ import { jsonToXlsx as jsonToXlsx2, xlsxToJson } from "@lacspace/xlsx";
 function detectFormat(file) {
   const ext = extname(file).toLowerCase().replace(/^\./, "");
   if (ext === "json") return "json";
+  if (ext === "ndjson" || ext === "jsonl") return "ndjson";
   if (ext === "csv" || ext === "tsv") return "csv";
   if (ext === "xlsx" || ext === "xls") return "xlsx";
-  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|csv|xlsx).`);
+  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|ndjson|csv|xlsx).`);
 }
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
@@ -960,6 +1036,15 @@ async function readRows(file, format) {
   if (fmt === "csv") {
     return csvParse(text, { header: true });
   }
+  if (fmt === "ndjson") {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        throw new Error(`Invalid NDJSON on line ${i + 1}.`);
+      }
+    });
+  }
   const parsed = JSON.parse(text);
   if (Array.isArray(parsed)) return parsed;
   if (parsed && typeof parsed === "object") return [parsed];
@@ -982,6 +1067,9 @@ function serializeRows(rows, format, opts = {}) {
   if (format === "json") {
     return { data: JSON.stringify(rows, null, 2), binary: false };
   }
+  if (format === "ndjson") {
+    return { data: rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""), binary: false };
+  }
   const cols = columnsOf(rows);
   const flat = rows.map((row) => {
     const out = {};
@@ -1054,6 +1142,8 @@ function parseArgs(list) {
     else if (arg === "--area" || arg === "--areas") a.area = next();
     else if (arg === "-t" || arg === "--type" || arg === "--types") a.type = next();
     else if (arg === "-q" || arg === "--query") a.query = next();
+    else if (arg === "--near") a.near = next();
+    else if (arg === "--radius") a.radius = next();
     else if (arg === "--fields") a.fields = next();
     else if (arg === "--preset") a.preset = next();
     else if (arg === "-f" || arg === "--format") a.format = next();
@@ -1109,7 +1199,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 free loca
 
 ${c("bold", "Usage")}
   npx lacspace-leads [type] [options]
-  npx lacspace-leads convert <file> [-f json|csv|xlsx] [-o out]
+  npx lacspace-leads convert <file> [-f json|ndjson|csv|xlsx] [-o out]
 
 ${c("bold", "Search options")}
   -t, --type <text>     Business type/keyword. Comma-separate for several,
@@ -1118,6 +1208,8 @@ ${c("bold", "Search options")}
       --area <text>     Area/neighbourhood. Comma-separate to sweep a whole
                         city, e.g. --area "Baneshwor,Thamel,Patan"
   -q, --query <text>    Raw query verbatim (overrides city/area/type)
+      --near <lat,lng>  Centre the search on a coordinate (radius search)
+      --radius <dist>   Keep only leads within this of --near, e.g. 2km, 500m, 1mi
       --fields <list>   Columns: ${ALL_FIELDS.join(",")}
       --preset <name>   Field bundle: ${Object.keys(FIELD_PRESETS).join(" | ")}
   -n, --limit <n>       Max listings per search   (default 60)
@@ -1146,8 +1238,8 @@ ${c("bold", "Filters & order")}
       --has-valid-email Keep only leads with an MX-verified email (implies --verify-emails)
       --dedupe <key>    website | phone | name | smart | none   (default website;
                         --append uses smart: website\u2192phone\u2192name)
-      --sort <key>      rating | reviews | name | priceLevel
-      --desc / --asc    Sort direction
+      --sort <key>      rating | reviews | name | priceLevel | distance
+      --desc / --asc    Sort direction (distance defaults nearest-first)
 
 ${c("bold", "Output")}
   -f, --format <fmt>    json | ndjson | csv | xlsx      (default json)
@@ -1175,6 +1267,7 @@ ${c("bold", "Examples")}
   npx lacspace-leads salons --city Pokhara --preset outreach --country NP -f csv -o -
   npx lacspace-leads dentists --city Pokhara --verify-emails --has-valid-email -f csv
   npx lacspace-leads cafes --city Kathmandu -o master.csv --append   # accumulate daily
+  npx lacspace-leads restaurants --near "27.7172,85.3240" --radius 2km -f csv
   npx lacspace-leads convert leads.json -f xlsx
 
 ${c("dim", "Please scrape responsibly: keep volumes small, respect Google's Terms of")}
@@ -1197,6 +1290,13 @@ async function runConvert(rest) {
     exit(1);
     return;
   }
+  if ((rest.includes("-f") || rest.includes("--format")) && !OUTPUT_FORMATS.includes(a.format)) {
+    log(c("red", `
+\u2717 Unknown format "${a.format}". Use: ${OUTPUT_FORMATS.join(", ")}.
+`));
+    exit(1);
+    return;
+  }
   log(`
 ${c("bold", c("magenta", "\u25C6 lacspace-leads convert"))}
 `);
@@ -1261,6 +1361,26 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
     exit(1);
     return;
   }
+  const nearPoint = args.near ? parseLatLngPair(args.near) : void 0;
+  if (args.near && !nearPoint) {
+    log(c("red", `
+\u2717 --near must be "lat,lng", e.g. --near "27.7172,85.3240".`));
+    exit(1);
+    return;
+  }
+  const radiusM = args.radius ? parseDistance(args.radius) : void 0;
+  if (args.radius && radiusM === void 0) {
+    log(c("red", `
+\u2717 --radius must be a distance like 2km, 500m or 1mi.`));
+    exit(1);
+    return;
+  }
+  if (args.radius && !nearPoint) {
+    log(c("red", `
+\u2717 --radius needs a centre \u2014 add --near "lat,lng".`));
+    exit(1);
+    return;
+  }
   const base = args.fields ? normalizeFields(args.fields) : resolvePreset(args.preset) ?? [...DEFAULT_FIELDS];
   const wanted = new Set(base);
   if (args.emails) wanted.add("email");
@@ -1269,6 +1389,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
     wanted.add("email");
     wanted.add("emailStatus");
   }
+  if (nearPoint) wanted.add("distanceKm");
   const fields = ALL_FIELDS.filter((f) => wanted.has(f));
   const toStdout = args.out === "-";
   const out = toStdout ? "-" : resolve2(args.out ?? defaultFilename(query, args.format));
@@ -1301,7 +1422,9 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
   if (args.emails || args.socials) log(`  ${c("dim", "enrich")}  ${[args.emails && "emails", args.socials && "socials"].filter(Boolean).join(" + ")} ${c("dim", `(${args.concurrency ?? 3}\xD7 parallel, visits each website)`)}`);
   if (args.verifyEmails) log(`  ${c("dim", "verify")}  email domains (MX lookup)`);
   if (hasFilters) log(`  ${c("dim", "filters")} ${Object.entries(filters).map(([k, v]) => `${k}=${v}`).join(", ")}`);
+  if (nearPoint) log(`  ${c("dim", "near")}    ${nearPoint.lat},${nearPoint.lng}${radiusM !== void 0 ? c("dim", ` (within ${args.radius})`) : c("dim", " (centred, no radius filter)")}`);
   if (args.sort) log(`  ${c("dim", "sort")}    ${args.sort} ${args.desc === false ? "asc" : "desc"}`);
+  else if (nearPoint) log(`  ${c("dim", "sort")}    distance (nearest first)`);
   if (args.country) log(`  ${c("dim", "phones")}  E.164 for ${args.country}`);
   if (args.proxy) log(`  ${c("dim", "proxy")}   ${args.proxy.replace(/\/\/[^@]+@/, "//***@")}`);
   log(`  ${c("dim", "limit")}   ${args.limit}${isBatch ? "/search" : ""}${args.total ? ` (cap ${args.total})` : ""}   ${c("dim", "format")} ${args.format}   ${c("dim", "\u2192")} ${toStdout ? "stdout" : out}${args.append ? c("dim", " (append)") : ""}`);
@@ -1338,7 +1461,10 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   };
   if (hasFilters) opts.filters = filters;
   if (args.dedupe) opts.dedupe = args.dedupe;
+  if (nearPoint) opts.near = { lat: nearPoint.lat, lng: nearPoint.lng };
+  if (radiusM !== void 0) opts.radiusM = radiusM;
   if (args.sort) opts.sort = args.sort;
+  else if (nearPoint) opts.sort = "distance";
   if (args.desc !== void 0) opts.sortDir = args.desc ? "desc" : "asc";
   if (args.country) opts.country = args.country;
   if (args.locale) opts.locale = args.locale;

package/dist/lib.cjs

@@ -42,10 +42,13 @@ __export(lib_exports, {
   extractEmails: () => extractEmails,
   extractSocials: () => extractSocials,
   filterLeads: () => filterLeads,
+  haversineMeters: () => haversineMeters,
   mapsSearchUrl: () => mapsSearchUrl,
   normalizeFields: () => normalizeFields,
   normalizePhone: () => normalizePhone,
+  parseDistance: () => parseDistance,
   parseLatLng: () => parseLatLng,
+  parseLatLngPair: () => parseLatLngPair,
   parseRating: () => parseRating,
   parseReviewCount: () => parseReviewCount,
   readRows: () => readRows,
@@ -61,7 +64,8 @@ __export(lib_exports, {
   sortLeads: () => sortLeads,
   toRows: () => toRows,
   verifyEmail: () => verifyEmail,
-  verifyEmails: () => verifyEmails
+  verifyEmails: () => verifyEmails,
+  zoomForRadius: () => zoomForRadius
 });
 module.exports = __toCommonJS(lib_exports);
 
@@ -91,9 +95,11 @@ var ALL_FIELDS = [
   "plusCode",
   "latitude",
   "longitude",
+  "distanceKm",
   "hours",
   "mapsUrl"
 ];
+var DERIVED_FIELDS = ["distanceKm"];
 var ENRICHED_FIELDS = [
   "email",
   "facebook",
@@ -116,11 +122,13 @@ var FIELD_PRESETS = {
   /** Map/geo columns for plotting. */
   geo: ["name", "address", "latitude", "longitude", "plusCode", "mapsUrl"],
   /** Everything Maps shows, no website enrichment. */
-  full: ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f)),
+  full: ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f) && !DERIVED_FIELDS.includes(f)),
   /** Every field, including enriched ones. */
   everything: [...ALL_FIELDS]
 };
-var DEFAULT_FIELDS = ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f));
+var DEFAULT_FIELDS = ALL_FIELDS.filter(
+  (f) => !ENRICHED_FIELDS.includes(f) && !DERIVED_FIELDS.includes(f)
+);
 
 // src/query.ts
 function composeQuery(opts) {
@@ -134,7 +142,9 @@ function mapsSearchUrl(query, opts = {}) {
   const hl = (opts.hl ?? "en").split("-")[0] || "en";
   const params = new URLSearchParams({ hl });
   if (opts.gl) params.set("gl", opts.gl.toLowerCase());
-  return `https://www.google.com/maps/search/${encodeURIComponent(query)}?${params.toString()}`;
+  const base = `https://www.google.com/maps/search/${encodeURIComponent(query)}`;
+  const at = opts.center ? `/@${opts.center.lat},${opts.center.lng},${Math.round(opts.center.zoom ?? 14)}z` : "";
+  return `${base}${at}?${params.toString()}`;
 }
 function expandQueries(opts) {
   if (opts.query && opts.query.trim()) return [{ query: opts.query.trim() }];
@@ -434,12 +444,14 @@ function plausible(digits) {
   return digits.length >= 8 && digits.length <= 15;
 }
 var priceRank = (p) => p ? p.replace(/[^$€£₹¥₩]/g, "").length : 0;
+var ASC_BY_DEFAULT = /* @__PURE__ */ new Set(["name", "distance"]);
 function sortLeads(leads, by, dir) {
   if (!by) return [...leads];
-  const desc = dir ? dir === "desc" : by !== "name";
+  const desc = dir ? dir === "desc" : !ASC_BY_DEFAULT.has(by);
   const val = (l) => {
     if (by === "name") return l.name?.toLowerCase();
     if (by === "priceLevel") return l.priceLevel ? priceRank(l.priceLevel) : void 0;
+    if (by === "distance") return l.distanceKm;
     return l[by];
   };
   return [...leads].map((lead, i) => ({ lead, i })).sort((a, b) => {
@@ -507,6 +519,43 @@ async function verifyEmails(leads, opts = {}) {
   return leads;
 }
 
+// src/geo.ts
+var R_EARTH_M = 63710088e-1;
+var toRad = (deg) => deg * Math.PI / 180;
+function haversineMeters(a, b) {
+  const dLat = toRad(b.lat - a.lat);
+  const dLng = toRad(b.lng - a.lng);
+  const lat1 = toRad(a.lat);
+  const lat2 = toRad(b.lat);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+  return 2 * R_EARTH_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+function parseLatLngPair(input) {
+  if (!input) return void 0;
+  const m = input.replace(/^@/, "").match(/(-?\d+(?:\.\d+)?)\s*[, ]\s*(-?\d+(?:\.\d+)?)/);
+  if (!m) return void 0;
+  const lat = parseFloat(m[1]);
+  const lng = parseFloat(m[2]);
+  if (!Number.isFinite(lat) || !Number.isFinite(lng)) return void 0;
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) return void 0;
+  return { lat, lng };
+}
+function parseDistance(input) {
+  if (!input) return void 0;
+  const m = input.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(km|m|mi|mile|miles|meters?|metres?)?$/);
+  if (!m) return void 0;
+  const value = parseFloat(m[1]);
+  if (!Number.isFinite(value) || value <= 0) return void 0;
+  const unit = m[2] ?? "m";
+  const metres = unit === "km" ? value * 1e3 : unit.startsWith("mi") ? value * 1609.344 : value;
+  return metres;
+}
+function zoomForRadius(radiusM, lat = 0) {
+  const mpp = 2 * Math.max(50, radiusM) / 600;
+  const zoom = Math.log2(156543.03392 * Math.cos(toRad(lat)) / mpp);
+  return Math.max(3, Math.min(19, Math.round(zoom)));
+}
+
 // src/export.ts
 var import_csv = require("@lacspace/csv");
 var import_xlsx = require("@lacspace/xlsx");
@@ -532,6 +581,7 @@ var HEADERS = {
   plusCode: "Plus Code",
   latitude: "Latitude",
   longitude: "Longitude",
+  distanceKm: "Distance (km)",
   hours: "Hours",
   mapsUrl: "Maps URL"
 };
@@ -592,7 +642,7 @@ var FIELD_BY_KEY = (() => {
   }
   return m;
 })();
-var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude"]);
+var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude", "distanceKm"]);
 function rowsToLeads(rows) {
   return rows.map((row) => {
     const lead = {};
@@ -803,8 +853,13 @@ async function scrapeLeads(opts) {
   const pauseMs = () => opts.jitter ? Math.round(delayMs * (0.6 + Math.random() * 0.8)) : delayMs;
   const wantVerify = Boolean(opts.verifyEmails) || Boolean(opts.filters?.hasValidEmail) || fields.has("emailStatus");
   const wantEnrich = Boolean(opts.enrich) || ENRICHED_FIELDS.some((f) => fields.has(f)) || Boolean(opts.filters?.hasEmail) || wantVerify;
+  const near = opts.near;
   const collect = new Set(fields);
   if (wantEnrich) collect.add("website");
+  if (near) {
+    collect.add("latitude");
+    collect.add("longitude");
+  }
   const detailOnly = ["name", "mapsUrl"];
   const wantDetails = (opts.details ?? true) && ([...collect].some((f) => !detailOnly.includes(f)) || wantEnrich);
   onProgress?.(`searching Google Maps for "${query}"\u2026`);
@@ -818,6 +873,7 @@ async function scrapeLeads(opts) {
     const page = await context.newPage();
     const urlOpts = { hl: locale };
     if (opts.region) urlOpts.gl = opts.region;
+    if (near) urlOpts.center = { lat: near.lat, lng: near.lng, zoom: zoomForRadius(opts.radiusM ?? 2e3, near.lat) };
     await page.goto(mapsSearchUrl(query, urlOpts), { waitUntil: "domcontentloaded", timeout: 45e3 });
     await dismissConsent(page);
     await loadResults(page, limit, delayMs, onProgress, signal);
@@ -895,6 +951,19 @@ async function scrapeLeads(opts) {
         if (lead.website) lead.website = cleanWebsite(lead.website);
       }
     }
+    if (near) {
+      for (const lead of leads) {
+        if (typeof lead.latitude === "number" && typeof lead.longitude === "number") {
+          const m = haversineMeters(near, { lat: lead.latitude, lng: lead.longitude });
+          lead.distanceKm = Math.round(m / 1e3 * 100) / 100;
+        }
+      }
+      if (opts.radiusM !== void 0) {
+        const r = opts.radiusM;
+        leads = leads.filter((l) => l.distanceKm !== void 0 && l.distanceKm * 1e3 <= r);
+        onProgress?.(`within ${Math.round(r)} m: ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
+      }
+    }
     leads = dedupeLeads(leads, opts.dedupe ?? "website");
     if (wantEnrich) {
       const socialFields = ENRICHED_FIELDS.filter((f) => f !== "email");
@@ -935,6 +1004,16 @@ async function scrapeLeads(opts) {
     if (opts.filters) leads = filterLeads(leads, opts.filters);
     if (opts.sort) leads = sortLeads(leads, opts.sort, opts.sortDir);
     if (wantVerify && !fields.has("emailStatus")) for (const l of leads) delete l.emailStatus;
+    if (near) {
+      const keepLat = fields.has("latitude");
+      const keepLng = fields.has("longitude");
+      const keepDist = fields.has("distanceKm");
+      for (const l of leads) {
+        if (!keepLat) delete l.latitude;
+        if (!keepLng) delete l.longitude;
+        if (!keepDist) delete l.distanceKm;
+      }
+    }
     onProgress?.(`collected ${leads.length} lead${leads.length === 1 ? "" : "s"}.`);
     return leads;
   } finally {
@@ -1019,9 +1098,10 @@ var import_xlsx2 = require("@lacspace/xlsx");
 function detectFormat(file) {
   const ext = (0, import_node_path.extname)(file).toLowerCase().replace(/^\./, "");
   if (ext === "json") return "json";
+  if (ext === "ndjson" || ext === "jsonl") return "ndjson";
   if (ext === "csv" || ext === "tsv") return "csv";
   if (ext === "xlsx" || ext === "xls") return "xlsx";
-  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|csv|xlsx).`);
+  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|ndjson|csv|xlsx).`);
 }
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
@@ -1033,6 +1113,15 @@ async function readRows(file, format) {
   if (fmt === "csv") {
     return (0, import_csv2.parse)(text, { header: true });
   }
+  if (fmt === "ndjson") {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        throw new Error(`Invalid NDJSON on line ${i + 1}.`);
+      }
+    });
+  }
   const parsed = JSON.parse(text);
   if (Array.isArray(parsed)) return parsed;
   if (parsed && typeof parsed === "object") return [parsed];
@@ -1055,6 +1144,9 @@ function serializeRows(rows, format, opts = {}) {
   if (format === "json") {
     return { data: JSON.stringify(rows, null, 2), binary: false };
   }
+  if (format === "ndjson") {
+    return { data: rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""), binary: false };
+  }
   const cols = columnsOf(rows);
   const flat = rows.map((row) => {
     const out = {};
@@ -1108,10 +1200,13 @@ async function convertFile(input, opts = {}) {
   extractEmails,
   extractSocials,
   filterLeads,
+  haversineMeters,
   mapsSearchUrl,
   normalizeFields,
   normalizePhone,
+  parseDistance,
   parseLatLng,
+  parseLatLngPair,
   parseRating,
   parseReviewCount,
   readRows,
@@ -1127,5 +1222,6 @@ async function convertFile(input, opts = {}) {
   sortLeads,
   toRows,
   verifyEmail,
-  verifyEmails
+  verifyEmails,
+  zoomForRadius
 });

package/dist/lib.d.cts

@@ -1,5 +1,5 @@
 /** The fields a {@link Lead} can carry — request any subset via `fields`. */
-type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "distanceKm" | "hours" | "mapsUrl";
 /** Deliverability verdict for a discovered email (see `verifyEmails`). */
 type EmailStatus = "valid" | "no-mx" | "invalid-format" | "unknown";
 /** Every field, in a sensible column order for exports. */
@@ -53,6 +53,8 @@ interface Lead {
     latitude?: number;
     /** Longitude, parsed from the listing's Maps URL. */
     longitude?: number;
+    /** Distance in km from the `near` point (set only in radius search). */
+    distanceKm?: number;
     /** Opening-hours summary, when shown. */
     hours?: string;
     /** Canonical Google Maps URL for the listing. */
@@ -76,7 +78,7 @@ interface LeadFilters {
 /** Output formats the tool can write. */
 type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
 /** How to sort collected leads before export. */
-type SortKey$1 = "rating" | "reviews" | "name" | "priceLevel";
+type SortKey$1 = "rating" | "reviews" | "name" | "priceLevel" | "distance";
 /** Options for a lead search. */
 interface SearchOptions {
     /** City, e.g. "Kathmandu". */
@@ -87,6 +89,16 @@ interface SearchOptions {
     type: string;
     /** A ready-made query, used verbatim instead of composing city/area/type. */
     query?: string;
+    /**
+     * Centre the search on a coordinate. Results are biased to this point, and —
+     * when `radiusM` is set — filtered to within it. Each lead gets `distanceKm`.
+     */
+    near?: {
+        lat: number;
+        lng: number;
+    };
+    /** Keep only leads within this many metres of `near`. Requires `near`. */
+    radiusM?: number;
     /** Max number of leads to collect. Default 60. */
     limit?: number;
     /** Fields to collect. Default: all of {@link ALL_FIELDS}. */
@@ -290,11 +302,17 @@ declare function composeQuery(opts: {
 }): string;
 /**
  * The Google Maps search URL for a query. `hl` (interface language) keeps the
- * scraped aria-labels predictable; `gl` biases results to a region.
+ * scraped aria-labels predictable; `gl` biases results to a region; `center`
+ * (`{lat,lng,zoom}`) points the map at a location for a radius search.
  */
 declare function mapsSearchUrl(query: string, opts?: {
     hl?: string;
     gl?: string;
+    center?: {
+        lat: number;
+        lng: number;
+        zoom?: number;
+    };
 }): string;
 /**
  * Expand a possibly-multi search request into individual `{type, city, area}`
@@ -359,10 +377,11 @@ declare function callingCode(country?: string): string | undefined;
  */
 declare function normalizePhone(raw?: string, country?: string): string | undefined;
 /** Keys a lead list can be sorted by. */
-type SortKey = "rating" | "reviews" | "name" | "priceLevel";
+type SortKey = "rating" | "reviews" | "name" | "priceLevel" | "distance";
 /**
  * Sort leads by a key, missing values always last. Stable, pure, new array.
- * `dir` defaults to descending for numeric keys and ascending for `name`.
+ * `dir` defaults to descending for numeric quality keys, ascending for `name`
+ * and `distance` (nearest first).
  */
 declare function sortLeads(leads: Lead[], by?: SortKey, dir?: "asc" | "desc"): Lead[];
 
@@ -399,11 +418,39 @@ declare function enrichContacts(website: string, opts?: {
     contactPages?: boolean;
 }): Promise<Contacts>;
 
+/**
+ * Geo helpers for radius search — parse a coordinate/radius, measure distance
+ * (haversine), and pick a Maps zoom that frames a radius. All pure, unit-tested.
+ */
+/** A latitude/longitude point. */
+interface LatLng {
+    lat: number;
+    lng: number;
+}
+/** Great-circle distance between two points, in metres. Pure. */
+declare function haversineMeters(a: LatLng, b: LatLng): number;
+/**
+ * Parse a `"lat,lng"` pair (also accepts a bare `@lat,lng` or whitespace).
+ * Returns `undefined` if it isn't two in-range numbers. Pure.
+ */
+declare function parseLatLngPair(input: string | undefined): LatLng | undefined;
+/**
+ * Parse a distance like `"2km"`, `"500m"`, `"1.5mi"` (or a bare number = metres)
+ * into metres. Returns `undefined` for junk or non-positive values. Pure.
+ */
+declare function parseDistance(input: string | undefined): number | undefined;
+/**
+ * A Google Maps zoom level (integer) that roughly frames a circle of `radiusM`
+ * at a given latitude in the map viewport. Clamped to 3–19. Pure/best-effort —
+ * Maps re-fits results anyway; this just centres the search sensibly.
+ */
+declare function zoomForRadius(radiusM: number, lat?: number): number;
+
 /** An arbitrary tabular row. */
 type DataRow = Record<string, unknown>;
 /** Infer the format from a filename extension. Throws on an unknown extension. */
 declare function detectFormat(file: string): OutputFormat;
-/** Read a JSON / CSV / Excel file into an array of rows. */
+/** Read a JSON / NDJSON / CSV / Excel file into an array of rows. */
 declare function readRows(file: string, format?: OutputFormat): Promise<DataRow[]>;
 /** The union of keys across all rows, in first-seen order — the column set. */
 declare function columnsOf(rows: DataRow[]): string[];
@@ -425,4 +472,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type LatLng, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, haversineMeters, mapsSearchUrl, normalizeFields, normalizePhone, parseDistance, parseLatLng, parseLatLngPair, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails, zoomForRadius };

package/dist/lib.d.ts

@@ -1,5 +1,5 @@
 /** The fields a {@link Lead} can carry — request any subset via `fields`. */
-type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "distanceKm" | "hours" | "mapsUrl";
 /** Deliverability verdict for a discovered email (see `verifyEmails`). */
 type EmailStatus = "valid" | "no-mx" | "invalid-format" | "unknown";
 /** Every field, in a sensible column order for exports. */
@@ -53,6 +53,8 @@ interface Lead {
     latitude?: number;
     /** Longitude, parsed from the listing's Maps URL. */
     longitude?: number;
+    /** Distance in km from the `near` point (set only in radius search). */
+    distanceKm?: number;
     /** Opening-hours summary, when shown. */
     hours?: string;
     /** Canonical Google Maps URL for the listing. */
@@ -76,7 +78,7 @@ interface LeadFilters {
 /** Output formats the tool can write. */
 type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
 /** How to sort collected leads before export. */
-type SortKey$1 = "rating" | "reviews" | "name" | "priceLevel";
+type SortKey$1 = "rating" | "reviews" | "name" | "priceLevel" | "distance";
 /** Options for a lead search. */
 interface SearchOptions {
     /** City, e.g. "Kathmandu". */
@@ -87,6 +89,16 @@ interface SearchOptions {
     type: string;
     /** A ready-made query, used verbatim instead of composing city/area/type. */
     query?: string;
+    /**
+     * Centre the search on a coordinate. Results are biased to this point, and —
+     * when `radiusM` is set — filtered to within it. Each lead gets `distanceKm`.
+     */
+    near?: {
+        lat: number;
+        lng: number;
+    };
+    /** Keep only leads within this many metres of `near`. Requires `near`. */
+    radiusM?: number;
     /** Max number of leads to collect. Default 60. */
     limit?: number;
     /** Fields to collect. Default: all of {@link ALL_FIELDS}. */
@@ -290,11 +302,17 @@ declare function composeQuery(opts: {
 }): string;
 /**
  * The Google Maps search URL for a query. `hl` (interface language) keeps the
- * scraped aria-labels predictable; `gl` biases results to a region.
+ * scraped aria-labels predictable; `gl` biases results to a region; `center`
+ * (`{lat,lng,zoom}`) points the map at a location for a radius search.
  */
 declare function mapsSearchUrl(query: string, opts?: {
     hl?: string;
     gl?: string;
+    center?: {
+        lat: number;
+        lng: number;
+        zoom?: number;
+    };
 }): string;
 /**
  * Expand a possibly-multi search request into individual `{type, city, area}`
@@ -359,10 +377,11 @@ declare function callingCode(country?: string): string | undefined;
  */
 declare function normalizePhone(raw?: string, country?: string): string | undefined;
 /** Keys a lead list can be sorted by. */
-type SortKey = "rating" | "reviews" | "name" | "priceLevel";
+type SortKey = "rating" | "reviews" | "name" | "priceLevel" | "distance";
 /**
  * Sort leads by a key, missing values always last. Stable, pure, new array.
- * `dir` defaults to descending for numeric keys and ascending for `name`.
+ * `dir` defaults to descending for numeric quality keys, ascending for `name`
+ * and `distance` (nearest first).
  */
 declare function sortLeads(leads: Lead[], by?: SortKey, dir?: "asc" | "desc"): Lead[];
 
@@ -399,11 +418,39 @@ declare function enrichContacts(website: string, opts?: {
     contactPages?: boolean;
 }): Promise<Contacts>;
 
+/**
+ * Geo helpers for radius search — parse a coordinate/radius, measure distance
+ * (haversine), and pick a Maps zoom that frames a radius. All pure, unit-tested.
+ */
+/** A latitude/longitude point. */
+interface LatLng {
+    lat: number;
+    lng: number;
+}
+/** Great-circle distance between two points, in metres. Pure. */
+declare function haversineMeters(a: LatLng, b: LatLng): number;
+/**
+ * Parse a `"lat,lng"` pair (also accepts a bare `@lat,lng` or whitespace).
+ * Returns `undefined` if it isn't two in-range numbers. Pure.
+ */
+declare function parseLatLngPair(input: string | undefined): LatLng | undefined;
+/**
+ * Parse a distance like `"2km"`, `"500m"`, `"1.5mi"` (or a bare number = metres)
+ * into metres. Returns `undefined` for junk or non-positive values. Pure.
+ */
+declare function parseDistance(input: string | undefined): number | undefined;
+/**
+ * A Google Maps zoom level (integer) that roughly frames a circle of `radiusM`
+ * at a given latitude in the map viewport. Clamped to 3–19. Pure/best-effort —
+ * Maps re-fits results anyway; this just centres the search sensibly.
+ */
+declare function zoomForRadius(radiusM: number, lat?: number): number;
+
 /** An arbitrary tabular row. */
 type DataRow = Record<string, unknown>;
 /** Infer the format from a filename extension. Throws on an unknown extension. */
 declare function detectFormat(file: string): OutputFormat;
-/** Read a JSON / CSV / Excel file into an array of rows. */
+/** Read a JSON / NDJSON / CSV / Excel file into an array of rows. */
 declare function readRows(file: string, format?: OutputFormat): Promise<DataRow[]>;
 /** The union of keys across all rows, in first-seen order — the column set. */
 declare function columnsOf(rows: DataRow[]): string[];
@@ -425,4 +472,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type LatLng, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, haversineMeters, mapsSearchUrl, normalizeFields, normalizePhone, parseDistance, parseLatLng, parseLatLngPair, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails, zoomForRadius };

package/dist/lib.js

@@ -24,9 +24,11 @@ var ALL_FIELDS = [
   "plusCode",
   "latitude",
   "longitude",
+  "distanceKm",
   "hours",
   "mapsUrl"
 ];
+var DERIVED_FIELDS = ["distanceKm"];
 var ENRICHED_FIELDS = [
   "email",
   "facebook",
@@ -49,11 +51,13 @@ var FIELD_PRESETS = {
   /** Map/geo columns for plotting. */
   geo: ["name", "address", "latitude", "longitude", "plusCode", "mapsUrl"],
   /** Everything Maps shows, no website enrichment. */
-  full: ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f)),
+  full: ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f) && !DERIVED_FIELDS.includes(f)),
   /** Every field, including enriched ones. */
   everything: [...ALL_FIELDS]
 };
-var DEFAULT_FIELDS = ALL_FIELDS.filter((f) => !ENRICHED_FIELDS.includes(f));
+var DEFAULT_FIELDS = ALL_FIELDS.filter(
+  (f) => !ENRICHED_FIELDS.includes(f) && !DERIVED_FIELDS.includes(f)
+);
 
 // src/query.ts
 function composeQuery(opts) {
@@ -67,7 +71,9 @@ function mapsSearchUrl(query, opts = {}) {
   const hl = (opts.hl ?? "en").split("-")[0] || "en";
   const params = new URLSearchParams({ hl });
   if (opts.gl) params.set("gl", opts.gl.toLowerCase());
-  return `https://www.google.com/maps/search/${encodeURIComponent(query)}?${params.toString()}`;
+  const base = `https://www.google.com/maps/search/${encodeURIComponent(query)}`;
+  const at = opts.center ? `/@${opts.center.lat},${opts.center.lng},${Math.round(opts.center.zoom ?? 14)}z` : "";
+  return `${base}${at}?${params.toString()}`;
 }
 function expandQueries(opts) {
   if (opts.query && opts.query.trim()) return [{ query: opts.query.trim() }];
@@ -367,12 +373,14 @@ function plausible(digits) {
   return digits.length >= 8 && digits.length <= 15;
 }
 var priceRank = (p) => p ? p.replace(/[^$€£₹¥₩]/g, "").length : 0;
+var ASC_BY_DEFAULT = /* @__PURE__ */ new Set(["name", "distance"]);
 function sortLeads(leads, by, dir) {
   if (!by) return [...leads];
-  const desc = dir ? dir === "desc" : by !== "name";
+  const desc = dir ? dir === "desc" : !ASC_BY_DEFAULT.has(by);
   const val = (l) => {
     if (by === "name") return l.name?.toLowerCase();
     if (by === "priceLevel") return l.priceLevel ? priceRank(l.priceLevel) : void 0;
+    if (by === "distance") return l.distanceKm;
     return l[by];
   };
   return [...leads].map((lead, i) => ({ lead, i })).sort((a, b) => {
@@ -440,6 +448,43 @@ async function verifyEmails(leads, opts = {}) {
   return leads;
 }
 
+// src/geo.ts
+var R_EARTH_M = 63710088e-1;
+var toRad = (deg) => deg * Math.PI / 180;
+function haversineMeters(a, b) {
+  const dLat = toRad(b.lat - a.lat);
+  const dLng = toRad(b.lng - a.lng);
+  const lat1 = toRad(a.lat);
+  const lat2 = toRad(b.lat);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+  return 2 * R_EARTH_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+function parseLatLngPair(input) {
+  if (!input) return void 0;
+  const m = input.replace(/^@/, "").match(/(-?\d+(?:\.\d+)?)\s*[, ]\s*(-?\d+(?:\.\d+)?)/);
+  if (!m) return void 0;
+  const lat = parseFloat(m[1]);
+  const lng = parseFloat(m[2]);
+  if (!Number.isFinite(lat) || !Number.isFinite(lng)) return void 0;
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) return void 0;
+  return { lat, lng };
+}
+function parseDistance(input) {
+  if (!input) return void 0;
+  const m = input.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(km|m|mi|mile|miles|meters?|metres?)?$/);
+  if (!m) return void 0;
+  const value = parseFloat(m[1]);
+  if (!Number.isFinite(value) || value <= 0) return void 0;
+  const unit = m[2] ?? "m";
+  const metres = unit === "km" ? value * 1e3 : unit.startsWith("mi") ? value * 1609.344 : value;
+  return metres;
+}
+function zoomForRadius(radiusM, lat = 0) {
+  const mpp = 2 * Math.max(50, radiusM) / 600;
+  const zoom = Math.log2(156543.03392 * Math.cos(toRad(lat)) / mpp);
+  return Math.max(3, Math.min(19, Math.round(zoom)));
+}
+
 // src/export.ts
 import { stringify as csvStringify } from "@lacspace/csv";
 import { jsonToXlsx } from "@lacspace/xlsx";
@@ -465,6 +510,7 @@ var HEADERS = {
   plusCode: "Plus Code",
   latitude: "Latitude",
   longitude: "Longitude",
+  distanceKm: "Distance (km)",
   hours: "Hours",
   mapsUrl: "Maps URL"
 };
@@ -525,7 +571,7 @@ var FIELD_BY_KEY = (() => {
   }
   return m;
 })();
-var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude"]);
+var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude", "distanceKm"]);
 function rowsToLeads(rows) {
   return rows.map((row) => {
     const lead = {};
@@ -736,8 +782,13 @@ async function scrapeLeads(opts) {
   const pauseMs = () => opts.jitter ? Math.round(delayMs * (0.6 + Math.random() * 0.8)) : delayMs;
   const wantVerify = Boolean(opts.verifyEmails) || Boolean(opts.filters?.hasValidEmail) || fields.has("emailStatus");
   const wantEnrich = Boolean(opts.enrich) || ENRICHED_FIELDS.some((f) => fields.has(f)) || Boolean(opts.filters?.hasEmail) || wantVerify;
+  const near = opts.near;
   const collect = new Set(fields);
   if (wantEnrich) collect.add("website");
+  if (near) {
+    collect.add("latitude");
+    collect.add("longitude");
+  }
   const detailOnly = ["name", "mapsUrl"];
   const wantDetails = (opts.details ?? true) && ([...collect].some((f) => !detailOnly.includes(f)) || wantEnrich);
   onProgress?.(`searching Google Maps for "${query}"\u2026`);
@@ -751,6 +802,7 @@ async function scrapeLeads(opts) {
     const page = await context.newPage();
     const urlOpts = { hl: locale };
     if (opts.region) urlOpts.gl = opts.region;
+    if (near) urlOpts.center = { lat: near.lat, lng: near.lng, zoom: zoomForRadius(opts.radiusM ?? 2e3, near.lat) };
     await page.goto(mapsSearchUrl(query, urlOpts), { waitUntil: "domcontentloaded", timeout: 45e3 });
     await dismissConsent(page);
     await loadResults(page, limit, delayMs, onProgress, signal);
@@ -828,6 +880,19 @@ async function scrapeLeads(opts) {
         if (lead.website) lead.website = cleanWebsite(lead.website);
       }
     }
+    if (near) {
+      for (const lead of leads) {
+        if (typeof lead.latitude === "number" && typeof lead.longitude === "number") {
+          const m = haversineMeters(near, { lat: lead.latitude, lng: lead.longitude });
+          lead.distanceKm = Math.round(m / 1e3 * 100) / 100;
+        }
+      }
+      if (opts.radiusM !== void 0) {
+        const r = opts.radiusM;
+        leads = leads.filter((l) => l.distanceKm !== void 0 && l.distanceKm * 1e3 <= r);
+        onProgress?.(`within ${Math.round(r)} m: ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
+      }
+    }
     leads = dedupeLeads(leads, opts.dedupe ?? "website");
     if (wantEnrich) {
       const socialFields = ENRICHED_FIELDS.filter((f) => f !== "email");
@@ -868,6 +933,16 @@ async function scrapeLeads(opts) {
     if (opts.filters) leads = filterLeads(leads, opts.filters);
     if (opts.sort) leads = sortLeads(leads, opts.sort, opts.sortDir);
     if (wantVerify && !fields.has("emailStatus")) for (const l of leads) delete l.emailStatus;
+    if (near) {
+      const keepLat = fields.has("latitude");
+      const keepLng = fields.has("longitude");
+      const keepDist = fields.has("distanceKm");
+      for (const l of leads) {
+        if (!keepLat) delete l.latitude;
+        if (!keepLng) delete l.longitude;
+        if (!keepDist) delete l.distanceKm;
+      }
+    }
     onProgress?.(`collected ${leads.length} lead${leads.length === 1 ? "" : "s"}.`);
     return leads;
   } finally {
@@ -952,9 +1027,10 @@ import { jsonToXlsx as jsonToXlsx2, xlsxToJson } from "@lacspace/xlsx";
 function detectFormat(file) {
   const ext = extname(file).toLowerCase().replace(/^\./, "");
   if (ext === "json") return "json";
+  if (ext === "ndjson" || ext === "jsonl") return "ndjson";
   if (ext === "csv" || ext === "tsv") return "csv";
   if (ext === "xlsx" || ext === "xls") return "xlsx";
-  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|csv|xlsx).`);
+  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|ndjson|csv|xlsx).`);
 }
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
@@ -966,6 +1042,15 @@ async function readRows(file, format) {
   if (fmt === "csv") {
     return csvParse(text, { header: true });
   }
+  if (fmt === "ndjson") {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        throw new Error(`Invalid NDJSON on line ${i + 1}.`);
+      }
+    });
+  }
   const parsed = JSON.parse(text);
   if (Array.isArray(parsed)) return parsed;
   if (parsed && typeof parsed === "object") return [parsed];
@@ -988,6 +1073,9 @@ function serializeRows(rows, format, opts = {}) {
   if (format === "json") {
     return { data: JSON.stringify(rows, null, 2), binary: false };
   }
+  if (format === "ndjson") {
+    return { data: rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""), binary: false };
+  }
   const cols = columnsOf(rows);
   const flat = rows.map((row) => {
     const out = {};
@@ -1040,10 +1128,13 @@ export {
   extractEmails,
   extractSocials,
   filterLeads,
+  haversineMeters,
   mapsSearchUrl,
   normalizeFields,
   normalizePhone,
+  parseDistance,
   parseLatLng,
+  parseLatLngPair,
   parseRating,
   parseReviewCount,
   readRows,
@@ -1059,5 +1150,6 @@ export {
   sortLeads,
   toRows,
   verifyEmail,
-  verifyEmails
+  verifyEmails,
+  zoomForRadius
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lacspace-leads",
-  "version": "1.2.1",
-  "description": "Free, open-source local-business lead finder — name a city, area and business type, and it drives a real browser over Google Maps to collect names, phones, websites, ratings, addresses, emails and social links, then exports to JSON, NDJSON, CSV or Excel. Sweep multiple areas at once, verify emails by MX, normalise phones to E.164, accumulate into a master file, and enrich in parallel through an optional proxy. No API keys.",
+  "version": "1.4.0",
+  "description": "Free, open-source local-business lead finder — name a city/area/business type, or search by coordinates + radius, and it drives a real browser over Google Maps to collect names, phones, websites, ratings, addresses, emails and social links, then exports to JSON, NDJSON, CSV or Excel. Sweep multiple areas at once, verify emails by MX, normalise phones to E.164, accumulate into a master file, and enrich in parallel through an optional proxy. No API keys.",
   "type": "module",
   "bin": {
     "lacspace-leads": "dist/cli.js"
@@ -33,6 +33,8 @@
     "google-maps",
     "scraper",
     "local-business",
+    "radius-search",
+    "geosearch",
     "prospecting",
     "b2b",
     "email-finder",