Zillow API Wrapper for Node.js

Common errors

• Error: ZWSID not provided

  cause The Zillow client was instantiated without a valid Zillow Web Service ID (ZWSID) or an empty string was passed.
  fix Provide your Zillow Web Service ID during instantiation: `new Zillow('YOUR_ZWSID', options)` or ensure `process.env.ZWSID` is correctly set.

• TypeError: Zillow is not a constructor

  cause Attempted to call `Zillow` as a function without the `new` keyword after requiring it.
  fix Instantiate the `Zillow` class using `new`: `const zillow = new Zillow(zwsid);`

• Zillow API Error: 5003 - Invalid ZWSID

  cause The Zillow Web Service ID provided is either incorrect, revoked, has not been approved for the specific API endpoint, or has reached its daily request limit.
  fix Verify your ZWSID on the Zillow developer portal. Ensure it is active, correctly entered, and authorized for the API calls you are making. Check your daily API usage limits.

• TypeError: Cannot read properties of undefined (reading 'response')

  cause The Zillow API call returned a result object that did not contain the expected `response` property, leading to an attempt to access `undefined.response`.
  fix Always check for the existence of the `response` property before attempting to access it, as it's not guaranteed in all Zillow API responses: `if (results && results.response) { /* process response */ }`.

Warnings

• breaking Version 1.0.0 removed all direct API method wrappers (e.g., `Zillow.getDeepSearchResults()`) in favor of a single, unified `get` method for all Zillow API calls.
  Fix: Refactor all API calls to use the `zillowInstance.get("MethodName", parameters)` pattern.
• breaking Version 2.0.0 dropped explicit support for Node.js v0.10.x and updated internal dependencies. Running this package in very old Node.js environments may lead to compatibility issues.
  Fix: Ensure your Node.js environment is a modern LTS version (v6.x or newer is generally recommended for packages from this era, though Node.js v0.12.x was likely the minimum target for v2.0.0).
• gotcha The Zillow API's response object might not always include the `response` property, even for successful calls depending on the specific endpoint and data availability. Always check for its existence.
  Fix: Implement conditional checks before accessing the `response` property, e.g., `if (results && results.response) { /* use response */ }`.
• gotcha The `https` option for API requests defaults to `false` if not explicitly set during instantiation (`new Zillow(zwsid, options)`). This means API requests could be made over insecure HTTP, exposing your ZWSID and potentially sensitive data.
  Fix: Always explicitly set `{ https: true }` in the options object when instantiating the Zillow client to ensure secure communication: `new Zillow(zwsid, { https: true })`.
• gotcha Usage of the Zillow API via this wrapper is subject to Zillow's API Terms of Use and Branding Requirements. Failure to comply can result in API key revocation or legal action.
  Fix: Thoroughly review and adhere to the official Zillow API documentation for terms of use and branding requirements before deploying any application.
• deprecated The library internally uses the 'Q' promise library. While this doesn't directly affect the consumer if using standard promise `.then()` and `.catch()`, 'Q' is generally considered a legacy promise implementation superseded by native Promises in modern Node.js environments. This might affect advanced promise interop.
  Fix: No direct fix is required, but be aware of this implementation detail. If mixing with modern `async/await` or other promise libraries, consider converting 'Q' promises to native promises if issues arise, e.g., `Promise.resolve(qPromise)`.

Install

• npm install node-zillow npm
• yarn add node-zillow yarn
• pnpm add node-zillow pnpm

Imports

• Zillow
  wrong:

  import { Zillow } from 'node-zillow';

  correct:

  const Zillow = require('node-zillow');

  The library exports the Zillow constructor as a CommonJS module. For ESM, it should be imported as a default export.
• new Zillow()
  wrong:

  const zillow = Zillow(process.env.ZWSID);

  correct:

  const zillow = new Zillow(process.env.ZWSID);

  The `Zillow` object must be instantiated using the `new` keyword, as it is a class constructor.
• get
  wrong:

  Zillow.get('GetSearchResults', parameters);

  correct:

  zillow.get('GetSearchResults', parameters);

  The `get` method is an instance method and must be called on an instantiated `Zillow` object, not directly on the `Zillow` class.

Quickstart

Demonstrates how to instantiate the Zillow client and make a call to the `GetZestimate` API endpoint using a Zillow Web Service ID (ZWSID), including error handling.

const Zillow = require('node-zillow');

// It's highly recommended to use environment variables for sensitive IDs.
// For demonstration, use a placeholder or actual ID if safe.
const zwsid = process.env.ZWSID ?? 'YOUR_ZWSID_HERE'; // Replace with a valid ZWSID for actual use

if (!zwsid || zwsid === 'YOUR_ZWSID_HERE') {
    console.error('Error: ZWSID not provided. Please set ZWSID environment variable or replace placeholder.');
    process.exit(1);
}

// Instantiate the Zillow client, explicitly enabling HTTPS for secure communication.
const zillow = new Zillow(zwsid, { https: true });

// Define parameters for the Zillow API call. Example for GetZestimate.
const parameters = {
    zpid: 1111111 // Example Zillow Property ID
};

console.log(`Attempting to get Zestimate for ZPID: ${parameters.zpid}`);

zillow.get('GetZestimate', parameters)
    .then(function(results) {
        // Zillow API responses can vary; 'response' property might not always be present.
        if (results && results.response) {
            console.log('Successfully retrieved Zestimate:');
            console.log(JSON.stringify(results.response, null, 2));
        } else if (results && results.message) {
            console.error('Zillow API Message:', JSON.stringify(results.message, null, 2));
        } else {
            console.error('Unexpected Zillow API response structure:', JSON.stringify(results, null, 2));
        }
    })
    .catch(function(error) {
        console.error('An error occurred during Zillow API call:', error.message);
        if (error.response && error.response.data) {
            console.error('Detailed error response:', error.response.data);
        }
    });