sg-property-scraper

# 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:
```bash
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

```bash
# 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

| Flag | URL Param | Type | Description |
|------|-----------|------|-------------|
| `--listing-type` | `listingType` | string | `rent` or `sale` |
| `--property-type-group` | `propertyTypeGroup` | string (repeatable) | `N`=Condo, `L`=Landed, `H`=HDB |
| `--entire-unit-or-room` | `entireUnitOrRoom` | string | `ent` for entire unit only; omit for all |
| `--room-type` | `roomType` | string (repeatable) | `master`, `common`, `shared` |
| `--bedrooms` | `bedrooms` | int | `-1`=room, `0`=studio, `1`-`5` |
| `--bathrooms` | `bathrooms` | int | Number of bathrooms |
| `--min-price` | `minPrice` | int | Minimum price (SGD) |
| `--max-price` | `maxPrice` | int | Maximum price (SGD) |
| `--min-size` | `minSize` | int | Minimum size (sqft) |
| `--max-size` | `maxSize` | int | Maximum size (sqft) |
| `--min-top-year` | `minTopYear` | int | Minimum TOP year |
| `--max-top-year` | `maxTopYear` | int | Maximum TOP year |
| `--distance-to-mrt` | `distanceToMRT` | float...

# SG Property Scraper

Search Singapore property rental and sale listings from the command line. Supports flexible filters (location, price, bedrooms, MRT proximity, etc.) and optional commute time calculation via Google Routes API.

## Setup

```bash
# Python 3.8+ required
pip install curl_cffi beautifulsoup4 lxml
```

Optional — for commute time calculation:

```bash
export GOOGLE_MAPS_API_KEY="your-key-here"  # needs Routes API enabled
```

## Usage

### CLI flags

```bash
# 2BR rentals under SGD 4000
python3 scripts/scrape.py --listing-type rent --bedrooms 2 --max-price 4000

# Condos near Circle Line MRT stations
python3 scripts/scrape.py --listing-type rent --property-type-group N --mrt-range CC:20-24

# With commute time to office
GOOGLE_MAPS_API_KEY=xxx python3 scripts/scrape.py \
  --listing-type rent --bedrooms 2 --max-price 4000 \
  --commute-to "1 Raffles Place, Singapore" \
  --output text
```

### JSON mode

```bash
python3 scripts/scrape.py --json '{
  "listingType": "rent",
  "bedrooms": 2,
  "maxPrice": 4000,
  "propertyTypeGroup": ["N"],
  "mrtStations": ["CC20", "CC21", "CC22"],
  "commuteTo": "1 Raffles Place, Singapore"
}'
```

### Dry run (preview URL without scraping)

```bash
python3 scripts/scrape.py --dry-run --listing-type rent --bedrooms 3
```

## Filter Parameters

| Flag | Type | Description |
|------|------|-------------|
| `--listing-type` | string | `rent` or `sale` |
| `--property-type-group` | string | `N`=Condo, `L`=Landed, `H`=HDB (repeatable) |
| `--bedrooms` | int | `-1`=room, `0`=studio, `1`-`5` |
| `--bathrooms` | int | Number of bathrooms |
| `--min-price` / `--max-price` | int | Price range in SGD |
| `--min-size` / `--max-size` | int | Size range in sqft |
| `--mrt-station` | string | MRT code e.g. `CC20` (repeatable) |
| `--mrt-range` | string | MRT range e.g. `CC:20-24` (repeatable) |
| `--distance-to-mrt` | float | Max distance to MRT in km |
| `--commute-to` | string | Destination for commute calculation |
| `--sort` |...