Modules

Scrap (Google Maps)

Module source qui extrait des fiches Google Maps pour un ensemble de requêtes sur une ou plusieurs zones géographiques.

Purpose

Module source : exécute chaque requête sur chaque point de grille couvrant les zones demandées et retourne un CSV à plat d'établissements Google Maps (nom, contact, localisation, note).

Inputs

Field	Type	Required	Description
`queries`	`string[]` (1–20)	yes	Termes recherchés sur Google Maps. Chaque requête est trimée et plafonnée à 200 caractères.
`zones`	`string[]` (1–50)	yes	Zones géographiques. Accepte codes INSEE, codes département, noms de région, ou `"France"`. Chaque zone est résolue en grille de points côté serveur.
`include_reviews`	`bool`	no	Conservé pour compatibilité ascendante. Ne chaîne pas un job reviews — utiliser le module `reviews` à la place. Défaut `false`.

Corps de requête :

{
  "queries": ["plombier", "chauffagiste"],
  "zones": ["75", "92"],
  "include_reviews": false
}

Requêtes Google Maps effectives = len(queries) × grid_points(zones). Rejeté à la soumission si coût supérieur au plafond per-job EF.

Outputs

Fichier résultat : CSV UTF-8, séparateur point-virgule, BOM (compatible Excel). Même jeu de données disponible en trois formats via l'endpoint de téléchargement.

Column	Type	Description
`nom`	string	Nom de l'établissement affiché sur Google Maps.
`site_web`	string	URL du site web public si renseignée.
`telephone`	string	Numéro de téléphone tel que listé.
`adresse`	string	Adresse postale.
`rating`	float	Note moyenne (0.0–5.0).
`reviews_count`	int	Nombre d'avis publics.
`category`	string	Catégorie principale Google Maps.
`lien_google_maps`	string	URL canonique Google Maps de la fiche.
`aggregator_flag`	bool	Vrai si la fiche ressemble à un annuaire/agrégateur plutôt qu'à un établissement final.
`query`	string	Requête source qui a produit la ligne.
`lat`, `lon`	float	Point de grille auquel la ligne a été collectée.

Formats : csv (original), json, xlsx. Choisi via ?format= sur l'endpoint de téléchargement.

Lifecycle

Cycle de vie standard : voir Jobs & lifecycle. Pendant l'exécution, l'événement SSE status transporte une charge query_stats de forme { "<query>": { "tiles": int, "with_results": int } }, mise à jour en temps réel pour exposer le taux de succès par requête.

Pipeline

Field	Value
`needs`	`null` (module source — aucun CSV d'entrée requis)
`produces`	`poi_list`

Modules typiques chaînés en aval d'un scrap :

emails — recherche les emails pro et personnels depuis site_web.
socials — extrait les comptes réseaux sociaux depuis site_web.
legal_ids — extrait SIREN/SIRET depuis le site de l'établissement (page mentions légales).
reviews — collecte les fils d'avis complets depuis lien_google_maps.
techstack, dead_check, brand_assets, ads_intelligence — enrichissements au niveau site web, indexés sur site_web.

Endpoints

Endpoint dédié :

POST /api/jobs
Content-Type: application/json

{
  "queries": ["plombier"],
  "zones": ["75"],
  "include_reviews": false
}

Endpoint générique (équivalent — même payload, job_type déduit de la forme) :

POST /api/jobs
Content-Type: application/json

{
  "job_type": "scrap",
  "queries": ["plombier"],
  "zones": ["75"]
}

Les deux réponses retournent l'objet JobPublic créé, incluant id, status, grid_points_count, ef_cost et output_filename.

Téléchargement :

GET /api/jobs/{job_id}/download?format=csv|json|xlsx

Limits

Quotas globaux de la plateforme : voir /docs/fr/concepts/limits. Plafonds spécifiques au module :

Limit	Value
Nombre maximum de requêtes par job	20
Nombre maximum de zones par job	50
Longueur maximum d'une requête	200 caractères
Coût maximum par job	`1.0` équivalent-France (EF)
Vérification email	Requise sur le compte avant création d'un job `scrap`.

Errors

Scenario	HTTP	Resolution
Zone non reconnue	400	Inspecter le tableau `errors` dans le corps de réponse ; utiliser codes INSEE/département ou `"France"`.
Aucun point de grille résolu	400	L'ensemble des zones est vide après résolution — élargir la sélection.
Quota EF dépassé	400	Réduire le nombre de requêtes ou rétrécir les zones jusqu'à EF estimé ≤ 1.0.
Email non vérifié	403	Vérifier l'email du compte avant de créer un job `scrap`.
Aucun worker disponible	Le job reste en `pending` jusqu'à libération du pool multi-proxy partagé. Un seul job multi-proxy tourne à la fois sur l'ensemble de la plateforme.
Job échoué en cours	Un CSV partiel est conservé. Un `POST /api/jobs/{id}/resume` crée un job de relance qui saute les points de grille déjà traités et n'est facturé que sur le reliquat.
Téléchargement expiré	410	Les fichiers résultats ont une fenêtre de rétention — relancer le job ou chaîner depuis une source fraîche.

Les requêtes refusées par Google Maps remontent dans dead_queries sur l'objet job.