description

description is the listing's text: the remarks the agent or landlord wrote about the home, as Zillow publishes them.

What it means

The text comes back exactly as published, with its capitals, punctuation and spelling. Some remarks run to several paragraphs, so store it in a text column without a short length limit.

For homes that aren't listed, the page often carries a short generated summary instead of agent remarks: a sentence giving the square footage, bedrooms and bathrooms. That text describes facts the response already has in other fields.

Listing remarks are useful input for search, tagging or a language model that summarises a home. They are marketing copy, so treat claims inside them, such as recent upgrades or school names, as the seller's words.

The text can hold facts that no other field carries. A recorded Austin listing opened its remarks with a notice that the home was part of the city's affordable housing program, with buyer requirements, which appears nowhere else in the response. Keep the text even when you also use the structured fields.

Recorded example

{
  "description": "West Loop Corner Condo with Private Terrace. Highly sought after two bedroom, two bathroom corner unit featuring a private 575 sq. ft."
}

{
  "homeStatus": "OTHER",
  "description": "This 2200 square foot single family home has 3 bedrooms and 3.0 bathrooms."
}

Values are copied from recorded lookups of public Zillow pages, with the other fields of data left out; long lists are cut to their first entries and long text to its opening words. They show the shape and typical values, not today's data for these homes.

When it is null

• The page has no description. Some apartment building rentals and some land listings had none in our recorded lookups.
• Whitespace-only text is returned as null.

Read it in code

Send a Zillow link, a zpid or an address to GET /v1/zillow/property with your key in the x-api-key header, then read the field from data:

curl -sG "https://api.propertiesapi.com/v1/zillow/property" \
  -H "x-api-key: $PROPERTIESAPI_KEY" \
  --data-urlencode "url=https://www.zillow.com/homedetails/1704-Shelbourne-Dr-Austin-TX-78752/29412761_zpid/" \
  | jq '.data | {description}'

import os
import requests

r = requests.get(
    "https://api.propertiesapi.com/v1/zillow/property",
    params={"url": "https://www.zillow.com/homedetails/1704-Shelbourne-Dr-Austin-TX-78752/29412761_zpid/"},
    headers={"x-api-key": os.environ["PROPERTIESAPI_KEY"]},
    timeout=120,
)
r.raise_for_status()
home = r.json()["data"]
text = home["description"] or ""
print(len(text), "characters")
print(text[:200])

const url = "https://www.zillow.com/homedetails/1704-Shelbourne-Dr-Austin-TX-78752/29412761_zpid/";
const res = await fetch(
  `https://api.propertiesapi.com/v1/zillow/property?url=${encodeURIComponent(url)}`,
  { headers: { "x-api-key": process.env.PROPERTIESAPI_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { data: home } = await res.json();
const text = home.description ?? "";
console.log(text.length, "characters");
console.log(text.slice(0, 200));

Common mistakes

• Rendering the text as HTML. Escape it; it is plain text.
• Using a generated off-market summary as if an agent wrote it.
• Extracting facts such as square footage from the text when a structured field already has them.

Related

• photos, imgSrc, photoCount and virtualTourUrl
• Listing agent, broker and MLS
• homeStatus and statusText
• Every field of the property endpoint
• Guide: Enrich a Property Address List with Python and Export to CSV
• All response fields

Zillow is a trademark of Zillow, Inc. PropertiesAPI is an independent service and is not affiliated with, endorsed by or sponsored by Zillow.