@lovett/geosearch

Consumer SDK for the geosearch API — ZIP/VTD/county/place lookup + boundary geometry. Backend-agnostic: ships a Rust adapter (production, calls the Fly.io geocoder service) and a Supabase adapter (migration shim, kept until the Rust backend is fully live).

Install

npm install @lovett/geosearch
# If using the Supabase adapter, also:
npm install @supabase/supabase-js

Quick start

import { createGeosearchClient } from "@lovett/geosearch";

// Production: Rust backend
const geo = await createGeosearchClient({
  adapter: "rust",
  baseUrl: "https://geosearch.edwinlovett.com",
});

// Migration shim: Supabase
const geo = await createGeosearchClient({
  adapter: "supabase",
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseAnonKey: process.env.SUPABASE_ANON_KEY!,
});

// Either way, the same API:
const results = await geo.searchZips({ q: "Albany", state: "NY", limit: 25 });

Adapter selection

createGeosearchClient({ adapter, ... }) returns a GeosearchApi — the consumer code never needs to know which adapter is in play. Flipping backends is a config change.

| Adapter | Status | Bundle impact | |---|---|---| | 'rust' | Production — calls the Fly.io Rust service | Default; no extra deps | | 'supabase' | Migration shim — direct Supabase Postgres | Lazy-loads @supabase/supabase-js only when the Supabase adapter is constructed |

The Supabase adapter is intended to be removed once the Rust backend covers all required queries. Treat it as transitional.

Subpath imports

If you only need one adapter, importing the subpath skips loading the other:

import { createRustAdapter } from "@lovett/geosearch/rust";
import { createSupabaseAdapter } from "@lovett/geosearch/supabase";

The main barrel (@lovett/geosearch) only pulls the Rust adapter at module init; the Supabase adapter is dynamically imported on first construction. Subpath imports are useful when you want explicit control over what's in your bundle.

What the API covers

• ZIP search + lookup — searchZips, lookupZip
• State / county / city pickers — listStates, listCounties, listCities
• ZIP boundaries — zipBoundaries
• VTD (voter tabulation districts) — vtdsByCounties, vtdsByBbox, lookupVtd
• State / county / place boundaries — lookupStateBoundary, stateBoundariesByBbox, lookupCountyBoundary, countyBoundariesByBbox, lookupPlaceBoundary, placeBoundariesByBbox

Full type signatures are in @lovett/geosearch-types; this package re-exports the entire types surface so consumers usually only need to install one package.

Error handling

All adapter calls throw GeosearchApiError on backend errors:

import { GeosearchApiError } from "@lovett/geosearch";

try {
  const results = await geo.searchZips({ q: "albany" });
} catch (err) {
  if (err instanceof GeosearchApiError) {
    console.error(err.code, err.message);   // typed ApiErrorCode union
  }
}

License

UNLICENSED — distribution + use by Lovett Platform consumers only.