FR
Copied
Modules

Reviews

Enrichment module that extracts the full Google reviews stream for each point of interest in a list.

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 flag. 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.

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. Items without it are dropped at validation.
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",
  "items": [
    {
      "nom": "Boulangerie Centrale",
      "adresse": "12 rue de la Paix, 75002 Paris",
      "lien_google_maps": "https://www.google.com/maps/place/..."
    },
    {
      "nom": "Garage Dupont",
      "lien_google_maps": "https://www.google.com/maps/place/..."
    }
  ]
}

Outputs

One row per review (not per POI). POI context is duplicated on every row.

Column Type Description
nom string Business name (from input).
adresse string Business address (from input).
lien_google_maps string Source POI URL.
reviewer_name string Public display name of the review author.
rating integer Star rating, 1–5.
date string Relative date as published by Google (e.g. "il y a 2 mois").
review_text string Body of the review.
owner_replied boolean true when the business owner posted a public reply.
owner_reply_text string Owner reply body, empty when none.

Two export formats: CSV (UTF-8, comma-separated, RFC 4180-quoted) and XLSX. The CSV is canonical.

Lifecycle

Standard job lifecycle: see Jobs & lifecycle.

Pipeline

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

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. No client-side cap on reviews per POI.

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.
POI has no public reviews The POI is processed; zero rows are emitted for it. The job still succeeds.
Source temporarily unavailable for a POI That POI is skipped and surfaced in the job summary; remaining POIs continue.
Source unreachable for the whole run Job ends in failed with the upstream error surfaced on the job record.

What's next