sg-property-scraper_知识管理 skill-PHP中文网

sg-property-scraper

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

搜索新加坡房产租售列表，支持灵活筛选。适用于查询新加坡房产、寻找租售房源等请求。

新加坡地产 Singapore scraper.

功能概述

新加坡地产 Singapore scraper.是一项面向实际任务的技能，主要用于Scrapes 新加坡地产通过 HTTP 请求上市.；Returns structure JSON..；

核心要点

Script 位置. 向此 SKILL 目录过渡.；
Run 与 :.；
Dependenities.；

使用与执行

Python 3.8+；pip in。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

结果检查与注意事项

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。

新加坡房产爬虫

通过 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

筛选参数

命令行标志	URL 参数名	类型	说明
`--listing-type`	`listingType`	字符串	`rent`（出租）或 `sale`（出售）
`--property-type-group`	`propertyTypeGroup`	字符串（可重复使用）	`N`=Condo（公寓），`L`=Landed（有地住宅），`H`=HDB（组屋）
`--entire-unit-or-room`	`entireUnitOrRoom`	字符串	`ent` 表示仅显示整套单位；省略该参数则同时返回整套单位与单间
`--room-type`	`roomType`	字符串（可重复使用）	`master`（主卧）、`common`（共用房）、`shared`（合住房间）
`--bedrooms`	`bedrooms`	整数	`-1`=单间，`0`=开间（studio），`1`–`5`=卧室数量
`--bathrooms`	`bathrooms`	整数	浴室数量
`--min-price`	`minPrice`	整数	最低价格（单位：SGD）
`--max-price`	`maxPrice`	整数	最高价格（单位：SGD）
`--min-size`	`minSize`	整数	最小面积（单位：sqft）
`--max-size`	`maxSize`	整数	最大面积（单位：sqft）
`--min-top-year`	`minTopYear`	整数	最早完工年份（TOP Year）
`--max-top-year`	`maxTopYear`	整数	最晚完工年份（TOP Year）
`--distance-to-mrt`	`distanceToMRT`	浮点数	距最近地铁站的最大距离（单位：km），例如 `0.5`、`0.75`
`--availability`	`availability`	整数	可用性筛选条件
`--mrt-station`	`mrtStations`	字符串（可重复使用）	MRT 站点代码，例如 `CC20`
`--mrt-range`	`mrtStations`	字符串（可重复使用）	MRT 范围，例如 `CC:20-24`
`--sort`	`sort`	字符串	`date`（上架日期）、`price`（价格）、`psf`（每平方英尺单价）、`size`（面积）
`--order`	`order`	字符串	`asc`（升序）、`desc`（降序）
`--commute-to`	`commuteTo`	字符串	通勤目的地地址（需配置 `GOOGLE_MAPS_API_KEY`）

卧室/房间逻辑说明

--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。

执行参数

命令行标志	说明
`--pages N`	要爬取的页数（默认值：1）
`--dry-run`	构建并打印 URL，跳过实际爬取
`--no-validate`	跳过参数校验
`--timeout N`	HTTP 请求超时时间（单位：秒，默认值：30）
`--raw-param K=V`	额外 URL 查询参数（可重复使用）
`--output json\|text\|none`	输出格式（当输出被管道重定向时默认为 json）
`--verbose`	启用详细日志（输出至 stderr）

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 中调用本脚本时，请注意以下事项：

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