# Zillow 邮编房源搜索 API (zillow.zip_search)

- Canonical page: https://everyinfra.com/zillow-api/zip_search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "zillow", "action": "zip_search", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 200 per call
- Mode: sync; add "mode": "async" for slow tasks

Zillow 邮编房源搜索按 `zip` 列出一个或几个美国邮编下的房源，默认 20 条，单次最多 200 条。它和关键词搜索不同，带状态开关：`for_sale_by_agent` 经纪人挂牌，`for_sale_by_owner` 房主自售，`for_rent` 出租，`sold` 已售，可以组合。它回答「这几个邮编里在卖什么、租什么、成交过什么」，适合邮编范围内的行情摸底。

`zip` 推荐写成五位字符串，这样不会丢掉前导零；也接受逗号或空白分隔的字符串，以及邮编数组。传多个邮编时，`limit` 是这次调用合计返回的条数，不是每个邮编各返回这么多；多个邮编的计量以实际请求的计费规则为准。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=zillow&action=zip_search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| zip | not declared | yes | not declared | 美国邮编，推荐五位字符串以保留前导零；也接受逗号/空白分隔字符串或邮编数组。多个邮编的目标计量须以实际请求计费规则为准。传多个邮编时，limit 是这次调用合计返回的条数，不是每个邮编各返回 limit 条。 |
| days_on_zillow | enum: 1 / 12m / 14 / 24m / 30 / 36m / 6m / 7 / 90 | no | not declared | 时间预设：1/7/14/30/90 为天数，6m/12m/24m/36m 为月数；选择已售时表示距成交时间，不接受任意整数天数。 |
| for_rent | not declared | no | not declared | 是否包含出租房源，布尔值；不是独占开关，可与其他状态组合。 |
| for_sale_by_agent | not declared | no | not declared | 是否包含经纪人挂牌房源，布尔值；未显式选择任何状态时默认 true。 |
| for_sale_by_owner | not declared | no | not declared | 是否包含房主自售房源，布尔值；不能据此推断交易完全没有佣金。 |
| max_price | not declared | no | not declared | 最高房源价格，整数；与 min_price 配合。带小数时向上取整。 |
| min_price | not declared | no | not declared | 最低房源价格，整数；价格随出租或出售状态分别为租金或售价。带小数时向下取整。 |
| sold | not declared | no | not declared | 是否包含已售房源，布尔值；已售状态不保证每个地区都有公开成交金额。 |
| limit | integer (1–200) | no | 20 | 这次调用最多返回的条数，整数，1–200；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| zpid | Zillow 内部房源 ID，该站的主键。 |
| url | 该记录在原平台上的可访问链接。 |
| status | 房源状态，与 home_status 同义。 |
| status_type | 状态分类，比 status 更粗的一层。 |
| price | 价格数值，不含货币符号；币种见 currency。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| address | 详细地址，原文透传。 |
| street | 街道地址。 |
| city | 城市名，用原平台的语言书写，未做中英归一。 |
| state | 州。 |
| zipcode | 邮编。 |
| latitude | 纬度。 |
| longitude | 经度。 |
| beds | 卧室数量，与 bedrooms 同义。 |
| baths | 卫生间数量，与 bathrooms 同义。 |
| area_sqft | 室内面积，单位平方英尺（1 平方米 ≈ 10.76 平方英尺）。 |
| home_type | 房屋类型，原平台分类（SINGLE_FAMILY / CONDO / TOWNHOUSE 等）。 |
| home_status | 房源状态（FOR_SALE / FOR_RENT / SOLD / PENDING 等）。 |
| zestimate | Zillow 估价模型给出的房屋估值。**不是成交价也不是挂牌价**。 |
| rent_zestimate | Zillow 估算的月租金，同样是模型值不是实际租金。 |
| tax_assessed_value | 税务评估价值，政府计税用，通常低于市场价。 |
| lot_area_value | 地块面积数值，单位见 lot_area_unit，两个字段要一起读。 |
| lot_area_unit | 地块面积单位（sqft 平方英尺 / acres 英亩）。 |
| days_on_zillow | 在 Zillow 上的挂牌天数。数值大通常意味着不好卖或定价偏高。 |
| broker_name | 挂牌经纪公司名称。 |
| is_zillow_owned | 是否为 Zillow 自持房源（Zillow Offers 收购的房子）。 |
| has_3d_model | 是否有 3D 看房模型。 |
| has_video | 是否有视频。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "zillow",
  "action": "zip_search",
  "params": {
    "zip": "78701"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "zillow",
        "action": "zip_search",
        "params": {
            "zip": "78701",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 233. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "zillow",
  "action": "zip_search",
  "results": [
    {
      "zpid": "89552472",
      "beds": 1,
      "baths": 1,
      "area_sqft": 801,
      "is_zillow_owned": false,
      "has_3d_model": true,
      "has_video": false,
      "platform": "zillow"
    },
    {
      "zpid": "•••",
      "beds": 2,
      "baths": 2,
      "area_sqft": 793,
      "is_zillow_owned": false,
      "has_3d_model": false,
      "has_video": false,
      "platform": "zillow"
    }
  ],
  "count": 233,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 不选任何状态会返回什么？

返回经纪人挂牌的房源：没有显式选择任何状态时，`for_sale_by_agent` 默认为 true。`for_rent` 不是独占开关，可以和其他状态组合；价格区间 `min_price`、`max_price` 随房源状态分别当作租金或售价。

### `days_on_zillow` 怎么填？

取 `1`、`7`、`14`、`30`、`90` 表示天数，取 `6m`、`12m`、`24m`、`36m` 表示月数，不接受任意整数天数。选已售时，它表示距成交的时间。这个参数和返回字段 `days_on_zillow` 同名，但字段是每套房已经挂牌的天数。

### 已售房源一定有成交价吗？

不保证。`sold` 只是把已售房源纳入结果，已售状态不保证每个地区都有公开成交金额。`for_sale_by_owner` 也只表示房主自售，不能据此推断交易完全没有佣金。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=zillow
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
