Twelve-month ranking (explicit window)

Overview

Get your top 10 locations, ranked on review count, average rating and response rate combined, passing an explicit range_start/range_end window. Same endpoint as Twelve-month ranking; this variant shows the full datetime window form.

You'll need a token and the window.

Returns the ranked list, best first.

Prerequisites

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

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

This endpoint has no rate limit.

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.40",
      "review_count": 223,
      "response_count": "0 (0%)"
    }
  ]
}

Examples

Success payload

See Response payload.

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

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.
`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&range_start=2026-01-01%2000:00:00&range_end=2026-09-30%2023:59:59" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'