EN
Copied
Modules

Avis

Module d'enrichissement qui extrait les avis Google de chaque point d'intérêt d'une liste, du plus récent au plus ancien.

Purpose

Module d'enrichissement : transforme une liste de POI (avec lien Google Maps) en flux à plat d'avis : auteur, note, date, texte et réponse du propriétaire. Typiquement chaîné après scrap.

Inputs

Corps JSON avec une liste d'items POI. Chaque item doit porter un lien Google Maps ; les autres colonnes sont conservées comme contexte mais ignorées pour l'extraction.

Field Type Required Description
items list yes Lignes POI. Entre 1 et 10000 entrées par job.
source_job_id string no UUID du job amont (typiquement un job scrap). Utilisé pour la traçabilité.
max_reviews int no Avis gardés par POI, les plus récents d'abord. Défaut 300. 0 = illimité.
period_months int no Seuls les avis publiés dans les N derniers mois sont gardés. Défaut 12. 0 = illimité.

Avec les valeurs par défaut, chaque POI donne au plus ses 300 avis les plus récents publiés sur les 12 derniers mois. Les deux réglages sont indépendants : mettre l'un à 0 le lève, les deux à 0 lit tous les avis de chaque POI.

Chaque entrée d'items est un objet. La seule clé requise est lien_google_maps. Les autres clés sont propagées inchangées et rattachées à chaque ligne d'avis produite.

Item key Type Required Notes
lien_google_maps string yes URL canonique Google Maps du POI. Un item sans ce champ n'est pas traité : il est conservé dans le fichier final, colonnes d'avis vides.
nom string no Nom de l'établissement, propagé à chaque ligne d'avis.
adresse string no Adresse postale, propagée.
telephone string no Propagé.
site_web string no Propagé.

Exemple de requête :

{
  "source_job_id": "9d2f8e0a-1c4b-4f7e-a2b9-3d6a5e10c8f1",
  "max_reviews": 300,
  "period_months": 12,
  "items": [
    {
      "nom": "Boulangerie Exemple",
      "adresse": "1 rue de l'Exemple, 00000 Exempleville",
      "lien_google_maps": "https://www.google.com/maps/place/..."
    },
    {
      "nom": "Garage Exemple",
      "lien_google_maps": "https://www.google.com/maps/place/..."
    }
  ]
}

Outputs

Une ligne par avis (pas par POI). Un POI sans avis, ou sans avis dans la période demandée, garde une ligne, colonnes d'avis vides. Les colonnes d'entrée du POI sont répétées sur chaque ligne.

Colonne Type Description
avis_auteur string Nom public de l'auteur de l'avis.
avis_note integer Note en étoiles, de 1 à 5.
avis_date string Date de l'avis, au format jj/mm/aaaa.
avis_texte string Corps de l'avis.
avis_reponse_proprietaire string Réponse publique du propriétaire, vide sinon.

Formats d'export : CSV (UTF-8 avec BOM, séparateur point-virgule), JSON et XLSX. Le CSV est canonique. Le registre liste reviews_list et owner_replied sous produces : ce sont des noms de signaux ; une réponse du propriétaire existe quand avis_reponse_proprietaire n'est pas vide.

Lifecycle

Cycle de vie standard : voir Jobs & lifecycle.

Pipeline

Slot Value
category enrich
needs poi_list (nécessite lien_google_maps)
produces reviews_list, owner_replied

Config du node dans une pipeline : {"max_reviews": 300, "period_months": 12} (même sens et mêmes défauts que les champs du job, 0 = illimité).

Amont : scrap, ou tout import avec colonne lien_google_maps valide. Aval : typiquement filter et sort pour restreindre par note, réponse propriétaire, ou récence.

Endpoints

Spécifique au module :

POST /api/jobs/reviews

Corps : ReviewsJobCreateRequest (voir Inputs). Retourne le job créé en pending.

Endpoints job génériques :

Method Path Purpose
GET /api/jobs/{job_id} Récupère l'état et les métadonnées du job.
GET /api/jobs/{job_id}/events Flux SSE des événements de progression.
GET /api/jobs/{job_id}/download Téléchargement du CSV/XLSX produit.
POST /api/jobs/{job_id}/cancel Demande d'annulation.

Limits

Quotas globaux : voir /docs/fr/concepts/limits. Le module reviews consomme environ 0.4 / 3700 EF par POI. Bornes payload : 1 à 10000 items par job. Avis par POI : bornés par max_reviews (défaut 300) et period_months (défaut 12) ; max_reviews accepte 0 à 1000000, period_months 0 à 1200. La période porte sur la date de publication, celle de avis_date. Le classement par récence suit la dernière modification d'un avis : un avis modifié récemment compte parmi les plus récents. Le job renvoie les deux réglages.

Errors

Condition Outcome
Aucun item ne porte de lien_google_maps La création échoue avec HTTP 400 et message Aucun établissement valide.
Coût estimé supérieur au quota per-job La création échoue avec HTTP 400 et un message explicite Quota dépassé.
max_reviews ou period_months négatif ou hors bornes La création échoue avec HTTP 422.
POI sans avis publics Le POI est conservé : une ligne aux colonnes d'avis vides. Le job réussit malgré tout.
Avis d'un POI lus en partie ou pas du tout Le POI est conservé avec les avis déjà lus (sinon une ligne aux colonnes d'avis vides), compté dans les erreurs du job et remonté dans son résumé ; les autres POI continuent.
Job annulé en cours d'exécution Le fichier partiel garde tous les avis déjà lus, y compris ceux des POI en cours.
Source injoignable sur l'ensemble du run Le job termine en failed avec l'erreur amont remontée sur le job.

What's next