Average rating over time

Overview

Get average rating by month.

Use this for a trend line.

You'll need a token. A period is optional.

Returns a series with a running average: each point is the average of the bucket ratings so far. The bucket size follows the range: daily up to 30 days, weekly up to 180 days, monthly up to 730 days, yearly beyond. With no dates, the range is the start of the month 13 months ago to the end of this month, so the buckets are monthly.

Prerequisites

A bearer token. See Authentication.
Optional: a location (store_id), a review site (review_site_id) and a date range (range_start, range_end, both Y-m-d).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/account/dashboard/get-averagerating-chart

Authentication

Partner or Account token

store_id must be inside your own account tree; otherwise 422.
Without store_id, the figures cover every location the token can see: every location under the partner for a Partner token, the account's locations for an Account token, or only the assigned locations for a user limited to some locations.

Rate limit

120 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

Parameter	In	Type	Required	Description
`store_id`	query	integer	No	One location. Must exist and be inside your account tree. Leave it out to cover every location your token can see.
`review_site_id`	query	integer	No	Only this review site, e.g. `44` for Google. Must be an existing review site. Leave it out to include every site.
`range_start`	query	string	No	Start of the chart, `Y-m-d`. Default: the start of the month 13 months ago.
`range_end`	query	string	No	End of the chart, `Y-m-d`. Must be on or after `range_start`. Default: the end of this month.

Request body

None.

Request payload

None.

Response body

data is an array with one point per bucket, oldest first, with no gaps.

Field	Type	Description
`data[]`	array of objects	One point per bucket, oldest first.
`data[].period`	string	The bucket: `YYYY-MM-DD` (daily), `YYYY-WW` (ISO week), `YYYY-MM` (monthly) or `YYYY` (yearly).
`data[].count`	number	Running average rating up to and including this bucket: the average of the bucket ratings so far, 2 decimals. A bucket with no reviews counts as 0. (It's a rating, despite the name.)

Response payload

{
  "data": [
    {
      "period": "2026-01",
      "count": 3.67
    },
    {
      "period": "2026-02",
      "count": 4.09
    },
    {
      "period": "2026-03",
      "count": 4.19
    },
    {
      "period": "2026-04",
      "count": 4.23
    },
    {
      "period": "2026-05",
      "count": 4.28
    },
    {
      "period": "2026-06",
      "count": 4.28
    },
    {
      "period": "2026-07",
      "count": 4.31
    },
    {
      "period": "2026-08",
      "count": 4.33
    },
    {
      "period": "2026-09",
      "count": 4.33
    }
  ]
}

Examples

Success payload

See Response payload.

Error payload

422 Date not in Y-m-d

{
  "message": "The range start field must match the format Y-m-d.",
  "errors": {
    "range_start": [
      "The range start field must match the format Y-m-d."
    ]
  }
}

422 range_end before range_start

{
  "message": "The range_end must be greater than or equal to range start.",
  "errors": {
    "range_end": [
      "The range_end must be greater than or equal to range start."
    ]
  }
}

422 Location outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy.",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ]
  }
}

422 Review site doesn't exist

{
  "message": "The selected review site id is invalid.",
  "errors": {
    "review_site_id": [
      "The selected review site id is invalid."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	The chart series.
`401`	The token is missing, expired or invalid.
`422`	A date isn't `Y-m-d`, `range_end` is before `range_start`, `store_id` doesn't exist or is outside your tree, or `review_site_id` doesn't exist.
`429`	More than 120 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/account/dashboard/get-averagerating-chart?store_id=3007&review_site_id=44&range_start=2026-01-01&range_end=2026-09-30" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'