Rating breakdown

Overview

Get counts by star rating.

Use this for a distribution chart.

You'll need a token. Send both range_start and range_end to count only that window; otherwise the counts are all-time.

Returns counts per star. Only star values that have at least one review appear.

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

Endpoint

GET /api/v1/account/dashboard/get-review-rating-breakdown

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

Request body

None.

Request payload

None.

Response body

data is an object keyed by star value, from "1 Star" to "5 Star". A star value with no reviews is left out, so data is {} when there are none.

Response payload

{
  "data": {
    "1 Star": 4,
    "2 Star": 5,
    "3 Star": 22,
    "4 Star": 58,
    "5 Star": 134
  }
}

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."
}

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/account/dashboard/get-review-rating-breakdown?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'