Open-source workbench for analyzing rental-yield data across Chinese cities — visualize properties on a map, compute yield / payback / occupancy KPIs.
中文 README · Live demo · Browser capture import
Yieldwise is a personal-scale real-estate analysis tool. It:
- Plots properties on a map alongside open-data communities and OSM building footprints
- Computes rental yield / payback / occupancy KPIs per district / community / building
- Lets you compare candidates against the local market in seconds
Run it locally on your machine. Your data never leaves it.
- Individual investors who want to look at rental yield distributions across districts before bidding on a property
- FinTech / urban-economics / real-estate finance students and researchers who need a quick analytical scaffolding for coursework or research
- Tinkerers who want to see what a "Bloomberg terminal for Chinese rentals" might look like as an open-source side project
Public real-estate data in China is scattered across government open-data portals, OSM, AMAP POIs, and PDF reports priced for institutions. Yieldwise stitches the open-source bits into one place.
No login-gated or unauthorized scraping — only public open data and browser-captured public pages.
Prerequisites: Python 3.13+ and a local Postgres + PostGIS instance. Postgres.app is the lightest option on macOS and bundles PostGIS.
git clone https://github.com/Leonard-Don/yieldwise.git
cd yieldwise
cp .env.example .env # edit .env to set AMAP_API_KEY (free, see below)
python3 -m venv .venv && source .venv/bin/activate
pip install -r api/requirements.txt
createdb yieldwise # one-time
psql yieldwise -c "CREATE EXTENSION IF NOT EXISTS postgis" # one-time
export $(grep -v '^#' .env | xargs)
uvicorn api.main:app --reload --port 8000Open http://localhost:8000 to see the map.
The schema is applied automatically on first DB use, so no manual psql -f is needed.
Need a free AMAP key for the map to render? Get one at lbs.amap.com.
Want to inspect the UI first? You can boot the demo/mock mode without creating a database:
python3 -m venv .venv && source .venv/bin/activate
pip install -r api/requirements.txt
ATLAS_ENABLE_DEMO_MOCK=1 uvicorn api.main:app --reload --port 8000This is only for local exploration. Real analysis should use Postgres/PostGIS plus open-data imports or public-page browser-scrape batches.
- Three workflows on one map: 收益猎手 (yield hunter) · 自住找房 (homebuyer) · 全市观察 (city overview)
- Candidate research loop for communities / buildings / districts, grouped by due review, target triggers, price/sample changes, evidence gaps, and shortlist state
- Candidate comparison + local memo export, including investment thesis, buy reasons, objections, evidence sources, pending checks, and next actions
- OSM + AMAP merged building footprints with quota-based community matching
- Ops refresh center for dry-running and executing staged reference/import/geo/metrics refresh jobs, with job history, anomaly triage, and geometry QA
| Layer | Source | License |
|---|---|---|
| Building footprints | OpenStreetMap | ODbL |
| Community boundaries | AMAP POI | Per AMAP ToS |
| District boundaries | Shanghai government open data | Open Government Data |
| Listings (sample) | Synthetic / browser-scraped demo set | Self-generated |
Yieldwise keeps the listing path to public-page browser scraping only: no manual data-entry UI and no auto-fetching of anything that requires authorization.
v1.0 self-use final (2026-05-05) — feature development frozen.
This version is intentionally closed as a personal local real-estate research workbench, not a commercial product. The complete self-use loop is:
- Discover opportunities on the map → inspect community / building / floor evidence → add to the candidate desk
- Set target price, target rent, target yield, and review due dates
- Track target triggers, price/yield changes, due reviews, evidence gaps, and same-floor sample changes through alerts
- Run candidate actions: complete review, defer review, shortlist, or reject
- Export local Markdown decision memos
- Maintain data quality, public sampling, review queues, and geometry QA from the backstage refresh center
Future work policy:
- No new feature development is planned
- Only blocking bugs, data-quality issues, or repeated real-use pain points should reopen development
- Shanghai-only; no multi-city abstraction. City constants live in
api/config/city.py - Backend, frontend, and full-browser regression tests are the closure validation baseline
The project is now frozen for self-use. Blocking bugs and data-quality issues can still be filed. See CONTRIBUTING.md.
MIT — see LICENSE. The MIT grant covers Yieldwise's source code only; data sources retain their own licenses (OSM ODbL, AMAP ToS, etc.).
For questions, feedback, or bug reports, please use GitHub Issues or Discussions.
If you find this useful, a star on the repo helps a lot.