findhomes-cli

Command-line tool for searching South African residential property listings, historical sales, and market data via the FindHomes API.

Handles location resolution, isochrone commute searches, property details, market screening, and investment analysis — all from the terminal, with results also written to temp JSON files for downstream use.

Install

npm install -g findhomes-cli

Or run ad-hoc without installing:

npx findhomes-cli search --location "Camps Bay" --beds-min 3

Setup

Set your API key as an environment variable:

export FIND_HOMES_X_API_KEY="your-api-key-here"

Requires Node.js 18 or later (uses native fetch, parseArgs, and top-level await).

Commands

| Command | Purpose | Example | |---------|---------|---------| | resolve | Suburb/city names → location IDs | findhomes resolve "Camps Bay, Sea Point" | | search | Find for-sale listings | findhomes search --location "Sea Point" --beds-min 2 --price-max 5000000 | | details | Full property info by ID | findhomes details <uuid1>,<uuid2> | | sales | Historical sale transactions + stats | findhomes sales --location "Wynberg" --date-min 2025-01-01 | | isochrone | Generate commute-time polygon | findhomes isochrone --destination "V&A Waterfront" --minutes 20 | | isochrone-intersect | Intersect two isochrone polygons | findhomes isochrone-intersect --iso1 a.json --iso2 b.json | | screen | Batch market screening (parallel) | findhomes screen --locations "Wynberg,Plumstead,Kenilworth" | | shortlist | Manage property shortlist | findhomes shortlist add <uuid> --notes "love the view" |

Search flags

• --location <name> or --l-ids <id1,id2> or --polygon-file <path>
• --beds-min, --beds-max, --baths-min, --price-min, --price-max
• --sort-by <price|price_per_m2|date_listed> with --sort-direction <asc|desc>
• --show-por <true|false> — include price-on-request listings (default true)
• --visual-search-description "..." — rank by visual similarity
• --limit <n>

When --sort-by is omitted, results are ranked by visual similarity (if a visual description is given) or by date_listed descending.

Example workflows

Simple suburb search

findhomes resolve "Camps Bay"
findhomes search --l-ids <id> --beds-min 3 --price-max 15000000
findhomes details <uuid>

Isochrone (commute-based) search

findhomes isochrone --destination "V&A Waterfront" --minutes 20 -o /tmp/iso.json
findhomes search --polygon-file /tmp/iso.json --beds-min 2

Dual-commute overlap

findhomes isochrone --destination "Place A" --minutes 20 -o /tmp/iso1.json
findhomes isochrone --destination "Place B" --minutes 25 -o /tmp/iso2.json
findhomes isochrone-intersect --iso1 /tmp/iso1.json --iso2 /tmp/iso2.json -o /tmp/overlap.json
findhomes search --polygon-file /tmp/overlap.json

Market screening

findhomes screen --locations "Wynberg,Plumstead,Kenilworth,Bergvliet" --date-min 2025-01-01

Output files

The CLI writes the full JSON payload of most queries to temp files for easy piping into other tools:

• /tmp/findhomes_results.json — latest search results
• /tmp/findhomes_sales.json — latest sales query
• /tmp/findhomes_screen.json — latest screening data
• /tmp/isochrone.json — latest isochrone polygon (when -o omitted)

Persistent data (~/.findhomes/)

• suburb_stats.json — cached market stats (7-day TTL; use --no-cache to refresh)
• search_log.jsonl — append-only log of every search
• shortlist.json — saved property shortlist with notes

Limitations

• For-sale only — no rental listings.
• South Africa only — FindHomes covers SA residential property.
• GET-only API — extremely large polygons may exceed URL limits. The CLI auto-simplifies, but for very large areas prefer --l-ids.

License

Proprietary — all rights reserved. See LICENSE.

This package is source-available on the public npm registry for convenient installation, but is not open source. You may install and run it for personal or internal use with a valid FindHomes API key. Copying, modifying, redistributing, or building derivative works is not permitted without prior written consent from the author.

For licensing inquiries, contact: [email protected]