feat(zillow): add Zillow dedicated scraper API (SCR-99)

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.6] - 2026-07-07
+
+### Added
+
+- **Zillow client** (`client.zillow`) — real-estate coverage over zillow.com (US + Canadian inventory). Five endpoints across four sub-clients: `search.search()`, `search.autocomplete()`, `properties.getProperty()`, `agent.getAgent()`, `reference.listMarkets()`, with `Zillow*`-prefixed exported types (`ZillowSearchResponse`, `ZillowProperty`, `ZillowAgent`, …). (SCR-99)
+
 ## [0.15.5] - 2026-07-07
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrapebadger",
-  "version": "0.15.5",
+  "version": "0.15.6",
   "description": "Official Node.js SDK for ScrapeBadger - Async web scraping APIs for Twitter, Google, Vinted, Reddit, and more",
   "type": "module",
   "main": "./dist/index.js",

src/client.ts

@@ -18,6 +18,7 @@ import { EbayClient } from "./ebay/client.js";
 import { YoutubeClient } from "./youtube/client.js";
 import { RealtorClient } from "./realtor/client.js";
 import { LeboncoinClient } from "./leboncoin/client.js";
+import { ZillowClient } from "./zillow/client.js";
 
 /**
  * ScrapeBadger API client.
@@ -90,6 +91,9 @@ export class ScrapeBadger {
   /** Leboncoin scraper API client — 10 endpoints (France) */
   readonly leboncoin: LeboncoinClient;
 
+  /** Zillow scraper API client — 5 endpoints (search, property, agent, autocomplete, markets) */
+  readonly zillow: ZillowClient;
+
   /**
    * Create a new ScrapeBadger client.
    *
@@ -141,5 +145,6 @@ export class ScrapeBadger {
     this.youtube = new YoutubeClient(this.baseClient);
     this.realtor = new RealtorClient(this.baseClient);
     this.leboncoin = new LeboncoinClient(this.baseClient);
+    this.zillow = new ZillowClient(this.baseClient);
   }
 }

src/index.ts

@@ -88,6 +88,7 @@ export * from "./ebay/index.js";
 // Re-export YouTube module — YoutubeClient + Youtube*-prefixed sub-clients and types
 export * from "./youtube/index.js";
 export * from "./realtor/index.js";
+export * from "./zillow/index.js";
 
 // Re-export Leboncoin module — LeboncoinClient + Leboncoin*-prefixed sub-clients and types
 export * from "./leboncoin/index.js";

src/zillow/agent.ts

@@ -0,0 +1,43 @@
+/**
+ * Zillow Agent API client.
+ *
+ * Provides a method for fetching an agent profile and their listings.
+ */
+
+import type { BaseClient } from "../internal/client.js";
+import type { ZillowAgentOptions, AgentResponse } from "./types.js";
+
+/**
+ * Client for the zillow agent profile endpoint.
+ *
+ * @example
+ * ```typescript
+ * const client = new ScrapeBadger({ apiKey: "key" });
+ *
+ * const { agent } = await client.zillow.agent.getAgent({ username: "some-agent" });
+ * console.log(agent.name, agent.review_count, agent.listings.length);
+ * ```
+ */
+export class AgentClient {
+  private readonly client: BaseClient;
+
+  constructor(client: BaseClient) {
+    this.client = client;
+  }
+
+  /**
+   * Get a Zillow real-estate professional's profile and their active listings.
+   *
+   * Provide either a `username` (screen name) or a full `url`.
+   *
+   * @param options - The agent `username` or profile `url`.
+   * @returns Agent profile wrapped in `{ agent }`.
+   * @throws NotFoundError - If the agent doesn't exist.
+   * @throws ValidationError - If neither username nor url is provided.
+   */
+  async getAgent(options: ZillowAgentOptions = {}): Promise<AgentResponse> {
+    return this.client.request<AgentResponse>("/v1/zillow/agent", {
+      params: { username: options.username, url: options.url },
+    });
+  }
+}

src/zillow/client.ts

