{
  "openapi": "3.1.0",
  "info": {
    "title": "PropertiesAPI Zillow API",
    "version": "1.0.0-preview",
    "summary": "Zillow property and listing data as JSON, from a Zillow URL or an address.",
    "description": "Send a Zillow property URL or a US address. Get back { data, meta }: data has the listing price and status, Zestimate, rent Zestimate, home facts, photo URLs, days on Zillow, price history, tax history, schools, broker and agent. Live lookups typically take 8 seconds, up to about 20 (measured; set a client timeout of at least 120 seconds); repeat lookups of the same home within 24 hours come from cache and are free (x-cache: HIT). Errors aren't billed. Fields Zillow doesn't show for a property are null.\n\nData is provided as-is, without any guarantee of accuracy or completeness. Not for FCRA uses (credit, insurance, employment or tenant screening).\n\nZillow is a trademark of Zillow, Inc. PropertiesAPI is an independent service and is not affiliated with, endorsed by or sponsored by Zillow.",
    "contact": {
      "name": "PropertiesAPI",
      "url": "https://propertiesapi.com/waitlist"
    }
  },
  "servers": [
    {
      "url": "https://api.propertiesapi.com/v1",
      "description": "v1 (preview)"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Zillow",
      "description": "Zillow property and listing lookups by URL or address."
    }
  ],
  "paths": {
    "/zillow/property": {
      "get": {
        "operationId": "getZillowProperty",
        "summary": "Zillow property lookup",
        "description": "One property by Zillow URL or address: listing price and status, Zestimate, rent Zestimate, beds, baths, living area, lot, year built, home type, photo URLs, days on Zillow, price history, tax history, schools, broker and agent.\n\nBilling: 1 credit per successful live lookup, by Zillow link or address. Repeat lookups of the same home within 24 hours come from cache and are free. Errors aren't billed.\n\n- Send exactly one of url or address. Sending neither returns 400 missing_param; sending both returns 400 bad_param.\n- The body is { data, meta }. data is the property; meta has credits, cached, cache_key, fetched_at, source and took_ms.\n- The x-cache response header is HIT when the result came from the 24-hour cache (free, no live lookup) and MISS when it was fetched live.\n- A live lookup typically takes 8 seconds, up to about 20. Set a client timeout of at least 120 seconds: an occasional lookup takes longer.\n- Fields Zillow doesn't show for a property come back as null. Don't treat null as zero.\n- price is the listing price (monthly rent for rentals). zestimate and rentZestimate are Zillow's own estimates, returned only when Zillow shows them. PropertiesAPI doesn't make estimates of its own.\n- An apartment-building link (zillow.com/apartments/...) returns the building: zpid, address, photos and schools are the building listing's, and price, beds, baths, livingArea and unit come from its lowest-priced unit available now (no move-in date, or one on or before the lookup date; if none is available yet, its lowest-priced unit). The other units aren't returned yet.\n- photos is a list of image URLs. priceHistory, taxHistory and schools are lists and can be empty.\n- Data is provided as-is, as shown on the public Zillow page at the time of the lookup. It isn't official and isn't guaranteed to be accurate or complete.",
        "tags": [
          "Zillow"
        ],
        "externalDocs": {
          "url": "https://propertiesapi.com/docs/endpoints/property"
        },
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "A zillow.com property link (zillow.com/homedetails/..._zpid/, or an apartment-building link, zillow.com/apartments/...). URL-encode it. Max 500 characters.",
            "schema": {
              "type": "string"
            },
            "example": "https://www.zillow.com/homedetails/1600-Main-St-Austin-TX-78701/0000000_zpid/"
          },
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "A one-line US address with a house number, 5-200 characters. We find the matching Zillow property first. Include the unit number for condos and apartments.",
            "schema": {
              "type": "string"
            },
            "example": "1600 Main St, Austin, TX 78701"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Optional hint for which listing to read. If omitted, the status is detected automatically.",
            "schema": {
              "type": "string",
              "enum": [
                "for_sale",
                "sold",
                "for_rent"
              ]
            }
          },
          {
            "name": "raw",
            "in": "query",
            "required": false,
            "description": "Also return the unmapped source record as data.raw. Its shape isn't documented and can change.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-api-version": {
                "description": "Always v1.",
                "schema": {
                  "type": "string"
                }
              },
              "cache-control": {
                "description": "no-store.",
                "schema": {
                  "type": "string"
                }
              },
              "x-cache": {
                "description": "HIT when served from the 24-hour cache (free), MISS when fetched live.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "HIT",
                    "MISS"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyResponse"
                },
                "example": {
                  "data": {
                    "zpid": "0000000",
                    "detailUrl": "https://www.zillow.com/homedetails/1600-Main-St-Austin-TX-78701/0000000_zpid/",
                    "address": "1600 Main St, Austin, TX 78701",
                    "streetAddress": "1600 Main St",
                    "unit": null,
                    "city": "Austin",
                    "state": "TX",
                    "zipcode": "78701",
                    "county": "Travis County",
                    "neighborhood": null,
                    "latitude": 30.27,
                    "longitude": -97.74,
                    "price": 525000,
                    "currency": "USD",
                    "homeStatus": "FOR_SALE",
                    "statusText": "For sale",
                    "homeType": "SINGLE_FAMILY",
                    "beds": 3,
                    "baths": 2,
                    "livingArea": 1840,
                    "lotSize": 6970,
                    "yearBuilt": 1998,
                    "pricePerSquareFoot": 285,
                    "zestimate": 512000,
                    "rentZestimate": 2650,
                    "daysOnZillow": 12,
                    "datePosted": "2026-10-07",
                    "dateSold": null,
                    "lastSoldPrice": null,
                    "monthlyHoaFee": null,
                    "taxAnnualAmount": 9840,
                    "taxAssessedValue": 498000,
                    "propertyTaxRate": 1.98,
                    "parcelId": null,
                    "description": "Three-bedroom home near downtown.",
                    "imgSrc": "https://photos.example.com/0000000-1.jpg",
                    "photos": [
                      "https://photos.example.com/0000000-1.jpg",
                      "https://photos.example.com/0000000-2.jpg"
                    ],
                    "photoCount": 2,
                    "brokerName": "Example Realty",
                    "brokerPhone": null,
                    "agentName": null,
                    "agentPhone": null,
                    "agentLicenseNumber": null,
                    "mlsId": null,
                    "mlsName": null,
                    "priceHistory": [
                      {
                        "date": "2026-10-07",
                        "event": "Listed for sale",
                        "price": 525000,
                        "pricePerSquareFoot": 285,
                        "priceChangeRate": null,
                        "source": "Example MLS"
                      }
                    ],
                    "taxHistory": [
                      {
                        "year": 2025,
                        "taxPaid": 9840,
                        "value": 498000,
                        "taxIncreaseRate": null,
                        "valueIncreaseRate": null
                      }
                    ],
                    "schools": [],
                    "virtualTourUrl": null,
                    "scrapedAt": "2026-10-19T14:02:11.000Z"
                  },
                  "meta": {
                    "credits": 1,
                    "cached": false,
                    "cache_key": "zpid:0000000",
                    "fetched_at": "2026-10-19T14:02:11.000Z",
                    "source": {
                      "provider": "apify",
                      "actor": "maxcopell/zillow-detail-scraper",
                      "note": "Zillow data collected by an Apify actor. PropertiesAPI is not affiliated with Zillow."
                    },
                    "took_ms": 14230
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          },
          "504": {
            "$ref": "#/components/responses/E504"
          }
        }
      }
    },
    "/zillow/batch": {
      "post": {
        "operationId": "batchZillowProperties",
        "summary": "Zillow batch lookup",
        "description": "Up to 50 Zillow URLs or addresses in one request. Each item is looked up exactly as GET /v1/zillow/property would, and comes back with its own ok flag.\n\nBilling: 1 credit per successful live lookup, by Zillow link or address. Repeat lookups of the same home within 24 hours come from cache and are free. Errors aren't billed.\n\n- More than 50 items returns 400 too_many_items. An empty or missing items array, or a body that isn't JSON, returns 400 bad_body. Split larger lists into several requests.\n- data has one result per item, in the same order, with its index. Check each result's ok: one failed item doesn't fail the batch.\n- Items run concurrently within an overall time limit of about 280 seconds. Items that couldn't start in time come back with error code batch_deadline; retry those.\n- meta.credits is the number of credits charged. Only successful live lookups count; cache hits and failed items are free.",
        "tags": [
          "Zillow"
        ],
        "externalDocs": {
          "url": "https://propertiesapi.com/docs/endpoints/batch"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-api-version": {
                "description": "Always v1.",
                "schema": {
                  "type": "string"
                }
              },
              "cache-control": {
                "description": "no-store.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResponse"
                },
                "example": {
                  "data": [
                    {
                      "index": 0,
                      "ok": true,
                      "data": {
                        "zpid": "0000000",
                        "price": 525000,
                        "zestimate": 512000,
                        "...": "same fields as GET /v1/zillow/property"
                      },
                      "meta": {
                        "credits": 0,
                        "cached": true,
                        "cache_key": "zpid:0000000",
                        "fetched_at": "2026-10-19T14:02:11.000Z",
                        "source": {
                          "provider": "apify",
                          "actor": "maxcopell/zillow-detail-scraper",
                          "note": "Zillow data collected by an Apify actor. PropertiesAPI is not affiliated with Zillow."
                        },
                        "took_ms": 2
                      }
                    },
                    {
                      "index": 1,
                      "ok": false,
                      "error": {
                        "code": "not_found",
                        "message": "No Zillow property matches this input"
                      }
                    }
                  ],
                  "meta": {
                    "count": 2,
                    "succeeded": 1,
                    "failed": 1,
                    "cache_hits": 1,
                    "credits": 0,
                    "took_ms": 9120
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        },
        "requestBody": {
          "required": true,
          "description": "items: 1 to 50 entries. Each is a string (a zillow.com link or an address) or an object with one of url or address. Optional status (for_sale, sold or for_rent) applies to every item; optional raw: true adds data.raw.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              },
              "example": {
                "items": [
                  "https://www.zillow.com/homedetails/1600-Main-St-Austin-TX-78701/0000000_zpid/",
                  "1 Nowhere Rd, Austin, TX 78701",
                  {
                    "address": "1600 Main St, Austin, TX 78701"
                  }
                ],
                "status": "for_sale"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "responses": {
      "E400": {
        "description": "missing_param: None of url, address or zpid was sent.\n\nbad_param: More than one of url, address, zpid; url isn't a zillow.com property link or is too long; address is outside 5-200 characters, has no house number, or has neither a city and state nor a ZIP code (US addresses only; checked before any lookup, so it's free); zpid isn't digits; status isn't for_sale, sold or for_rent; raw isn't true or false.\n\nbad_body: Batch only: the body isn't JSON, or items is missing or empty.\n\ntoo_many_items: Batch only: more than 50 items.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E401": {
        "description": "missing_api_key: The x-api-key header is missing.\n\ninvalid_api_key: The key is unknown.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E402": {
        "description": "credits_exhausted: The account's lookups are used up: the Free plan's one-time lookups, or a paid plan's included lookups while usage past the plan is off (it pauses while a payment is failing). Not billed, no lookup made. details.upgrade_url links to pricing. Cached properties still work.\n\nspend_limit_reached: Only if you set an optional monthly spending limit (there is none by default, and usage past the plan isn't capped): a paid plan went past its included lookups at its own per-lookup rate and reached that limit. Not billed, no lookup made. details has the limit (spend_limit_usd), your plan's overage rate, the overage used so far and dashboard_url, where you can raise or remove the limit. Cached properties still work; the limit resets with your billing period.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E404": {
        "description": "not_found: No Zillow property matches the URL, address or zpid. details.reason may say why.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E409": {
        "description": "address_ambiguous: Zillow's closest match for the address is a different home (another house number, street, directional, unit, ZIP, city or state). Not billed. details.candidate.detailUrl is that home's Zillow link and details.mismatch says what differed. Repeating the same address within an hour returns the same 409 without a new lookup. If the candidate is the home you meant, look it up with url=detailUrl (a normal, billed lookup); otherwise add the unit, city, state or ZIP.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E422": {
        "description": "unprocessable_input: The data provider rejected this input. Check the Zillow URL or address.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E500": {
        "description": "internal: Something failed on our side. Safe to retry with backoff.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E502": {
        "description": "upstream_error: The data provider failed (also upstream_unreachable, upstream_bad_response, upstream_run_failed). Safe to retry with backoff.\n\nupstream_cost_cap: The lookup was stopped at its per-lookup upstream cost limit before it found the home. Not billed. Retry at most once, with status=for_sale, sold or for_rent if you know it.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E503": {
        "description": "upstream_busy: The data provider is busy. Wait for retry-after seconds. Other 503 codes (no_api_keys, live_lookups_disabled, upstream_auth, upstream_quota, upstream_actor_missing, upstream_misconfigured) mean live lookups are unavailable on our side.\n\nlive_lookups_capped: Today's service-wide safety limit on live lookups is reached: our daily upstream budget (for paid plans, details.scope is paid_daily_budget). It is our limit, not one on your account, and nothing is billed. Cached properties still work; new lookups resume at 00:00 UTC (retry-after has the seconds until then).\n\nstore_unavailable: Our usage and cache store is unreachable, so live lookups are refused rather than run unmetered. Retry after retry-after seconds (30).",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          },
          "retry-after": {
            "description": "On upstream_busy: seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E504": {
        "description": "upstream_timeout: The live lookup took too long. Safe to retry. In a batch, batch_deadline means the item didn't start in time.",
        "headers": {
          "x-api-version": {
            "description": "Always v1.",
            "schema": {
              "type": "string"
            }
          },
          "cache-control": {
            "description": "no-store.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "ZillowProperty": {
        "type": "object",
        "description": "One Zillow property (type ZillowProperty). Fields Zillow doesn't show for this property are null; lists may be empty. With raw=true, data also has raw (the unmapped source record).\n\nUsually null: price: The home isn't listed for sale or rent, the listing doesn't show a price, or a sold home's sale price isn't disclosed (some states don't publish sale prices). zestimate: Zillow doesn't show a Zestimate for this home. rentZestimate: Zillow doesn't show a rent Zestimate for this home. beds, baths, livingArea, lotSize, yearBuilt: The Zillow page doesn't list this fact (common for land and new construction). daysOnZillow: The home isn't currently listed. brokerName, agentName: The listing doesn't name a broker or agent, or the home isn't listed.",
        "required": [
          "zpid",
          "detailUrl",
          "address",
          "streetAddress",
          "unit",
          "city",
          "state",
          "zipcode",
          "county",
          "neighborhood",
          "latitude",
          "longitude",
          "price",
          "currency",
          "homeStatus",
          "statusText",
          "homeType",
          "beds",
          "baths",
          "livingArea",
          "lotSize",
          "yearBuilt",
          "pricePerSquareFoot",
          "zestimate",
          "rentZestimate",
          "daysOnZillow",
          "datePosted",
          "dateSold",
          "lastSoldPrice",
          "monthlyHoaFee",
          "taxAnnualAmount",
          "taxAssessedValue",
          "propertyTaxRate",
          "parcelId",
          "description",
          "imgSrc",
          "photos",
          "photoCount",
          "brokerName",
          "brokerPhone",
          "agentName",
          "agentPhone",
          "agentLicenseNumber",
          "mlsId",
          "mlsName",
          "priceHistory",
          "taxHistory",
          "schools",
          "virtualTourUrl",
          "scrapedAt"
        ],
        "properties": {
          "zpid": {
            "type": [
              "string",
              "null"
            ],
            "description": "Zillow property ID."
          },
          "detailUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Zillow property page."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "One-line address."
          },
          "streetAddress": {
            "type": [
              "string",
              "null"
            ],
            "description": "Street line."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "Unit number, e.g. 1905 for 600 N Fairbanks Ct APT 1905. For an apartment building, the unit that price describes (see price)."
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "description": "City."
          },
          "state": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two-letter state code."
          },
          "zipcode": {
            "type": [
              "string",
              "null"
            ],
            "description": "ZIP code."
          },
          "county": {
            "type": [
              "string",
              "null"
            ],
            "description": "County."
          },
          "neighborhood": {
            "type": [
              "string",
              "null"
            ],
            "description": "Neighborhood name."
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ],
            "description": "Latitude."
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ],
            "description": "Longitude."
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "List price. For rentals, the monthly rent. For an apartment building (a zillow.com/apartments/ link), the rent of its lowest-priced unit available now (no move-in date, or one on or before the lookup date; if none is available yet, its lowest-priced unit); beds, baths, livingArea and unit describe that same unit. For sold homes, the sale price, or null when the sale price isn't disclosed. Never 0."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Currency of price, e.g. USD."
          },
          "homeStatus": {
            "type": [
              "string",
              "null"
            ],
            "description": "Zillow's status code: FOR_SALE, FOR_RENT, RECENTLY_SOLD, PENDING, COMING_SOON, FORECLOSURE, OFF_MARKET or OTHER. Homes that aren't listed usually come back as OTHER."
          },
          "statusText": {
            "type": [
              "string",
              "null"
            ],
            "description": "A short readable status built from Zillow's status and listing flags: For sale, Pending, Coming soon, New construction, For sale by owner, Foreclosure, Auction, For rent, Sold or Off market. Null when the status is unclear."
          },
          "homeType": {
            "type": [
              "string",
              "null"
            ],
            "description": "SINGLE_FAMILY, CONDO, TOWNHOUSE, MULTI_FAMILY, APARTMENT, LOT, MANUFACTURED, ..."
          },
          "beds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bedrooms."
          },
          "baths": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bathrooms."
          },
          "livingArea": {
            "type": [
              "number",
              "null"
            ],
            "description": "Living area in square feet."
          },
          "lotSize": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lot size in square feet (acres converted)."
          },
          "yearBuilt": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Year built."
          },
          "pricePerSquareFoot": {
            "type": [
              "number",
              "null"
            ],
            "description": "Price per square foot."
          },
          "zestimate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Zillow's Zestimate, when shown."
          },
          "rentZestimate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Zillow's rent Zestimate (a month), when shown."
          },
          "daysOnZillow": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Days the current listing has been on Zillow."
          },
          "datePosted": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date listed, YYYY-MM-DD."
          },
          "dateSold": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date of the last sale, YYYY-MM-DD."
          },
          "lastSoldPrice": {
            "type": [
              "number",
              "null"
            ],
            "description": "Last sale price."
          },
          "monthlyHoaFee": {
            "type": [
              "number",
              "null"
            ],
            "description": "HOA fee a month."
          },
          "taxAnnualAmount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Annual property tax."
          },
          "taxAssessedValue": {
            "type": [
              "number",
              "null"
            ],
            "description": "Assessed value."
          },
          "propertyTaxRate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Property tax rate, percent."
          },
          "parcelId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parcel (APN) number."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Listing description."
          },
          "imgSrc": {
            "type": [
              "string",
              "null"
            ],
            "description": "Main photo URL."
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Photo URLs as published on the listing. Never re-hosted. Can be empty."
          },
          "photoCount": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Number of photos."
          },
          "brokerName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Listing brokerage."
          },
          "brokerPhone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Brokerage phone."
          },
          "agentName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Listing agent."
          },
          "agentPhone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Agent phone."
          },
          "agentLicenseNumber": {
            "type": [
              "string",
              "null"
            ],
            "description": "Agent license number."
          },
          "mlsId": {
            "type": [
              "string",
              "null"
            ],
            "description": "MLS listing number."
          },
          "mlsName": {
            "type": [
              "string",
              "null"
            ],
            "description": "MLS name."
          },
          "priceHistory": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ZillowPriceEvent"
            },
            "description": "Past events, newest first: date, event, price, pricePerSquareFoot, priceChangeRate, source. Can be empty."
          },
          "taxHistory": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ZillowTaxEvent"
            },
            "description": "Tax years: year, taxPaid, value (assessed), taxIncreaseRate, valueIncreaseRate. Can be empty."
          },
          "schools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ZillowSchool"
            },
            "description": "Nearby schools: name, rating, distance (miles), level, type, grades, link. Can be empty."
          },
          "virtualTourUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Virtual tour link."
          },
          "scrapedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the data was collected (ISO 8601)."
          }
        }
      },
      "ZillowPriceEvent": {
        "type": "object",
        "properties": {
          "date": {
            "type": [
              "string",
              "null"
            ],
            "description": "YYYY-MM-DD",
            "format": "date"
          },
          "event": {
            "type": [
              "string",
              "null"
            ],
            "description": "e.g. Listed for sale, Sold, Price change."
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "USD"
          },
          "pricePerSquareFoot": {
            "type": [
              "number",
              "null"
            ],
            "description": "USD"
          },
          "priceChangeRate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Change vs the previous event."
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "description": "e.g. the MLS."
          }
        }
      },
      "ZillowTaxEvent": {
        "type": "object",
        "properties": {
          "year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tax year."
          },
          "taxPaid": {
            "type": [
              "number",
              "null"
            ],
            "description": "USD"
          },
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "Assessed value, USD."
          },
          "taxIncreaseRate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Change vs the previous year."
          },
          "valueIncreaseRate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Change vs the previous year."
          }
        }
      },
      "ZillowSchool": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "School name."
          },
          "rating": {
            "type": [
              "number",
              "null"
            ],
            "description": "Rating."
          },
          "distance": {
            "type": [
              "number",
              "null"
            ],
            "description": "Miles."
          },
          "level": {
            "type": [
              "string",
              "null"
            ],
            "description": "e.g. Elementary."
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "description": "e.g. Public."
          },
          "grades": {
            "type": [
              "string",
              "null"
            ],
            "description": "e.g. PK-5."
          },
          "link": {
            "type": [
              "string",
              "null"
            ],
            "description": "School page."
          }
        }
      },
      "PropertyMeta": {
        "type": "object",
        "required": [
          "credits",
          "cached",
          "cache_key",
          "fetched_at",
          "source",
          "took_ms"
        ],
        "properties": {
          "credits": {
            "type": "integer",
            "description": "Credits billed for this lookup: 0 on a cache hit."
          },
          "cached": {
            "type": "boolean",
            "description": "True when served from the 24-hour cache."
          },
          "cache_key": {
            "type": "string",
            "description": "e.g. zpid:2064142765 or addr:..."
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the data was collected from Zillow (a cache hit keeps the original time)."
          },
          "source": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string",
                "enum": [
                  "apify"
                ]
              },
              "actor": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "took_ms": {
            "type": "integer"
          },
          "warning": {
            "type": "string",
            "description": "Present only when something needs checking, e.g. Zillow answered a link or zpid with a different property (a different zpid) than the one asked for. The property returned is still the one billed; it's cached under its own zpid, never under the one you asked for."
          }
        }
      },
      "PropertyResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ZillowProperty"
          },
          "meta": {
            "$ref": "#/components/schemas/PropertyMeta"
          }
        }
      },
      "ErrorBody": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "See the error table. Upstream codes may be added.",
            "examples": [
              "missing_param",
              "bad_param",
              "bad_body",
              "too_many_items",
              "missing_api_key",
              "invalid_api_key",
              "credits_exhausted",
              "spend_limit_reached",
              "not_found",
              "address_ambiguous",
              "unprocessable_input",
              "internal",
              "upstream_error",
              "upstream_cost_cap",
              "upstream_busy",
              "live_lookups_capped",
              "store_unavailable",
              "upstream_timeout"
            ]
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "meta"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          },
          "meta": {
            "type": "object",
            "properties": {
              "took_ms": {
                "type": "integer"
              }
            }
          }
        },
        "example": {
          "error": {
            "code": "not_found",
            "message": "No Zillow property matches this input"
          },
          "meta": {
            "took_ms": 11840
          }
        }
      },
      "BatchRequest": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "oneOf": [
                {
                  "type": "string",
                  "description": "A zillow.com link or an address."
                },
                {
                  "type": "object",
                  "description": "Exactly one of url or address.",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "address": {
                      "type": "string"
                    }
                  }
                }
              ]
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "for_sale",
              "sold",
              "for_rent"
            ]
          },
          "raw": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "BatchResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "description": "One result per item, same order.",
            "items": {
              "type": "object",
              "required": [
                "index",
                "ok"
              ],
              "properties": {
                "index": {
                  "type": "integer"
                },
                "ok": {
                  "type": "boolean"
                },
                "data": {
                  "$ref": "#/components/schemas/ZillowProperty"
                },
                "meta": {
                  "$ref": "#/components/schemas/PropertyMeta"
                },
                "error": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer"
              },
              "succeeded": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              },
              "cache_hits": {
                "type": "integer"
              },
              "credits": {
                "type": "integer"
              },
              "took_ms": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}