Lou·Ka

Tous les logements à louer

Chercher un appartement au Québec, c'est ouvrir des dizaines de sites différents — chacun avec sa navigation, ses filtres, son format. **Lou·Ka retourne le problème** : un **connecteur dédié par gestionnaire immobilier** visite chaque site, **normalise chaque annonce** vers un schéma unique et **détecte les changements en continu** (synchronisation périodique + hash de contenu → ajouts, mises à jour et retraits automatiques ; une annonce disparue répond `410 Gone`). Chaque fiche renvoie vers l'annonce originale du gestionnaire via une passerelle de sortie transparente (`/passerelle/{uid}`). Pour qui ? Les locataires qui cherchent (recherche filtrée, carte 3D, fiches complètes), les curieux du marché (observatoire des loyers, rapports PDF) et les gestionnaires (pages réclamables). **En chiffres (au 2026-08-24)** : 45 762 annonces actives publiées, 281 sources recensées, 250 connecteurs (221 location long terme + 29 court terme), 1 233 villes, 11 régions, 97,4 % des annonces géolocalisées, loyer médian 1 700 $ — plus **41 460 séjours court terme** (chalets, Airbnb…) dans la section `/court-terme`. ## Visite guidée

_{Accueil — recherche et univers Lou·Ka (desktop)}	_{Accueil — version mobile}
_{Étape 1 · Cherchez depuis l'accueil}	_{Étape 2 · Parcourez les résultats d'une ville}
_{Étape 3 · Ouvrez la fiche d'un logement}	_{Étape 4 · Suivez le marché sur /stats}
_{Résultats de recherche — liste d'annonces filtrée}	_{Vue carte 3D — clusters par prix moyen (ka-maps)}
_{Fiche logement — photos, digest, badge marché, quartier}	_{Registre des sources — chaque gestionnaire et sa synchro}
_{Répertoire des villes (pages SEO)}	_{Page ville — Québec}
_{Observatoire du marché — loyers médians, KPI}	_{Accueil — variante pleine page}
_{Accueil mobile — variante pleine page}

### App iOS native

_Accueil	_Découverte	_Carte
_{Fiche logement}	_Statistiques	_Sources

## Fonctionnalités - **Recherche filtrée** — ville, quartier, type (3½, 4½…), loyer min/max, animaux, meublé, superficie, texte libre. - **Vue carte 3D** — Lou-Ka Maps (framework `@groupe-ka/ka-maps`, moteur Mapbox GL JS) : clusters par prix moyen, « Rechercher dans cette zone », bascule 3D/2D, synchro liste ↔ carte. - **Fiches complètes** — toutes les photos, digest structuré de la description (text mining regex FR, aucun LLM), badge marché, historique de prix (`price_log`), fiche PDF avec QR code. - **Couches de données de quartier** — recensement 2021, registre des loyers (57 433 déclarations géocodées), inondation (BDZI), criminalité (SPVM, 12 mois par catégorie), qualité de l'air (RSQAQ/PST), prix de l'essence, commerces et transport en commun (métro/REM aux couleurs officielles), estimation Hydro-Québec live, **KA Scores** (95,5 % du parc couvert au 2026-08-24). - **Location court terme** — section isolée `/court-terme` (sous-système `louka/shortterm/`, API `/api/ct/*`) : chalets, Airbnb (quadrillage carte quadtree limité à la frontière du Québec), Vrbo, Booking… 41 460 séjours, 22 sources actives sur 38 recensées, 27 régions (au 2026-08-24) ; SEO complet (JSON-LD `VacationRental`, sitemaps `sitemap-ct-N.xml`). - **Pages villes SEO** — `/villes`, `/ville/{slug}`, `/ville/{slug}/{type}` en SSR léger, sitemaps dynamiques (chunks de 10 000), JSON-LD (`RealEstateListing` + `Offer` CAD), vrais `404`/`410`. - **Observatoire du marché** — KPI temps réel, loyers médians par région/ville/taille, panneaux territoire (registre des loyers, population, essence), rapport de marché PDF multi-pages (`/api/stats/rapport.pdf`) et rapports PDF personnalisés (catalogue + `ReportBuilder`). - **Registre des sources** — chaque gestionnaire, son statut, sa dernière synchro ; toute source non connectable est documentée avec sa raison dans `data/sources.json` (281 entrées recensées). - **Qualité éditoriale** — porte de pertinence (quarantaine des stationnements, garages, locaux commerciaux, locations à la nuit) : 59 668 annonces publiées / 1 175 en quarantaine, complétude moyenne 91,4 % (au 2026-08-24). - **Comptes & SSO KA** — « Se connecter avec KA » via le hub groupe-ka.com (JWT HS256, `ka_id` émis par le hub) + Google OAuth direct ; favoris synchronisés vers « Mon univers Ka » ; pages gestionnaires réclamables (`/g/{source_id}`). - **Widget KA Agent** — bulle de chat IA du Groupe KA intégrée au site (déplaçable, position mémorisée). - **PWA installable** + app iOS SwiftUI 100 % native (dépôt séparé `lou-ka-ios` sur spbgit). - **Robustesse** — garde-fou anti-dérive (`DRIFT_RATIO = 0.25`, `louka/db.py`) : si une source retourne soudainement beaucoup moins d'annonces, les retraits sont suspendus au lieu de vider l'inventaire ; chaîne de fetch anti-bot résiliente (Oxylabs → Scrapfly → Bright Data). ## API (endpoints principaux) Servis par `louka/web.py` (FastAPI) sur le port 8095. ### Location long terme | Méthode | Endpoint | Rôle | |---|---|---| | `GET` | `/api/search` | recherche unifiée liste ↔ carte (mêmes filtres, même compteur) | | `GET` | `/api/listings` · `/api/listings/{uid}` | annonces paginées + fiche détaillée (`410 Gone` si retirée) | | `GET` | `/api/listings.geojson` | flux GeoJSON pour la carte 3D | | `GET` | `/api/listings/{uid}/pdf` | fiche PDF avec QR code | | `GET` | `/api/facets` · `/api/sources` | facettes de filtres, registre des sources | | `GET` | `/api/fairvalue/{uid}` | badge marché (juste prix) d'une annonce | | `GET` | `/api/rdl` · `/api/inondation` · `/api/air` · `/api/gaz` · `/api/commerces` · `/api/hydro` | couches de quartier : registre des loyers, BDZI, qualité de l'air, essence, commerces/transport, estimation Hydro-Québec | | `GET` | `/api/kascores/stats` | statistiques du moteur KA Scores | | `GET` | `/api/stats` · `/detailed` · `/dashboard` · `/report` · `/catalog` | observatoire : KPI, détail, tableau de bord, rapports | | `POST` | `/api/stats/report/custom` | rapport PDF personnalisé (ReportBuilder) | | `GET` | `/api/stats/rapport.pdf` | rapport de marché PDF multi-pages | | `POST` | `/api/sync` | déclenchement d'une synchronisation | | `GET` | `/doc/` | guide d'utilisation en ligne | ### Location court terme (`/api/ct`, préfixe du sous-système `louka/shortterm/`) | Méthode | Endpoint | Rôle | |---|---|---| | `GET` | `/api/ct/listings` · `/api/ct/listings/{uid}` | séjours paginés + fiche détaillée | | `GET` | `/api/ct/listings.geojson` | flux GeoJSON de la carte court terme | | `GET` | `/api/ct/facets` · `/api/ct/sources` | facettes, registre des sources court terme | | `GET` | `/api/ct/stats` | KPI court terme (total, sources, régions, prix/nuit) | | `POST` | `/api/ct/sync` | déclenchement d'une synchronisation court terme | ## Architecture Pipeline : **connecteurs → normalisation → déduplication → SQLite → API/SSR/frontend**. - **Backend Python 3.14 / FastAPI / Uvicorn** (`louka/web.py`) : API JSON + service du build Vite + SSR SEO (`louka/seo.py`). - **SQLite (WAL)** (`louka/db.py`) : migrations auto, upsert par hash de contenu, anti-dérive ; bases annexes dans `data/` (quartier, air, gaz, hydro, commerces, inondation…). - **250 connecteurs** auto-découverts : 221 long terme (`louka/connectors/`) + 29 court terme (`louka/shortterm/connectors/`), extraction directe / Firecrawl / Scrapfly / Bright Data / acteurs Apify maison selon la source. - **Enrichissement** : géocodage (Nominatim + Adresses Québec), POI OSM, stats de quartier, KA Scores, estimation Hydro-Québec. - **Frontend React 18 + Vite + TypeScript** (`frontend/`), cartographie `@groupe-ka/ka-maps` (Mapbox GL). - **CLI `run.py`** : `sync` · `watch` · `sync-ct` · `watch-ct` · `serve` · `geocode` · `quality` · `imgaudit` · `fairvalue` · `poi` · `quartier` · `kascores` · `rdl` · `air-refresh` · `gaz-refresh` · `hydro-precompute` · `record` (fixtures HTTP pour tests hors-ligne). Processus PM2 sur le nœud : | Processus | Commande réelle | Rôle | Cadence | |---|---|---|---| | `lou-ka-web` | `.venv/bin/python run.py serve 8095` | serveur FastAPI/Uvicorn (API + frontend + SSR) sur le port **8095** | continu | | `lou-ka-sync` | `.venv/bin/python run.py watch 60` | boucle de resynchronisation des connecteurs long terme | cycle de 60 min | | `lou-ka-ngrok` | `ngrok http --url=www.lou-ka.com 8095` | tunnel ngrok vers **www.lou-ka.com** | continu | La section court terme se resynchronise via `run.py watch-ct` (défaut 360 min) ou à la demande (`run.py sync-ct`, `POST /api/ct/sync`). ## Démarrage rapide ```bash # Backend (Python 3.14) python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # Frontend (nécessite le framework ka-maps bâti à côté : ../ka-maps) cd frontend && npm install && npm run build && cd .. .venv/bin/python run.py sync # ingestion (toutes les sources ou une liste) .venv/bin/python run.py sync-ct # ingestion court terme .venv/bin/python run.py serve 8095 # API + frontend sur http://localhost:8095 .venv/bin/python run.py watch 60 # resynchronisation en boucle (minutes) # Tests (pytest + fixtures HTTP rejouables hors-ligne) .venv/bin/python -m pytest tests/ ``` En développement frontend : `cd frontend && npm run dev` (Vite sur `:5173`, proxy `/api`). ## Variables d'environnement Aucun secret dans le repo — tout passe par l'environnement du nœud. Noms attendus : | Variable | Rôle | |---|---| | `SCRAPFLY_KEY` · `FIRECRAWL_API_KEY` · `APIFY_TOKEN` | extraction anti-bot / rendu / acteurs Apify maison | | `BRIGHTDATA_API_KEY` · `BRIGHTDATA_ZONE` | Web Unlocker Bright Data (repli anti-bot) | | `OXYLABS_PROXY` · `OXYLABS_PROXY_USER` · `OXYLABS_PROXY_PASS` | proxies résidentiels (1er maillon de la chaîne de fetch) | | `GOOGLE_CLIENT_ID` · `GOOGLE_CLIENT_SECRET` | connexion Google OAuth directe | | `KA_SSO_SECRET` · `KA_HUB_URL` · `SESSION_SECRET` | SSO KA ID (JWT HS256 partagé avec groupe-ka.com) + sessions | | `HQ_CAPTCHA_PROVIDER` · `HQ_CAPTCHA_KEY` | résolution reCAPTCHA de l'estimation Hydro-Québec | | `LOUKA_BASE_URL` | URL publique de base (liens PDF, sitemaps) | | `LOUKA__*` (≈70 variables) | tuning par connecteur : limites de détail, TTL, pages max, cadence (ex. `LOUKA_KIJIJI_DETAIL_LIMIT`, `LOUKA_FBMP_CITIES`, `LOUKA_AIRBNB_BUDGET`) | | `VITE_MAPBOX_TOKEN` (frontend) | jeton public Mapbox de la carte 3D | ## Données & conformité - **Agrégateur indépendant** : aucune affiliation avec les gestionnaires immobiliers ; chaque fiche renvoie vers l'annonce originale via la passerelle de sortie transparente `/passerelle/{uid}` (mention affichée au pied du site). - **Provenance** : sites publics des gestionnaires et portails d'annonces (281 sources recensées dans `data/sources.json`, statut et raison documentés pour chaque source non connectable) ; couches de quartier issues de données ouvertes (recensement 2021, registre des loyers, BDZI, SPVM, RSQAQ, Régie de l'énergie, OSM). - **Cadence** : resynchronisation long terme en boucle de 60 min (`lou-ka-sync`), court terme par cycles de 360 min ; détection de changement par hash de contenu → ajouts, mises à jour et retraits automatiques. - **Cycle de vie honnête** : une annonce retirée chez la source répond `410 Gone` et sort des sitemaps ; le garde-fou anti-dérive suspend les retraits massifs suspects plutôt que de vider l'inventaire. - **Qualité** : porte de pertinence (quarantaine du hors-périmètre : stationnements, commerciaux, nuitées) et score de complétude par annonce (moyenne 91,4 %). ## Structure du repo ``` lou-ka/ ├── run.py # point d'entrée CLI (sync / watch / sync-ct / watch-ct / serve / geocode / poi / quartier / record) ├── louka/ # paquet backend : web, seo, db, ingest, normalize, textmine, auth, kascores… │ ├── connectors/ # 221 connecteurs long terme auto-découverts │ └── shortterm/ # sous-système court terme isolé (db, ingest, web + 29 connecteurs) ├── frontend/ # React 18 + Vite + TypeScript (pages, composants, kamaps/) + public/doc/ (guide) ├── data/ # sources.json (registre, 281 entrées) + bases SQLite de prod (gitignorées) ├── scripts/ # build recensement/contexte/environnement, docs connecteurs, screenshots, check-order ├── tests/ # pytest + fixtures HTTP rejouables hors-ligne ├── actors/ # acteurs Apify d'appoint (ka-fb-marketplace, ka-apartments-com…) ├── reports/ # audits (fiches connecteurs, expansion par région, quartier…) └── docs/ # captures d'écran + docs connecteurs + ka-maps ``` ## Historique Repère des jalons (128 commits depuis la naissance) : | Date | Jalon | |---|---| | 2026-08-06 | naissance du projet : agrégateur Québec/Lévis/Grand Montréal, page Statistiques (`fb48938`, `ece6ed0`) | | 2026-08-08 | Mission 1a — couche commune : schéma enrichi, normalisation centrale, robustesse, tests (`7323079`) | | 2026-08-19 | KA Scores calculés sur 94,7 % du parc + standard « ordre des sections = ordre du DOM » (`747f631`, `a6e30ef`) | | 2026-08-21→22 | porte de pertinence (quarantaine hors-périmètre) + chaîne de fetch anti-bot Oxylabs→Scrapfly→Bright Data + acteurs Apify maison FB Marketplace / Apartments.com (`8547737`, `8598785`, `e7f4876`) | | 2026-08-22→23 | section « Location court terme » : sous-système isolé, Airbnb en quadrillage carte, 38 sources recensées, SEO complet (`38b708b`, `5c571bc`, `63456a0`) | | 2026-08-23 | couches de quartier : registre des loyers (57 433 déclarations), inondation BDZI, criminalité SPVM, air, essence, commerces/transport, estimation Hydro-Québec live + rapports PDF personnalisés (`604455e` → `4d17c17`, `834c92c`) | | 2026-08-24 | page documentation `/doc` + guide PDF + README v2/v3 (`963ba8f`, `4fa8714`) | ## Documentation - **Guide en ligne** : [www.lou-ka.com/doc/](https://www.lou-ka.com/doc/) — à quoi sert le site, le parcours en 4 étapes (recherche → résultats → fiche → /stats), d'où viennent les données, FAQ. - **Guide PDF** : [lou-ka-documentation.pdf](https://www.lou-ka.com/doc/lou-ka-documentation.pdf) — la même documentation, téléchargeable. - Les captures du guide sont versionnées dans `frontend/public/doc/img/` (etape1 → etape4). ## Développement (remote-first) **La source de vérité est le repo git sur le nœud M3U96b** (`~/apps/lou-ka`) — on n'édite jamais les copies laptop. Toute modification se fait sur le nœud via SSH : édition, build, `pm2 restart`, puis commit/push depuis le nœud. - Remote `origin` = **spbgit** (git perso [git.spboucher.ai](https://git.spboucher.ai), bare repos sur M3U96a). **Pas GitHub.** - L'agent forwarding SSH est actif : le `git push origin main` fonctionne pendant une session SSH depuis le laptop. ```bash pm2 restart lou-ka-web # après un changement en production ``` ## Déploiement - **Nœud** : M3U96b (Mac Studio, cluster MacLustr) — répertoire `~/apps/lou-ka` - **Port** : **8095** (local, exposé uniquement via le tunnel) - **Processus PM2** : `lou-ka-web` (serveur) + `lou-ka-sync` (synchro) + `lou-ka-ngrok` (tunnel) - **Domaine** : **https://www.lou-ka.com** (tunnel ngrok) ## Écosystème Groupe KA | Plateforme | Vocation | |---|---| | [groupe-ka.com](https://www.groupe-ka.com) | portail du groupe et compte unique KA ID | | [lou-ka.com](https://www.lou-ka.com) | logements à louer *(ce repo)* | | [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre | | [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière | | [auto-ka.com](https://www.auto-ka.com) | véhicules | | [fabri-ka.com](https://www.fabri-ka.com) | produits québécois | | [food-ka.com](https://www.food-ka.com) | épicerie et alimentation | | [resto-ka.com](https://www.resto-ka.com) | restaurants | | [sorti-ka.com](https://www.sorti-ka.com) | sorties et événements | | [job-ka.com](https://www.job-ka.com) | emplois | | [crea-ka.com](https://www.crea-ka.com) | créateurs de contenu | | [trouve-ka.com](https://www.trouve-ka.com) | petites annonces | | [api-ka.com](https://www.api-ka.com) | API de données | ## Contact **Simon-Pierre Boucher** — fondateur, Groupe KA 📧 [contact@spboucher.ai](mailto:contact@spboucher.ai) --- © Groupe KA — Simon-Pierre Boucher · contact@spboucher.ai Ce repo vit sur **spbgit** ([git.spboucher.ai](https://git.spboucher.ai)).