Data model
Insights
Aspect-based sentiment analysis, named entities, topics, temporal trend, and FAQ — derived from the reviews and served at /insights.json.
Top level
| Field | Type | Required | Notes |
|---|---|---|---|
version | integer | yes | Schema version (INSIGHTS_VERSION). Bumped when the aspect taxonomy changes. |
generated_at | string (ISO 8601) | yes | When this artifact was generated. |
model | string | yes | Model used for analysis, e.g. "claude-sonnet-4-6". |
review_count | integer | yes | Number of reviews analyzed. |
date_range | object | yes | { earliest, latest } — YYYY-MM-DD bounds of analyzed reviews. |
overall_sentiment | object | yes | Aggregate sentiment (see below). |
aspects | AspectInsight[] | yes | Per-aspect sentiment breakdown (see below). |
entities | object | yes | Named entities: technicians, services, problems, service_areas (see below). |
topics | Topic[] | yes | Per-vertical topic clusters (see below). |
temporal | object | yes | { monthly[], trend } — time-series and direction (see below). |
per_review | record<string, PerReviewStored> | yes | Stored per-review analysis keyed by review id. |
faq | FaqEntry[] | yes | Generated Q&A grounded in reviews (see below). |
summary | string | no | Editorial prose summary for the /summary page and llms.txt. |
pull_quote | string | no | Single representative pull-quote. |
overall_sentiment
| Field | Type | Required | Notes |
|---|---|---|---|
score | number | yes | Aggregate sentiment score (-1..1 range). |
positive_pct | number | yes | Percent of reviews scored positive. |
neutral_pct | number | yes | Percent scored neutral. |
negative_pct | number | yes | Percent scored negative. |
aspects[] — AspectInsight
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Aspect id from the fixed taxonomy, e.g. "punctuality". |
label | string | yes | Human-readable aspect label. |
mention_count | integer | yes | Reviews mentioning this aspect. |
positive_count | integer | yes | Mentions scored positive. |
neutral_count | integer | yes | Mentions scored neutral. |
negative_count | integer | yes | Mentions scored negative. |
positive_pct | number | yes | Percent of mentions that are positive. |
score | number | yes | Aggregate aspect sentiment score. |
top_phrases | string[] | yes | Representative evidence phrases. |
example_review_ids | string[] | yes | Review ids exemplifying this aspect. |
entities.technicians[] — Technician
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Normalized technician id. |
display_name | string | yes | Display name. |
mention_count | integer | yes | Reviews mentioning this technician. |
positive_pct | number | yes | Percent of their mentions that are positive. |
average_rating_when_mentioned | number | yes | Mean star rating of reviews mentioning them. |
review_ids | string[] | yes | Review ids mentioning this technician. |
entities.services[] — ServiceEntity
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Normalized service id. |
label | string | yes | Service label. |
mention_count | integer | yes | Reviews mentioning this service. |
positive_pct | number | yes | Percent positive. |
average_rating | number | yes | Mean star rating for this service. |
review_ids | string[] | yes | Review ids mentioning this service. |
entities.problems[] — ProblemEntity
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Normalized problem id. |
label | string | yes | Problem label. |
mention_count | integer | yes | Reviews mentioning this problem. |
resolution_positive_pct | number | yes | Percent of mentions where the problem was resolved positively. |
entities.service_areas[] — ServiceAreaEntity
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Normalized service-area id. |
label | string | yes | Service-area label. |
mention_count | integer | yes | Reviews mentioning this area. |
review_ids | string[] | yes | Review ids mentioning this area. |
topics[] — Topic
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Topic id. |
label | string | yes | Topic label. |
description | string | yes | Short topic description. |
review_count | integer | yes | Reviews in this topic cluster. |
positive_pct | number | yes | Percent positive within the topic. |
review_ids | string[] | yes | Review ids in this topic. |
key_findings | string[] | yes | Bullet findings synthesized for the topic. |
temporal
| Field | Type | Required | Notes |
|---|---|---|---|
monthly | MonthlyPoint[] | yes | Per-month series: { month (YYYY-MM), review_count, average_rating, sentiment_score }. |
trend | "improving" | "stable" | "declining" | yes | Overall direction of sentiment over time. |
faq[] — FaqEntry
| Field | Type | Required | Notes |
|---|---|---|---|
question | string | yes | Generated question. |
answer | string | yes | Answer grounded in the reviews. |
evidence_review_ids | string[] | yes | Review ids supporting the answer. |