Twelve-month ranking

Overview

Get your top 10 locations, ranked on review count, average rating and response rate combined. With no dates, the window is the last 13 complete months (from the start of the month 13 months ago to the end of last month).

Use this for a long-view leaderboard.

You'll need a token.

Returns the ranked list, best first.

Prerequisites

A bearer token. See Authentication.
Optional: a location (store_id), a review site (review_site_id) and a window (range_start, range_end, both Y-m-d H:i:s).

Base URL

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

Endpoint

GET /api/v1/account/dashboard/get-overall-ranking-bylocation-last12months

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 cover every location your token can see.
`review_site_id`	query	integer	No	Only this review site, e.g. `44` for Google. Must be an existing review site.
`range_start`	query	string	No	Start of the window, `Y-m-d H:i:s` (this endpoint needs the time part; a bare `Y-m-d` returns `422`). The time is ignored: the window starts at the beginning of that day. Default: the start of the month 13 months ago.
`range_end`	query	string	No	End of the window, `Y-m-d H:i:s`. Must be on or after `range_start`. The time is ignored: the window ends at the end of that day. Default: the end of last month.

Request body

None.

Request payload

None.

Response body

data is an array of up to 10 locations, best first.

Field	Type	Description
`data[]`	array of objects	Up to 10 locations, best overall rank first.
`data[].id`	string	`loc_` followed by the location's id, e.g. `loc_3007`.
`data[].final_grade`	string	Overall grade: `A+`, `A`, `B`, `C` or `D` (fewer grades when few locations differ), or `N/A`.
`data[].name`	string	The location's name, then `-` and its `client_location_id` (or its store code when that's empty).
`data[].avgRating`	string	Average rating as text with 2 decimals, e.g. `"4.38"`.
`data[].review_count`	integer	Reviews in the window that count toward the rating.
`data[].response_count`	string	Responses and response rate as text: `"<count> (<percent>%)"`.

Response payload

{
  "data": [
    {
      "id": "loc_3007",
      "final_grade": "A+",
      "name": "Acme Coffee - docs-test-loc-001",
      "avgRating": "4.38",
      "review_count": 230,
      "response_count": "0 (0%)"
    },
    {
      "id": "loc_3008",
      "final_grade": "A",
      "name": "Acme Coffee - Circular Quay - Sydney",
      "avgRating": "0.00",
      "review_count": 0,
      "response_count": "0 (0%)"
    }
  ]
}

Examples

Success payload

No dates, so the last 13 complete months: see Response payload.

One location and Google, January to September 2026:

{
  "data": [
    {
      "id": "loc_3007",
      "final_grade": "A+",
      "name": "Acme Coffee - docs-test-loc-001",
      "avgRating": "4.40",
      "review_count": 223,
      "response_count": "0 (0%)"
    }
  ]
}

Error payload

422 Date without a time

{
  "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 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`	Up to 10 ranked locations.
`401`	The token is missing, expired or invalid.
`422`	A date isn't `Y-m-d H:i:s`, `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-overall-ranking-bylocation-last12months?store_id=3007&review_site_id=44" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'