Maps Review Recency and Coverage Audit

Measures how fresh and how evenly spread the reviews in your existing review export are, per business location. It answers: which locations have gone quiet, which have thin or bursty review coverage, and where is the sample too small to trust?

This Actor does not scrape Google Maps or any other site, makes no network requests, and never reads, stores or returns reviewer names, IDs, profile links or review text. You supply the rows; it returns per-location statistics.

Who it is for

Teams that already hold review exports (from their own business profiles, licensed data, or prior exports) for many locations and need a quick, repeatable freshness check, for example multi-location operators, agencies reporting to clients, or analysts screening which locations need a review-request campaign.

Input

Copy-and-paste example:

{
  "reviews": [
    {"placeId": "demo-cafe-1", "locationName": "Demo Cafe", "publishedAt": "2026-09-20", "rating": 5},
    {"placeId": "demo-cafe-1", "locationName": "Demo Cafe", "publishedAt": "2026-08-02", "rating": 4},
    {"placeId": "demo-gym-2", "locationName": "Demo Gym", "publishedAt": "2025-05-11", "rating": 3}
  ],
  "referenceDate": "2026-10-01",
  "freshDays": 90,
  "staleDays": 365,
  "minReviewsForConfidence": 20
}

• Location: placeId (also place_id, locationId), or locationName / title plus optional address.
• Date: publishedAt, publishedAtDate, reviewDate, date, createdAt, time. Accepted formats: ISO dates/timestamps, epoch seconds or milliseconds, 2026/09/01, Sep 1, 2026, and relative text such as 3 months ago (treated as approximate).
• Rating (optional): rating, stars, reviewRating.
• Other fields are ignored.

Output

One dataset item per location, plus a SUMMARY record in the key-value store.

Field	Meaning
recencyStatus	fresh, aging, stale (by age of newest review) or no_usable_dates
recencyScore	0-100 heuristic: 50% newest-review recency, 50% share of the last 12 thirty-day periods with at least one review
sampleConfidence	adequate or low (fewer dated reviews than your threshold)
reviewsLast30Days / 90 / 365	Counts of dated reviews
monthsWithReviewsLast12, coverageRatio12	Coverage across twelve 30-day periods
longestGapDaysLast365	Longest review-free stretch in the last 365 days
ratingChange	Average rating of last 90 days minus days 91-365, only when each side has at least 5 rated reviews
flags	Plain-language caveats, e.g. small_sample, mostly_approximate_dates, concentrated_recent_activity

Pricing

The code emits one location-audited event per location that has at least one usable date. No payable plan is configured in this repository. Invalid input, locations without usable dates, and failed runs are not charged.

Limitations and caveats

• Results describe only the rows you provide. If the export is a partial sample (for example only the most recent N reviews per place), "oldest review", gaps and coverage will be misleading.
• Small samples are unreliable. Locations below your minimum are marked low confidence; do not compare their scores with well-sampled locations.
• Without reviewer identifiers, duplicate rows cannot be detected. Duplicated exports inflate counts.
• Relative dates ("3 months ago") are approximated (month = 30 days, year = 365 days) and flagged when they dominate.
• Date-only values are interpreted as UTC calendar days. Rows dated after the reference date are excluded and counted.
• recencyScore and concentrated_recent_activity are heuristics, not evidence of review manipulation or business quality.
• Rows are limited by maxReviews (hard cap 200000) and maxLocations; the SUMMARY reports anything skipped.
• Rows lacking a location identifier are skipped. Locations identified by name and address are merged case-insensitively, so differently spelled names will be split.

Local tests

Tests are offline: python -m unittest discover -s tests.