![Fedhubs Scraper](https://raw.githubusercontent.com/omkarcloud/google-maps-scraper/master/screenshots/google-maps-scraper-feautred-image.png)

Fedhubs Scraper

Python · Botasaurus · Next.js Dashboard

Outil de scraping Google Maps orienté B2B : collecte des fiches d'établissements (nom, téléphone, site web, horaires, réseaux sociaux, emails…), les enrichit automatiquement, et les expose via un dashboard Next.js et une API REST. --- ## Sommaire - [Architecture](#architecture) - [Prérequis](#prérequis) - [Installation locale](#installation-locale) - [Lancement](#lancement) - [Docker](#docker) - [API REST](#api-rest) - [Variables d'environnement](#variables-denvironnement) - [FAQ](#faq) --- ## Architecture ``` ┌─────────────────────────────────────────────────────┐ │ Utilisateur │ └───────────┬──────────────────┬──────────────────────┘ │ :3000 │ :8001 ┌──────▼──────┐ ┌───────▼────────┐ │ Dashboard │ │ FastAPI │ │ Next.js │ │ Custom API │ └──────┬──────┘ └───────┬────────┘ │ │ └──────┬───────────┘ │ :8000 ┌────────▼────────┐ │ Botasaurus │ │ Server (UI+API) │ └────────┬────────┘ │ ┌──────────▼──────────┐ │ Scrapers Python │ │ Google Maps │ │ Website Contacts │ │ Social / Email │ └─────────────────────┘ ``` | Port | Service | Description | |------|---------|-------------| | `3000` | Frontend Next.js | Dashboard interface utilisateur | | `8000` | Botasaurus Server | API interne utilisée par le dashboard | | `8001` | FastAPI custom | API REST externe (Swagger sur `/docs`) | --- ## Prérequis - Python **3.9+** - Node.js **16+** - Google Chrome installé (utilisé par Botasaurus en mode headless) - pip --- ## Installation locale ### 1. Cloner le projet ```bash git clone https://gitlab.com/fedhubs/workspace/fedhubs_pro_scrapping_tool.git cd fedhubs_pro_scrapping_tool ``` ### 2. Créer et activer l'environnement virtuel ```bash python3 -m venv .venv source .venv/bin/activate # Windows : .venv\Scripts\activate ``` ### 3. Installer les dépendances Python ```bash pip install -r requirements.txt ``` ### 4. Installer le scraper Botasaurus (télécharge Chrome headless) ```bash python main.py install ``` ### 5. Installer les dépendances frontend ```bash cd frontend npm install cd .. ``` > Le projet utilise React 17. Un fichier `.npmrc` (déjà inclus) force `legacy-peer-deps=true` pour éviter les conflits de dépendances npm. --- ## Lancement ```bash source .venv/bin/activate python main.py ``` Le backend démarre sur : - Botasaurus Server → `http://127.0.0.1:8000` - FastAPI custom → `http://127.0.0.1:8001` - Dashboard → `http://localhost:3000` > Si le port `8001` est déjà occupé après un crash : `lsof -ti:8001 | xargs kill -9` ### Mode développement (frontend hot-reload) Dans un second terminal : ```bash cd frontend npm run dev ``` --- ## Docker ### 1. Créer le fichier `.env` ```bash echo "FEDHUBS_API_KEY=change-moi-par-une-vraie-cle" > .env ``` ### 2. Build et lancer ```bash docker compose up -d --build ``` ### Ports exposés | Port externe | Port interne | Service | Accès | |---|---|---|---| | `7431` | `3000` | Dashboard | SSH tunnel uniquement | | `7432` | `8000` | Botasaurus API | SSH tunnel uniquement | | `7433` | `8001` | FastAPI custom | Public (clé API requise) | > Les ports 7431 et 7432 sont liés à `127.0.0.1` — inaccessibles depuis l'extérieur. Seul le port 7433 est public. ### Accéder au dashboard depuis son poste ```bash ssh -L 7431:localhost:7431 user@ton-serveur # puis ouvre http://localhost:7431 ``` ### Arrêter ```bash docker compose down ``` --- ## API REST L'API custom FastAPI est disponible sur le port `8001` (local) ou `7433` (Docker). **Swagger UI interactif →** `http://127.0.0.1:8001/docs` ### Endpoints | Méthode | Endpoint | Auth | Description | |---------|----------|------|-------------| | `GET` | `/api` | ❌ | Health check | | `POST` | `/api/tasks/create-task-async` | ✅ | Créer une tâche de scraping | | `GET` | `/api/tasks` | ✅ | Lister toutes les tâches | | `GET` | `/api/tasks/{id}` | ✅ | Détail d'une tâche | | `GET` | `/api/results/{id}` | ✅ | Résultats d'une tâche | | `GET` | `/api/tasks/{id}/download?format=csv` | ✅ | Télécharger (`csv`, `json`, `xlsx`) | | `POST` | `/api/tasks/{id}/abort` | ✅ | Interrompre une tâche | | `DELETE` | `/api/tasks/{id}` | ✅ | Supprimer une tâche | > **Note** `create-task-async` renvoie `{task_id, status}` où `task_id` est l'**« All Task »** (la tâche parente qui agrège les résultats de toutes les sous-requêtes). En interne, `create_async_task` botasaurus renvoie une *liste* (All Task + une sous-tâche par requête) ; le wrapper FastAPI sélectionne l'All Task. Côté lecture, `/api/tasks` et `/api/results/{id}` renvoient une **enveloppe paginée** (`{count, results, …}`). ### Paramètres `data` | Champ | Type | Défaut | Description | |---|---|---|---| | `queries` | string[] | — | Requêtes de recherche (**obligatoire**) | | `max_results` | int | null | Nombre max de résultats par requête | | `country` | string | null | Code pays ISO pour cibler des villes (ex: `"FR"`) | | `business_type` | string | `""` | Type d'établissement (ex: `"Restaurant"`) | | `max_cities` | int | null | Nb max de villes à cibler (si `country` défini) | | `randomize_cities` | bool | true | Randomiser l'ordre des villes | | `lang` | string | null | Langue des résultats (ex: `"fr"`) | | `coordinates` | string | `""` | Centrer la recherche sur `"lat, lng"` | | `zoom_level` | int | 14 | Niveau de zoom Google Maps (1–21) | | `enable_reviews_extraction` | bool | false | Extraire les avis clients | | `max_reviews` | int | 20 | Nb max d'avis par lieu | | `reviews_sort` | string | `"newest"` | Tri des avis : `newest`, `most_relevant`, `highest_rating`, `lowest_rating` | | `scrape_from_external_links` | bool | false | Scraper site web, Instagram et Facebook | | `use_cache` | bool | true | Réutiliser le cache JSON. `false` = rescraper depuis Google Maps | ### Exemple — Créer une tâche ```bash curl -X POST http://127.0.0.1:8001/api/tasks/create-task-async \ -H "Content-Type: application/json" \ -H "X-API-Key: ton-secret-ici" \ -d '{ "scraper_name": "google_maps_scraper", "data": { "queries": ["Restaurant in Paris"], "max_results": 50, "lang": "fr", "use_cache": false } }' ``` **Réponse :** ```json { "task_id": 42, "status": "pending" } ``` ### Exemple — Récupérer les résultats ```bash curl http://127.0.0.1:8001/api/results/42 \ -H "X-API-Key: ton-secret-ici" ``` ### Exemple Python complet ```python import requests, time BASE = "http://127.0.0.1:8001" HEADERS = {"X-API-Key": "ton-secret-ici"} task_id = requests.post( f"{BASE}/api/tasks/create-task-async", headers=HEADERS, json={ "scraper_name": "google_maps_scraper", "data": {"queries": ["Restaurant in Paris"], "max_results": 50} } ).json()["task_id"] while True: status = requests.get(f"{BASE}/api/tasks/{task_id}", headers=HEADERS).json()["status"] if status in ("completed", "failed"): break time.sleep(3) results = requests.get(f"{BASE}/api/results/{task_id}", headers=HEADERS).json() print(f"{len(results)} résultats") ``` --- ## Session Google (optionnel) Le scraper fonctionne **sans compte Google**. Cependant, se connecter une fois améliore la qualité des données (nombre d'avis, horaires détaillés) et réduit les risques de détection. ```bash python google_login.py ``` Un navigateur s'ouvre → connecte-toi à Google → appuie sur Entrée. Le profil est sauvegardé localement dans `profiles/google_scraper/` (ignoré par git — chaque développeur fait cette étape sur sa propre machine). > Sans profil : le scraper tourne en mode anonyme, tous les champs principaux sont récupérés, mais certains compteurs peuvent être incomplets. --- ## Variables d'environnement | Variable | Défaut | Description | |----------|--------|-------------| | `FEDHUBS_API_KEY` | *(vide)* | Clé d'auth pour l'API REST. Si vide, l'API est accessible sans auth (dev local uniquement). | | `FASTAPI_HOST` | `127.0.0.1` | Host d'écoute de FastAPI. Mettre `0.0.0.0` en Docker. | ### Configurer la clé API ```bash # Linux / macOS export FEDHUBS_API_KEY="change-moi-par-une-vraie-cle" python main.py # Windows (PowerShell) $env:FEDHUBS_API_KEY = "change-moi-par-une-vraie-cle" python main.py ``` --- ## FAQ **Le scraper est détecté par Google, que faire ?** Botasaurus gère automatiquement un fallback en mode navigateur headless lorsqu'un captcha est détecté. Si les détections sont fréquentes, envisage l'usage d'un proxy rotatif. **Combien de résultats peut-on scraper ?** Google affiche jusqu'à 120 résultats par requête. En combinant plusieurs villes via le champ `country`, tu peux scraper des milliers d'établissements en une seule tâche. **Le dashboard affiche "Server not running" ?** Le backend Python doit être démarré avant le frontend. Lance `python main.py` et attends le message `Botasaurus prêt.` avant d'ouvrir le dashboard. **Comment utiliser le scraper de contacts de sites web ?** Dans le dashboard, sélectionne **"Website Contacts Scraper"** dans le sélecteur de scraper, puis colle une ou plusieurs URLs de sites web. **Comment vider le cache ?** Supprime les fichiers dans `task_results/cache/`. Ou passe `"use_cache": false` dans ta requête pour forcer un re-scraping sans toucher au cache existant. --- ## Contact 📩 [deban@fedhubs.com](mailto:deban@fedhubs.com) --- Made with ❤️ by [Fedhubs](https://www.fedhubs.net)