This year versus last

Overview

Get review volume and rating for each of the last 13 complete months, so this year's months sit next to the same months last year.

Use this for a year-over-year panel.

You'll need a token.

Returns one row per month, oldest first: from the start of the month 13 months ago to the end of last month.

Prerequisites

A bearer token. See Authentication.
Optional: a location (store_id) and a review site (review_site_id).

Base URL

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

Endpoint

GET /api/v1/account/dashboard/get-annual-volume-rating-stats

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 include every location your token can see.
`review_site_id`	query	integer	No	Only this review site. Must be an existing review site. `9` also includes Google (`44`).
`range_start`	query	string	No	Accepted but doesn't change the window. If sent, it must be `Y-m-d`.
`range_end`	query	string	No	Accepted but doesn't change the window. If sent, it must be `Y-m-d` and on or after `range_start`.

triangle-exclamation
The server sets the date window to the last 13 complete months. range_start and range_end don't change the window, but if you send them they must still be valid Y-m-d dates or the call returns 422.

Request body

None.

Request payload

None.

Response body

data is an array with one row per month in the fixed window, oldest first.

Field	Type	Description
`data[]`	array of objects	One row per month, 13 rows, oldest first.
`data[].month`	string	The month as `Mon YYYY` (for example, `Sep 2025`).
`data[].reviews`	integer	Reviews that month.
`data[].responses`	integer	Responses to that month's reviews.
`data[].monthly_avg_rating`	number	Average rating that month, 2 decimals. `0` when there are no reviews.
`data[].overall_rating`	number	The all-time overall rating, 2 decimals. The same on every row.

Response payload

{
  "data": [
    {
      "month": "Sep 2025",
      "reviews": 2,
      "responses": 0,
      "monthly_avg_rating": 5,
      "overall_rating": 4.21
    },
    {
      "month": "Oct 2025",
      "reviews": 1,
      "responses": 0,
      "monthly_avg_rating": 5,
      "overall_rating": 4.21
    },
    {
      "month": "Nov 2025",
      "reviews": 1,
      "responses": 0,
      "monthly_avg_rating": 5,
      "overall_rating": 4.21
    },
    {
      "month": "Dec 2025",
      "reviews": 3,
      "responses": 0,
      "monthly_avg_rating": 1.67,
      "overall_rating": 4.21
    },
    {
      "month": "Jan 2026",
      "reviews": 3,
      "responses": 0,
      "monthly_avg_rating": 3.67,
      "overall_rating": 4.21
    },
    {
      "month": "Feb 2026",
      "reviews": 4,
      "responses": 0,
      "monthly_avg_rating": 4.5,
      "overall_rating": 4.21
    },
    {
      "month": "Mar 2026",
      "reviews": 5,
      "responses": 0,
      "monthly_avg_rating": 4.4,
      "overall_rating": 4.21
    },
    {
      "month": "Apr 2026",
      "reviews": 33,
      "responses": 0,
      "monthly_avg_rating": 4.36,
      "overall_rating": 4.21
    },
    {
      "month": "May 2026",
      "reviews": 34,
      "responses": 0,
      "monthly_avg_rating": 4.47,
      "overall_rating": 4.21
    },
    {
      "month": "Jun 2026",
      "reviews": 30,
      "responses": 0,
      "monthly_avg_rating": 4.27,
      "overall_rating": 4.21
    },
    {
      "month": "Jul 2026",
      "reviews": 43,
      "responses": 0,
      "monthly_avg_rating": 4.53,
      "overall_rating": 4.21
    },
    {
      "month": "Aug 2026",
      "reviews": 38,
      "responses": 0,
      "monthly_avg_rating": 4.45,
      "overall_rating": 4.21
    },
    {
      "month": "Sep 2026",
      "reviews": 33,
      "responses": 0,
      "monthly_avg_rating": 4.33,
      "overall_rating": 4.21
    }
  ]
}

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`	One row per month.
`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-annual-volume-rating-stats?store_id=3007&review_site_id=44" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'