Performance by review site

Overview

Get reviews and ratings by site for the account.

Use this to see where reviews come from.

You'll need a token and a date range.

Returns one row per site, the site with the most reviews first.

Prerequisites

A bearer token. See Authentication.
A date range (range_start, range_end), both Y-m-d H:i:s.
Optional: a location id (store_id). Leave it out to report on every location your token can see.

Base URL

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

Endpoint

POST /api/v1/reports/response/reviews/site

Authentication

Partner or Account token

store_id must be inside your own account tree; otherwise 422.
Without store_id, the report covers 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.
There are no account_id or client_* fields here.

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
`range_start`	string	Yes	Start of the period, `Y-m-d H:i:s` (e.g. `2026-01-01 00:00:00`). A date without a time is rejected.
`range_end`	string	Yes	End of the period, `Y-m-d H:i:s` (e.g. `2026-09-30 23:59:59`).
`store_id`	integer	No	One location to report on. Must exist and be inside your account tree. Leave it out to cover every location your token can see.

Request payload

{
  "range_start": "2026-01-01 00:00:00",
  "range_end": "2026-09-30 23:59:59",
  "store_id": 3007
}

Response body

data is an array with one row per review site that has reviews in the period, sorted by reviews_count, highest first. It's [] when there are no reviews.

Field	Type	Description
`data[]`	array of objects	One row per review site with reviews in the period, most reviews first. `[]` when there are none.
`data[].id`	integer	The review site's id (`review_site_id`).
`data[].review_site`	string	The review site's name in lower case, e.g. `google`.
`data[].review_site_logo`	string or null	URL of the site's logo.
`data[].reviews_count`	integer	Reviews from this site in the period.
`data[].avg_rating`	number	Average star rating of this site's reviews in the period.
`data[].per_of_total`	number	This site's share of the period's reviews, in percent.
`data[].total_response`	integer	Responses to this site's reviews, not counting failed ones (no login saved, login error, not responding, business already responded).
`data[].per_total_response`	number	`total_response` as a percentage of `reviews_count`.
`data[].response_rate_pct`	number	Percentage of this site's reviews that have a response of any kind.
`data[].avg_response_time`	number	Average time to respond, in days. `0` when there are no responses.
`data[].awaiting_response`	integer	Reviews from this site in the period with no response yet that the location may respond to.

Response payload

{
  "data": [
    {
      "id": 44,
      "review_site": "google",
      "review_site_logo": "https://d2ny6zb7otrnhl.cloudfront.net/assets/backend/images/logos/google_ic.png",
      "reviews_count": 223,
      "avg_rating": 4.4,
      "per_of_total": 100,
      "total_response": 0,
      "per_total_response": 0,
      "response_rate_pct": 0,
      "avg_response_time": 0,
      "awaiting_response": 223
    }
  ]
}

Examples

Success payload

One location: see Response payload.

No reviews in the period:

{
  "data": []
}

Error payload

422 Dates missing

{
  "message": "The range start field is required. (and 1 more error)",
  "errors": {
    "range_start": [
      "The range start field is required."
    ],
    "range_end": [
      "The range end field is required."
    ]
  }
}

422 Date not in Y-m-d H:i:s

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

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

429 Too many requests

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

Status	Meaning
`200`	One row per review site, or `[]` when there are no reviews.
`401`	The token is missing, expired or invalid.
`422`	`range_start` or `range_end` is missing or not in `Y-m-d H:i:s` format (a bare date is rejected), or `store_id` is outside your tree.
`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/reports/response/reviews/site" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"range_start": "2026-01-01 00:00:00", "range_end": "2026-09-30 23:59:59", "store_id": 3007}'