SDK Quickstart

import { BoroughClient } from "@borough/sdk";

// No key needed for free-tier search, areas, and market data.
// With no argument the client also picks up BOROUGH_API_KEY if it is set.
const borough = new BoroughClient();

// Search rentals in Midtown
const results = await borough.rentals.search({
  areas: "120",
  minBeds: 1,
  maxPrice: 4000,
  noFee: true,
});

console.log(`Found ${results.meta.total} listings`);
for (const listing of results.data) {
  console.log(
    `${listing.address.street}${listing.address.unit ? ` ${listing.address.unit}` : ""} — $${listing.price}/mo`,
  );
}

// Free tier: no key
const borough = new BoroughClient();

// Simple — just the API key
const borough = new BoroughClient("BOROUGH-...");

// Full config
const borough = new BoroughClient({
  apiKey: "BOROUGH-...",
  baseURL: "https://borough.qwady.app/v1", // default
  timeout: 30_000, // 30s default
  maxRetries: 2, // retries rate limits, 5xx responses and network failures
});

// Environment variable fallback
// Set BOROUGH_API_KEY in your environment, then:
const borough = new BoroughClient();

// Search
const rentals = await borough.rentals.search({ areas: "120", minBeds: 2 });
const sales = await borough.sales.search({ areas: "200", maxPrice: 1_000_000 });

// Property details
const listing = await borough.listings.get("4961849");
const byUrl = await borough.listings.getByUrl("/building/<slug>/<unit>");
const history = await borough.listings.history("4961849");
const fees = await borough.listings.fees("4961849");
const openHouses = await borough.listings.openHouses("4961849");

// Building data
const building = await borough.buildings.get("12345");
const scores = await borough.buildings.scores("12345");
const violations = await borough.buildings.violations("12345");
const buildingListings = await borough.buildings.listings("12345");

// Areas
const allAreas = await borough.areas.list();
const neighborhoods = await borough.areas.list({ level: 2, parentId: 100 });

// Market data
const snapshot = await borough.market.snapshot({ areaId: 120, bedrooms: 1 });
const trends = await borough.market.trends({ areaId: 120 });
const comparison = await borough.market.compare({ areas: "120,200,300" });
const marketHistory = await borough.market.history({ areaId: 120, days: 90 });

for await (const event of await borough.listings.stream("4961849")) {
  if (event.event === "cached") console.log("cached price", event.data.price);
  if (event.event === "live") console.log("live data", event.data);
  if (event.event === "error") console.log("no live data:", event.data.code);
}

const { data: watcher } = await borough.watchers.create({
  watchType: "search",
  searchFilters: { areas: "302", maxPrice: 4000, beds: 1 },
});

await borough.watchers.update(watcher.id, { active: false }); // pause
const all = await borough.watchers.list();

const controller = new AbortController();
const stream = await borough.watchers.stream(watcher.id, {
  maxReconnects: 12, // about one hour
  signal: controller.signal,
});

for await (const event of stream) {
  if (event.event === "change") console.log(event.data.eventType, event.data.listingId);
}

import {
  BoroughClient,
  NotFoundError,
  RateLimitError,
  QuotaExceededError,
} from "@borough/sdk";

const borough = new BoroughClient("BOROUGH-...");

try {
  const listing = await borough.listings.get("nonexistent");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Listing not found");
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof QuotaExceededError) {
    console.log("Monthly quota exceeded");
  } else {
    throw error;
  }
}

// Disable retries
const borough = new BoroughClient({ apiKey: "...", maxRetries: 0 });

import type {
  ListingSummary,
  ListingDetail,
  BuildingDetail,
  BuildingScores,
  SearchParams,
  SaleSearchParams,
} from "@borough/sdk";