Sentiment

Overview

Get the number of positive, neutral, and negative reviews.

Use this for a sentiment chart.

You'll need an account token. Send both range_start and range_end to count only that window and get a comparison with the previous window (the same length, immediately before range_start).

Returns the three counts (not percentages).

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/sentiment-overview

Authentication

Account token

The counts cover the locations of the caller's own account (the locations whose account is the caller's company). A Partner token has no locations of its own here, so it gets no data (zero counts or an empty list).
A user limited to some locations sees only those.

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	Only this location. Must exist and be inside your account tree.
`review_site_id`	query	integer	No	Only this review site, e.g. `44` for Google. Must be an existing review site (an integer).
`range_start`	query	string	No	Start of the window, `Y-m-d`. Used only together with `range_end`.
`range_end`	query	string	No	End of the window, `Y-m-d`. Must be on or after `range_start`. Used only together with `range_start`.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`positive_count`	integer	Reviews rated above 3 stars.
`neutral_count`	integer	The rest: 3-star reviews, and Facebook reviews with no star rating.
`negative_count`	integer	Reviews rated below 3 stars.
`comparison`	object or null	The window against the previous one. `null` unless both `range_start` and `range_end` are sent.
`comparison.previous_period`	object	The previous window: the same length, immediately before `range_start`.
`comparison.previous_period.range_start`	string	First day of the previous window, `Y-m-d`.
`comparison.previous_period.range_end`	string	Last day of the previous window, `Y-m-d`.
`comparison.positive_count`	object	`positive_count`: this period against the previous one.
`comparison.positive_count.current`	number	Value for the selected window.
`comparison.positive_count.previous`	number	Value for the previous window.
`comparison.positive_count.change_pct`	number or null	Change from `previous` to `current`, in percent, one decimal. `null` when `previous` is 0.
`comparison.positive_count.direction`	string	`up`, `down` or `flat` (`flat` when there's no change or `change_pct` is `null`).
`comparison.neutral_count`	object	`neutral_count`: this period against the previous one.
`comparison.neutral_count.current`	number	Value for the selected window.
`comparison.neutral_count.previous`	number	Value for the previous window.
`comparison.neutral_count.change_pct`	number or null	Change from `previous` to `current`, in percent, one decimal. `null` when `previous` is 0.
`comparison.neutral_count.direction`	string	`up`, `down` or `flat` (`flat` when there's no change or `change_pct` is `null`).
`comparison.negative_count`	object	`negative_count`: this period against the previous one.
`comparison.negative_count.current`	number	Value for the selected window.
`comparison.negative_count.previous`	number	Value for the previous window.
`comparison.negative_count.change_pct`	number or null	Change from `previous` to `current`, in percent, one decimal. `null` when `previous` is 0.
`comparison.negative_count.direction`	string	`up`, `down` or `flat` (`flat` when there's no change or `change_pct` is `null`).

Response payload

{
  "data": {
    "positive_count": 192,
    "neutral_count": 22,
    "negative_count": 9,
    "comparison": {
      "previous_period": {
        "range_start": "2025-04-03",
        "range_end": "2025-12-31"
      },
      "positive_count": {
        "current": 192,
        "previous": 17,
        "change_pct": 1029.4,
        "direction": "up"
      },
      "neutral_count": {
        "current": 22,
        "previous": 1,
        "change_pct": 2100,
        "direction": "up"
      },
      "negative_count": {
        "current": 9,
        "previous": 4,
        "change_pct": 125,
        "direction": "up"
      }
    }
  }
}

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_id not an integer

{
  "message": "The review site id field must be an integer.",
  "errors": {
    "review_site_id": [
      "The review site id field must be an integer."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The three counts.
`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` isn't an existing review site.
`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/sentiment-overview?store_id=3007&range_start=2026-01-01&range_end=2026-09-30" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'