新加坡房产爬虫

通过 HTTP 请求抓取新加坡房产列表，返回结构化 JSON 数据。

脚本位置

scripts/scrape.py

相对于本 SKILL 目录。运行方式如下：

python3 /scripts/scrape.py [OPTIONS]

依赖项

• Python 3.8+
• pip install curl_cffi beautifulsoup4 lxml
• 可选：设置环境变量 GOOGLE_MAPS_API_KEY 以计算通勤时间（需调用 Google Routes API）

快速开始

# 搜索环线（Circle Line）附近、月租低于 4000 新加坡元的 2 卧室公寓出租信息
python3 scripts/scrape.py 
  --listing-type rent --bedrooms 2 --max-price 4000 
  --property-type-group N --mrt-range CC:20-24 
  --output json

# JSON 输入模式（更适合 AI 工具调用）
python3 scripts/scrape.py --json '{
  "listingType": "rent",
  "bedrooms": 2,
  "maxPrice": 4000,
  "propertyTypeGroup": ["N"],
  "mrtStations": ["CC20","CC21","CC22","CC23","CC24"]
}'

# 试运行：仅打印生成的 URL，不执行实际爬取
python3 scripts/scrape.py --dry-run --listing-type rent --bedrooms 3

筛选参数

卧室/房间逻辑说明

• --entire-unit-or-room ent --bedrooms 4 → 四卧室整套单位
• --entire-unit-or-room ent --bedrooms 0 → 开间（studio）
• --bedrooms -1 --room-type master --room-type common → 出租单间（主卧或共用房）
• 省略 --entire-unit-or-room → 同时返回整套单位与单间

MRT 站点语法

• 单个站点：--mrt-station CC20
• 区间（同一条线路）：--mrt-range CC:20-24（展开为 CC20、CC21、CC22、CC23、CC24）
• 多条线路：使用多个 --mrt-station 或 --mrt-range 标志
• JSON 输入中："mrtStations": ["CC20", "EW15"] 或 [["CC", [20, 24]]]（元组格式）

完整有效的 MRT 站点代码列表（约 213 个）详见 references/params.md。

执行参数

JSON 输入模式

使用 --json 将筛选条件作为 JSON 字符串传入。键名采用 camelCase 风格，与 URL 参数名一致：

python3 scripts/scrape.py --json '{
  "listingType": "rent",
  "propertyTypeGroup": ["N"],
  "bedrooms": 2,
  "bathrooms": 2,
  "maxPrice": 4000,
  "mrtStations": ["EW16", "EW17", "EW18"],
  "distanceToMRT": 0.75,
  "minTopYear": 1990
}'

也可从文件加载：--config filters.json

输出格式

标准输出为 JSON 数组（无结果时返回空数组 []）：

[
  {
    "id": "23744236",
    "name": "Kingsford Waterbay",
    "price": "S$ 3,900 /mo",
    "psf": "S$ 4.53 psf",
    "address": "68 Upper Serangoon View",
    "bedrooms": "2",
    "bathrooms": "2",
    "area": "861 sqft",
    "type": "Condominium",
    "built": "Built: 2018",
    "availability": "Ready to Move",
    "mrt_distance": "14 min (1.15 km) from SE4 Kangkar LRT Station",
    "list_date": "Listed on Feb 15, 2026 (2d ago)",
    "agent": "May Chong",
    "agency": "PROPNEX REALTY PTE. LTD.",
    "headline": "Perfect work from home unit, river facing, unblocked high floor cozy",
    "link": "https://www.propertyguru.com.sg/listing/for-rent-kingsford-waterbay-23744236",
    "commute_driving": "25 mins",
    "commute_transit": "45 mins"
  }
]

退出码

• 0：成功，且找到结果
• 1：错误（参数非法、爬取失败等）
• 2：成功，但未找到任何房源

AI Agent 调用注意事项

当从 AI Agent 中调用本脚本时，请注意以下事项：

1. 建议使用 --output json 获取结构化输出（当输出被管道重定向时默认即为 JSON）
2. 建议使用 --json 标志传递参数，比逐个使用 CLI 标志更简洁易维护
3. 可使用 --dry-run 预览将要访问的搜索 URL，确认无误后再执行爬取
4. 如用户需要更多结果，可使用 --pages N 指定爬取页数（每页约含 20 条房源）
5. 使用 --commute-to 并指定目标地址，可为每条房源分别计算驾车及公共交通通勤时间（需配置 GOOGLE_MAPS_API_KEY）。若未设置该环境变量，则自动静默忽略通勤字段
6. 当 GOOGLE_MAPS_API_KEY 缺失或通勤时间计算失败时，commute_driving 和 commute_transit 字段值为空字符串 ""