Overall ranking by location (last 12 months)

Overview

Overall location ranking for the selected window: up to 10 store locations ranked and graded by review count, response rate, and average rating (for hipages stores, counts span reviews from all connected sites). Identical to the primary last-12-months ranking page. The only difference is this variant passes range_start/range_end as full Y-m-d H:i:s datetimes, which is exactly what the endpoint requires.

Prerequisites

• A bearer token. Callable with any valid bearer token.

Base URL

Endpoint

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

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: any authenticated user; results are scoped to the caller's own account tree.

• Authentication, under the account/dashboard group (role-agnostic; no partner-only access).

• Scope is the authenticated user's own company tree. When you supply store_id it must sit inside your own account tree.

• Otherwise all stores under the user, which itself honours the user's assign_location/assign_brand restrictions.

Rate limit

• No rate limit.

Query parameters

• Query: store_id (integer, optional) — must exist and belong to the caller's company; omit it to cover all of your locations.
• Query: review_site_id (integer, optional) — filter to one platform (e.g. 5); must be an existing review site.
• Query: range_start (string Y-m-d H:i:s, optional) — defaults to start of 13 months ago. NOTE: this endpoint requires the full datetime format Y-m-d H:i:s (unlike most other dashboard endpoints which use Y-m-d).
• Query: range_end (string Y-m-d H:i:s, optional) — must be ≥ range_start; defaults to end of last month.

Response

• id (string) — loc_<store id>.
• final_grade (string) — overall letter grade (e.g. A+, N/A).
• name (string) — "<store name> - <storeid>".
• avgRating (string) — average rating formatted to 2 decimals (e.g. "0.00").
• review_count (integer) — qualifying review count (for hipages stores, unified across all connected sites).
• response_count (string) — "<count> (<percent>%)".

200 OK · 200

{
  "data": [
    {
      "id": "loc_101",
      "final_grade": "A",
      "name": "North Branch - NB01",
      "avgRating": "4.62",
      "review_count": 248,
      "response_count": "231 (93%)"
    },
    {
      "id": "loc_102",
      "final_grade": "B",
      "name": "South Branch - SB02",
      "avgRating": "4.18",
      "review_count": 173,
      "response_count": "140 (81%)"
    }
  ]
}

422 Validation error · 422

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

Errors

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/account/dashboard/get-overall-ranking-bylocation-last12months?store_id=123&review_site_id=5&range_start=2025-06-01%2000:00:00&range_end=2026-05-31%2023:59:59" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'