FR
Copied
Modules

Reviews

Enrichment module that extracts the Google reviews of each point of interest in a list, most recent first.

Purpose

Enrichment module: turns a list of POIs (each with a Google Maps link) into a flat stream of reviews: author, rating, date, text and owner reply. Typically chained after scrap.

Inputs

JSON body with a list of POI items. Each item must carry a Google Maps link; other columns are preserved as context but ignored for extraction.

Field Type Required Description
items list yes POI rows. Between 1 and 10000 entries per job.
source_job_id string no UUID of the upstream job (typically a scrap job). Used for lineage.
max_reviews int no Reviews kept per POI, most recent first. Default 300. 0 = unlimited.
period_months int no Only reviews published within the last N months are kept. Default 12. 0 = unlimited.

With the defaults, each POI yields at most its 300 most recent reviews published over the last 12 months. The two settings are independent: set either one to 0 to lift it, both to 0 to read every review of every POI.

Each entry in items is an object. The single required key is lien_google_maps. Other keys are carried through unchanged and reattached on every produced review row.

Item key Type Required Notes
lien_google_maps string yes Canonical Google Maps URL of the POI. An item without it is not processed: it is kept in the final file with empty review columns.
nom string no Business name, propagated to each review row.
adresse string no Postal address, propagated.
telephone string no Propagated.
site_web string no Propagated.

Request example:

{
  "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

One row per review (not per POI). A POI with no review, or none within the requested period, keeps one row, with empty review columns. The input columns of the POI are repeated on every row.

Column Type Description
avis_auteur string Public display name of the review author.
avis_note integer Star rating, from 1 to 5.
avis_date string Date of the review, formatted dd/mm/yyyy.
avis_texte string Body of the review.
avis_reponse_proprietaire string Public reply of the business owner, empty when none.

Export formats: CSV (UTF-8 with BOM, semicolon delimiter), JSON and XLSX. The CSV is canonical. The registry lists reviews_list and owner_replied under produces: these are signal names; an owner reply exists when avis_reponse_proprietaire is not empty.

Lifecycle

Standard job lifecycle: see Jobs & lifecycle.

Pipeline

Slot Value
category enrich
needs poi_list (requires lien_google_maps)
produces reviews_list, owner_replied

Node config in a pipeline: {"max_reviews": 300, "period_months": 12} (same meaning and defaults as the job fields, 0 = unlimited).

Upstream: scrap, or any import with a valid lien_google_maps column. Downstream: typically filter and sort to narrow by rating, owner-reply, or recency.

Endpoints

Module-specific:

POST /api/jobs/reviews

Body: ReviewsJobCreateRequest (see Inputs). Returns the created job in pending.

Generic job endpoints:

Method Path Purpose
GET /api/jobs/{job_id} Fetch job state and metadata.
GET /api/jobs/{job_id}/events SSE stream of progress events.
GET /api/jobs/{job_id}/download Download the produced CSV/XLSX.
POST /api/jobs/{job_id}/cancel Request cancellation.

Limits

Global quotas: see /docs/concepts/limits. The reviews module consumes roughly 0.4 / 3700 EF per POI. Payload bounds: 1 to 10000 items per job. Reviews per POI: capped by max_reviews (default 300) and period_months (default 12); max_reviews accepts 0 to 1000000, period_months 0 to 1200. The period applies to the publication date shown in avis_date. The ranking by recency follows the last edit of a review: a review edited recently ranks among the most recent ones. The job record echoes both settings.

Errors

Condition Outcome
No item carries a lien_google_maps Job creation fails with HTTP 400 and message Aucun établissement valide.
Estimated cost exceeds the per-job quota Job creation fails with HTTP 400 and an explicit Quota dépassé message.
max_reviews or period_months negative or out of bounds Job creation fails with HTTP 422.
POI has no public reviews The POI is kept: one row with empty review columns. The job still succeeds.
Reviews of a POI could not be read in full The POI is kept with the reviews already read (otherwise one row with empty review columns), counted in the job errors and surfaced in the job summary; remaining POIs continue.
Job cancelled while running The partial file keeps every review already read, including for the POIs in progress.
Source unreachable for the whole run Job ends in failed with the upstream error surfaced on the job record.

What's next