Annual volume and rating

Overview

Get review volume and rating by month over a year.

Use this for a multi-year view.

You'll need a token and an account or location to report on (account_id, store_id, or your own client_account_id / client_location_id).

Returns 12 monthly rows, oldest first, ending with the month of date (this month when date is left out).

Prerequisites

A bearer token. See Authentication.
An account (account_id or client_account_id) or a location (store_id or client_location_id) to report on. At least one is required.

Base URL

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

Endpoint

POST /api/v1/graph/annual-volume

Authentication

Partner or Account token

Every id you send must be inside your own account tree; otherwise 422.
An Account token sends its own account or one of its locations; a Partner token can send any account or location under the partner.
account_id must be an account (not a partner or a location company).
Scope, in order: store_id (or client_location_id) is one location; otherwise account_id (or client_account_id) is every location of that account.

Rate limit

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

Request parameters

None.

Request body

Field	Type	Required	Description
`account_id`	integer	No	The account to report on (all its locations). Must be an account inside your tree. Required unless you send `store_id`, `client_location_id` or `client_account_id`.
`store_id`	integer	No	One location to report on. Must exist and be inside your tree. Required unless you send `account_id`, `client_location_id` or `client_account_id`. Takes priority over `account_id`.
`client_location_id`	string	No	Your own id for the location, instead of `store_id`. Up to 255 characters. Ignored when `store_id` is sent.
`client_account_id`	string	No	Your own id for the account, instead of `account_id`. Up to 255 characters. Ignored when `account_id` is sent.
`review_site_id`	integer	No	Only this review site, e.g. `44` for Google. Must be an existing review site.
`date`	string	No	Reference date, `Y-m-d`; the 12 months end with this date's month. Default: today.

Request payload

{
  "account_id": 5994,
  "review_site_id": 44,
  "date": "2025-06-01"
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`data[]`	array of objects	12 rows, one per month, oldest first.
`data[].month`	string	The month as `Month-YYYY`, e.g. `June-2025`.
`data[].reviews`	integer	Reviews that month.
`data[].avg_rating`	number	Average rating of that month's reviews, not rounded. `0` when there are none.
`data[].overall_rating`	number	Average rating of all reviews up to the end of that month, not rounded.
`data[].responses`	integer	Responses to that month's reviews.

Response payload

{
  "data": {
    "status": "success",
    "data": [
      {
        "month": "July-2024",
        "reviews": 2,
        "avg_rating": 5,
        "overall_rating": 4.1065,
        "responses": 0
      },
      {
        "month": "August-2024",
        "reviews": 4,
        "avg_rating": 4,
        "overall_rating": 4.1055,
        "responses": 0
      },
      {
        "month": "September-2024",
        "reviews": 2,
        "avg_rating": 5,
        "overall_rating": 4.1098,
        "responses": 0
      },
      {
        "month": "October-2024",
        "reviews": 3,
        "avg_rating": 4.6667,
        "overall_rating": 4.1137,
        "responses": 0
      },
      {
        "month": "November-2024",
        "reviews": 5,
        "avg_rating": 3.4,
        "overall_rating": 4.1054,
        "responses": 0
      },
      {
        "month": "December-2024",
        "reviews": 5,
        "avg_rating": 4.2,
        "overall_rating": 4.1065,
        "responses": 0
      },
      {
        "month": "January-2025",
        "reviews": 3,
        "avg_rating": 4.6667,
        "overall_rating": 4.1103,
        "responses": 0
      },
      {
        "month": "February-2025",
        "reviews": 2,
        "avg_rating": 4,
        "overall_rating": 4.1098,
        "responses": 0
      },
      {
        "month": "March-2025",
        "reviews": 0,
        "avg_rating": 0,
        "overall_rating": 4.1098,
        "responses": 0
      },
      {
        "month": "April-2025",
        "reviews": 3,
        "avg_rating": 4.6667,
        "overall_rating": 4.1136,
        "responses": 0
      },
      {
        "month": "May-2025",
        "reviews": 3,
        "avg_rating": 4.3333,
        "overall_rating": 4.1151,
        "responses": 0
      },
      {
        "month": "June-2025",
        "reviews": 3,
        "avg_rating": 4,
        "overall_rating": 4.1143,
        "responses": 0
      }
    ]
  }
}

Examples

Success payload

One account, Google, year to June 2025: see Response payload.

One location, Google, no date (called in October 2026):

{
  "data": {
    "status": "success",
    "data": [
      {
        "month": "November-2025",
        "reviews": 1,
        "avg_rating": 5,
        "overall_rating": 4.125,
        "responses": 0
      },
      {
        "month": "December-2025",
        "reviews": 3,
        "avg_rating": 1.6667,
        "overall_rating": 4.1089,
        "responses": 0
      },
      {
        "month": "January-2026",
        "reviews": 3,
        "avg_rating": 3.6667,
        "overall_rating": 4.1061,
        "responses": 0
      },
      {
        "month": "February-2026",
        "reviews": 4,
        "avg_rating": 4.5,
        "overall_rating": 4.1094,
        "responses": 0
      },
      {
        "month": "March-2026",
        "reviews": 5,
        "avg_rating": 4.4,
        "overall_rating": 4.1125,
        "responses": 0
      },
      {
        "month": "April-2026",
        "reviews": 33,
        "avg_rating": 4.3636,
        "overall_rating": 4.129,
        "responses": 0
      },
      {
        "month": "May-2026",
        "reviews": 34,
        "avg_rating": 4.4706,
        "overall_rating": 4.1506,
        "responses": 0
      },
      {
        "month": "June-2026",
        "reviews": 30,
        "avg_rating": 4.2667,
        "overall_rating": 4.1567,
        "responses": 0
      },
      {
        "month": "July-2026",
        "reviews": 43,
        "avg_rating": 4.5349,
        "overall_rating": 4.1833,
        "responses": 0
      },
      {
        "month": "August-2026",
        "reviews": 38,
        "avg_rating": 4.4474,
        "overall_rating": 4.1988,
        "responses": 0
      },
      {
        "month": "September-2026",
        "reviews": 33,
        "avg_rating": 4.3333,
        "overall_rating": 4.2053,
        "responses": 0
      },
      {
        "month": "October-2026",
        "reviews": 0,
        "avg_rating": 0,
        "overall_rating": 4.2053,
        "responses": 0
      }
    ]
  }
}

Error payload

422 No account or location

{
  "message": "The account id field is required when none of store id / client location id / client account id are present. (and 1 more error)",
  "errors": {
    "account_id": [
      "The account id field is required when none of store id / client location id / client account id are present."
    ],
    "store_id": [
      "The store id field is required when none of account id / client location id / client account id are present."
    ]
  }
}

422 account_id is not an account

{
  "message": "The selected account id is invalid.",
  "errors": {
    "account_id": [
      "The selected account id is invalid."
    ]
  }
}

422 Account outside your tree

{
  "message": "The selected account id is invalid. (and 1 more error)",
  "errors": {
    "account_id": [
      "The selected account id is invalid.",
      "The selected account id does not belong to your company hierarchy."
    ]
  }
}

422 date not in Y-m-d

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

429 Too many requests

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

Status	Meaning
`200`	Twelve monthly rows.
`401`	The token is missing, expired or invalid.
`422`	No account or location sent, an id doesn't exist, isn't an account, or is outside your tree, `review_site_id` doesn't exist, or `date` isn't `Y-m-d`.
`429`	More than 120 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/graph/annual-volume" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"account_id": 5994, "review_site_id": 44, "date": "2025-06-01"}'

Updated 17 days ago

Did this page help you?