Top locations

Overview

Get the account's best locations by review volume, with their rating.

Use this for a highlights panel.

You'll need an account token. Send both range_start and range_end to count only that window; otherwise the counts are all-time.

Returns up to three locations, most reviews first. Locations with no reviews are left out.

Prerequisites

• A bearer token. See Authentication.
• Optional: a date range (range_start, range_end, both Y-m-d).

Base URL

Endpoint

GET /api/v1/account/dashboard/get-top-performing-locations

Authentication

Account token

• The list covers 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

Request body

None.

Request payload

None.

Response body

data is an array of up to three locations, most reviews first.

Response payload

{
  "data": [
    {
      "store_id": 3007,
      "store_name": "Acme Coffee - docs-test-loc-001",
      "reviews": 223,
      "rating": 4.4
    }
  ]
}

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

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/account/dashboard/get-top-performing-locations?range_start=2026-01-01&range_end=2026-09-30" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'