sg-property-scraper（SG 财产刮刀）

Singapore Property Scraper

Scrapes Singapore property listings via HTTP requests. Returns structured JSON.

Script Location

scripts/scrape.py

Relative to this SKILL directory. Run with:

python3 <SKILL_DIR>/scripts/scrape.py [OPTIONS]

Dependencies

• Python 3.8+
• pip install curl_cffi beautifulsoup4 lxml
• Optional: GOOGLE_MAPS_API_KEY env var for commute time calculation (Google Routes API)

Quick Start

# Search 2BR condos for rent under SGD 4000 near Circle Line
python3 scripts/scrape.py \
  --listing-type rent --bedrooms 2 --max-price 4000 \
  --property-type-group N --mrt-range CC:20-24 \
  --output json

# JSON input mode (easier for AI tools)
python3 scripts/scrape.py --json '{
  "listingType": "rent",
  "bedrooms": 2,
  "maxPrice": 4000,
  "propertyTypeGroup": ["N"],
  "mrtStations": ["CC20","CC21","CC22","CC23","CC24"]
}'

# Dry run: print URL only without scraping
python3 scripts/scrape.py --dry-run --listing-type rent --bedrooms 3

Filter Parameters

Bedroom/Room Logic

• --entire-unit-or-room ent --bedrooms 4 = 4-bedroom entire unit
• --entire-unit-or-room ent --bedrooms 0 = studio
• --bedrooms -1 --room-type master --room-type common = room rental (master or common room)
• Omit --entire-unit-or-room to show both entire units and rooms

MRT Station Syntax

• Individual station: --mrt-station CC20
• Range (same line): --mrt-range CC:20-24 (expands to CC20, CC21, CC22, CC23, CC24)
• Multiple lines: use multiple flags
• In JSON: "mrtStations": ["CC20", "EW15"] or [["CC", [20, 24]]] (tuple format)

See references/params.md for the complete list of ~213 valid MRT station codes.

Execution Parameters

JSON Input Mode

Pass filters as a JSON string with --json. Keys use camelCase matching the URL parameter names:

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

Or load from a file: --config filters.json

Output Format

JSON array on stdout (empty [] if no results):

[
  {
    "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"
  }
]

Exit Codes

• 0: Success, results found
• 1: Error (bad parameters, scraping failure)
• 2: Success but zero listings found

Agent Usage Notes

When calling this script from an AI agent:

1. Use --output json for structured output (default when piped)
2. Use --json flag for easier parameter passing than individual CLI flags
3. Use --dry-run to preview the search URL before scraping
4. Use --pages N if the user wants more results (each page has ~20 listings)
5. Use --commute-to with a destination address to calculate commute times (driving + transit) for each listing. Requires GOOGLE_MAPS_API_KEY env var. If the key is not set, commute fields are omitted silently.
6. commute_driving and commute_transit fields are empty strings "" when API key is missing or calculation fails