Maps Review Rating Change Dashboard

Turn review exports you already hold into a per-business answer to one question: did the average rating really move, or is it noise?

For each business the Actor compares a recent window with a baseline window, reports the average change with a 95% confidence interval, shows the share of 1–2 star reviews, and attaches sample-size warnings. Businesses without enough data get an explicit insufficient_data status instead of a misleading number.

What it does not do

• It does not scrape Google Maps or any other site and makes no network requests. You supply the data.
• It does not collect reviewer names or any personal data; only business, date and rating are read.

Input

Field	Meaning	Default
reviews	JSON array of rows with a business (placeId, businessId or name), date (YYYY-MM-DD) and rating (1–5). Optional reviewId removes duplicates.	–
csvText	Same data as CSV text with a header row. Combined with reviews.	–
asOfDate	End of the recent window.	newest review date
recentDays	Recent window length.	90
baselineDays	Baseline window, directly before the recent one.	365
minReviewsPerWindow	Minimum reviews in each window for a verdict.	10
minMeaningfulShift	Smallest shift (stars) reported as improved/declined.	0.2
maxReviews	Row cap to keep memory low.	50000

Copyable example:

{
  "csvText": "placeId,name,date,rating\ncafe-001,Harbor Cafe,2026-01-10,5\ncafe-001,Harbor Cafe,2026-09-05,2",
  "recentDays": 90,
  "baselineDays": 365,
  "minReviewsPerWindow": 10
}

That tiny example will return insufficient_data by design; provide at least minReviewsPerWindow reviews per window for a verdict.

Output

One dataset row per business: status (improved, declined, no_clear_change, insufficient_data), baselineMean, recentMean, ratingChange, changeCI95Low, changeCI95High, counts per window, lowStarShareRecent/lowStarShareBaseline, sampleConfidence (insufficient, low, adequate) and a warnings list. A run summary is stored in the key-value store as OUTPUT_SUMMARY, including counts of invalid and duplicate rows.

Method and limitations

• Welch's interval for the difference of means, using Student t critical values. Ratings are discrete 1–5 values and often skewed, so the interval is approximate, especially below about 30 reviews per window.
• A variance floor is applied so identical ratings do not give a falsely exact interval.
• sampleConfidence is low when the smaller window has fewer than 3× the minimum reviews.
• Results describe your export only. Exports may be incomplete, sampled or biased (for example by review filtering or deletion), and the Actor cannot detect that.
• Statistical significance is not a cause. A drop can come from a changed mix of reviewers, seasonality or a single event.
• Many businesses tested at once will show some chance "significant" results; no multiple-comparison correction is applied.
• Dates are compared as calendar days with no time-zone handling. Rows with unparseable dates or ratings outside 1–5 are skipped and counted.

Pricing

The code emits a business-analyzed event for each business with a verdict. Rows with insufficient_data and failed runs are not charged. Pricing is not set in this repository.

Local tests

python -m unittest discover -s tests -t . (offline, standard library only for the analysis modules).