@@ -0,0 +1,69 @@
+/**
+ * Zillow API client.
+ *
+ * Provides access to all Zillow API endpoints through specialized sub-clients.
+ */
+
+import type { BaseClient } from "../internal/client.js";
+import { SearchClient } from "./search.js";
+import { PropertiesClient } from "./properties.js";
+import { AgentClient } from "./agent.js";
+import { ReferenceClient } from "./reference.js";
+
+/**
+ * Zillow API client with access to all Zillow endpoints.
+ *
+ * Maximal-coverage real-estate API over zillow.com (US + Canadian inventory,
+ * all served from zillow.com behind a US IP).
+ *
+ * Provides sub-clients for different resource types:
+ * - `search` - Property search and location autocomplete
+ * - `properties` - Full property detail
+ * - `agent` - Agent profile + their listings
+ * - `reference` - Reference data (markets)
+ *
+ * @example
+ * ```typescript
+ * const client = new ScrapeBadger({ apiKey: "key" });
+ *
+ * // Search properties
+ * const results = await client.zillow.search.search("Austin, TX");
+ *
+ * // Location autocomplete
+ * const suggestions = await client.zillow.search.autocomplete("Miami");
+ *
+ * // Get property detail
+ * const { property } = await client.zillow.properties.getProperty("2078029085");
+ *
+ * // Get an agent profile
+ * const { agent } = await client.zillow.agent.getAgent({ username: "some-agent" });
+ *
+ * // Reference data
+ * const markets = await client.zillow.reference.listMarkets();
+ * ```
+ */
+export class ZillowClient {
+  /** Client for property search and location autocomplete */
+  readonly search: SearchClient;
+
+  /** Client for full property detail */
+  readonly properties: PropertiesClient;
+
+  /** Client for agent profile + listings */
+  readonly agent: AgentClient;
+
+  /** Client for reference data (markets) */
+  readonly reference: ReferenceClient;
+
+  /**
+   * Create a new Zillow client.
+   *
+   * @param client - The base HTTP client for making requests.
+   */
+  constructor(client: BaseClient) {
+    this.search = new SearchClient(client);
+    this.properties = new PropertiesClient(client);
+    this.agent = new AgentClient(client);
+    this.reference = new ReferenceClient(client);
+  }
+}

src/zillow/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Zillow API module.
+ *
+ * @module zillow
+ */
+
+export { ZillowClient } from "./client.js";
+export { SearchClient as ZillowSearchClient } from "./search.js";
+export { PropertiesClient as ZillowPropertiesClient } from "./properties.js";
+export { AgentClient as ZillowAgentClient } from "./agent.js";
+export { ReferenceClient as ZillowReferenceClient } from "./reference.js";
+
+// Export all types
+export type {
+  // Shared
+  LatLong as ZillowLatLong,
+  Photo as ZillowPhoto,
+  Pagination as ZillowPagination,
+  MapBounds as ZillowMapBounds,
+  RegionSelection as ZillowRegionSelection,
+  NearbyRegion as ZillowNearbyRegion,
+  MarketInfo as ZillowMarketInfo,
+  // Search results
+  Listing as ZillowListing,
+  // Property detail
+  Address as ZillowAddress,
+  ListingSubType as ZillowListingSubType,
+  OpenHouse as ZillowOpenHouse,
+  ZestimateHistoryPoint as ZillowZestimateHistoryPoint,
+  PriceHistoryEvent as ZillowPriceHistoryEvent,
+  TaxHistoryEvent as ZillowTaxHistoryEvent,
+  School as ZillowSchool,
+  AgentAttribution as ZillowAgentAttribution,
+  MortgageRate as ZillowMortgageRate,
+  MortgageRates as ZillowMortgageRates,
+  HomeFacts as ZillowHomeFacts,
+  Property as ZillowProperty,
+  // Agent profile
+  AgentReview as ZillowAgentReview,
+  PastSale as ZillowPastSale,
+  AgentLicense as ZillowAgentLicense,
+  Agent as ZillowAgent,
+  // Autocomplete
+  AutocompleteResult as ZillowAutocompleteResult,
+  // Response envelopes
+  SearchResponse as ZillowSearchResponse,
+  PropertyResponse as ZillowPropertyResponse,
+  AgentResponse as ZillowAgentResponse,
+  AutocompleteResponse as ZillowAutocompleteResponse,
+  MarketsResponse as ZillowMarketsResponse,
+  // Param enums
+  ZillowStatus,
+  ZillowSort,
+  // Request params
+  ZillowSearchOptions,
+  ZillowAgentOptions,
+} from "./types.js";

src/zillow/properties.ts

@@ -0,0 +1,41 @@
+/**
+ * Zillow Properties API client.
+ *
+ * Provides a method for fetching full property detail.
+ */
+
+import type { BaseClient } from "../internal/client.js";
+import type { PropertyResponse } from "./types.js";
+
+/**
+ * Client for the zillow property detail endpoint.
+ *
+ * @example
+ * ```typescript
+ * const client = new ScrapeBadger({ apiKey: "key" });
+ *
+ * const { property } = await client.zillow.properties.getProperty("2078029085");
+ * console.log(property.street_address, property.price);
+ * ```
+ */
+export class PropertiesClient {
+  private readonly client: BaseClient;
+
+  constructor(client: BaseClient) {
+    this.client = client;
+  }
+
+  /**
+   * Get a single Zillow property's full detail by its zpid.
+   *
+   * Returns price/valuation, specs, resoFacts (home_facts), price & tax
+   * history, schools, listing agent, mortgage rates and photos.
+   *
+   * @param zpid - The Zillow property id.
+   * @returns Property detail wrapped in `{ property }`.
+   * @throws NotFoundError - If the property doesn't exist.
+   */
+  async getProperty(zpid: string): Promise<PropertyResponse> {
+    return this.client.request<PropertyResponse>(`/v1/zillow/property/${zpid}`);
+  }
+}

