Get overall ranking by location (last 12 months)

Overview

Overall location ranking for the selected window (default last 12 months): 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). Same endpoint as the primary last-12-months ranking page; this variant demonstrates passing an explicit range_start/range_end window.

Prerequisites

• A bearer token. Callable with Account tokens.

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: Account tokens.

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

• Scope is the caller's company tree.

• store_id (if given) is validated by an ownership check; otherwise all of the caller's stores are used (honouring the user's assign_location/assign_brand restrictions).

Rate limit

• No rate limit.

Query parameters

• Query: store_id (integer, optional) — must belong to the caller's company; omit it to cover all of your locations.
• Query: review_site_id (integer, optional) — filter to one platform; must be an existing review site.
• Query: range_start (string, optional) — REQUIRES full datetime format Y-m-d H:i:s (this endpoint's form request rejects bare Y-m-d). Defaults to start of 13 months ago when you omit it.
• Query: range_end (string, optional) — Y-m-d H:i:s, 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.
• review_count (integer) — qualifying review count (for hipages, unified across all connected sites).
• response_count (string) — "<count> (<percent>%)".

200 Success · 200

{
  "data": [
    {
      "id": "loc_42",
      "final_grade": "A",
      "name": "Downtown - LOC-001",
      "avgRating": "4.48",
      "review_count": 196,
      "response_count": "181 (92%)"
    }
  ]
}

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