src/zillow/reference.ts

@@ -0,0 +1,38 @@
+/**
+ * Zillow Reference Data API client.
+ *
+ * Provides a method for fetching the coverage market list.
+ */
+
+import type { BaseClient } from "../internal/client.js";
+import type { MarketsResponse } from "./types.js";
+
+/**
+ * Client for zillow reference data endpoints (markets).
+ *
+ * @example
+ * ```typescript
+ * const client = new ScrapeBadger({ apiKey: "key" });
+ *
+ * const markets = await client.zillow.reference.listMarkets();
+ * for (const m of markets.markets) {
+ *   console.log(`${m.code}: ${m.domain} (${m.currency})`);
+ * }
+ * ```
+ */
+export class ReferenceClient {
+  private readonly client: BaseClient;
+
+  constructor(client: BaseClient) {
+    this.client = client;
+  }
+
+  /**
+   * List Zillow coverage regions (US + Canada, all served via zillow.com).
+   *
+   * @returns Markets response with all supported markets.
+   */
+  async listMarkets(): Promise<MarketsResponse> {
+    return this.client.request<MarketsResponse>("/v1/zillow/markets");
+  }
+}

src/zillow/search.ts

@@ -0,0 +1,85 @@
+/**
+ * Zillow Search API client.
+ *
+ * Provides methods for property search and location autocomplete.
+ */
+
+import type { BaseClient } from "../internal/client.js";
+import type { ZillowSearchOptions, SearchResponse, AutocompleteResponse } from "./types.js";
+
+/**
+ * Client for zillow search and autocomplete endpoints.
+ *
+ * @example
+ * ```typescript
+ * const client = new ScrapeBadger({ apiKey: "key" });
+ *
+ * const results = await client.zillow.search.search("Austin, TX", { bedsMin: 3 });
+ * for (const l of results.results) {
+ *   console.log(`${l.address} — ${l.price_raw}`);
+ * }
+ *
+ * const suggestions = await client.zillow.search.autocomplete("Miami");
+ * ```
+ */
+export class SearchClient {
+  private readonly client: BaseClient;
+
+  constructor(client: BaseClient) {
+    this.client = client;
+  }
+
+  /**
+   * Search Zillow for properties.
+   *
+   * Beat the ~820-result (20-page) cap by re-issuing the search over
+   * subdivided `north/south/east/west` map-bound boxes returned in
+   * `map_bounds`.
+   *
+   * @param location - City/state, ZIP, address, or neighborhood ("Austin, TX").
+   * @param options - Filters, sorting, pagination, and map bounds.
+   * @returns Search results with pagination and map metadata.
+   * @throws AuthenticationError - If the API key is invalid.
+   * @throws ValidationError - If the parameters are invalid.
+   */
+  async search(location: string, options: ZillowSearchOptions = {}): Promise<SearchResponse> {
+    return this.client.request<SearchResponse>("/v1/zillow/search", {
+      params: {
+        location,
+        status: options.status,
+        page: options.page,
+        sort: options.sort,
+        price_min: options.priceMin,
+        price_max: options.priceMax,
+        beds_min: options.bedsMin,
+        baths_min: options.bathsMin,
+        home_type: options.homeType,
+        sqft_min: options.sqftMin,
+        sqft_max: options.sqftMax,
+        lot_min: options.lotMin,
+        lot_max: options.lotMax,
+        year_built_min: options.yearBuiltMin,
+        year_built_max: options.yearBuiltMax,
+        hoa_max: options.hoaMax,
+        keywords: options.keywords,
+        days_on: options.daysOn,
+        north: options.north,
+        south: options.south,
+        east: options.east,
+        west: options.west,
+      },
+    });
+  }
+
+  /**
+   * Resolve a search term to Zillow regions/addresses (regionId, lat/lng).
+   *
+   * @param query - Partial location — city, ZIP, address, or neighborhood.
+   * @returns Autocomplete suggestions.
+   */
+  async autocomplete(query: string): Promise<AutocompleteResponse> {
+    return this.client.request<AutocompleteResponse>("/v1/zillow/autocomplete", {
+      params: { query },
+    });
+  }
+}