Ranking report (full payload)

Overview

Ranks the authenticated account's locations against each other over a date range — by review volume, average rating, and response rate. It then computes a blended overall rank with a letter grade.

Prerequisites

• A bearer token. Callable with Account (bundle_id=3) or location (bundle_id=2) tokens; partner tokens are rejected with 403.

Base URL

Endpoint

POST /api/v1/reports/ranking

Authentication

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

• Who can call it: Account or location tokens (bundle_id 3 or 2). Partner tokens get 403.

• Uses a Passport bearer.

• Inside rankingReport the caller's company bundle_id must be 3 (account) or 2 (location-account); any other role gets a 403.

• Walking UP resolves the account name.

• Store scope comes from unless you supply store_id.

• Reachable stores differ per role. A location-level user (bundle_id=2 / assign_location) sees only its assigned store(s), while an account-level user sees every store under the account's location-account children.

• The optional store_id must sit inside your own account tree, so it must resolve to a store inside the caller's own hierarchy.

Rate limit

• No rate limit.

Request body

• Body (all in JSON body):

{
  "range_start": "2024-01-01 00:00:00",
  "range_end": "2024-12-31 23:59:59",
  "store_id": 1
}

Response

• data.account_name (string) — the parent account company name (null if no account resolved).
• data.interval (object) — start and end, echoed verbatim from the request.
• data.locationRank (object) — four arrays of per-location rows:
• byReview (array) — locations ranked by review_count; each row: id, name, review_count, response_count, response_percent, avgRating, rank.
• byRate (array) — same row shape, ranked by avgRating.
• byResponse (array) — same row shape, ranked by response_percent.
• overAll (array) — each row adds reviewRank, rateRank, responseRank, totalRank (sum of the three), final_grade (A+/A/B/C/D), final_grade_point. When there are 10+ distinct total ranks, a percentage_rank band (e.g. Top 10%) is also added.
• When no locations have data, all four arrays are empty.

200 Success · 200

{
  "data": {
    "account_name": "Burger King",
    "interval": {
      "start": "2024-01-01 00:00:00",
      "end": "2024-12-31 23:59:59"
    },
    "locationRank": {
      "byReview": [
        {
          "id": 12314,
          "name": "Burger King 1 - LOC-001",
          "review_count": 10,
          "response_count": 8,
          "response_percent": 80.0,
          "avgRating": 4.5,
          "rank": 1
        }
      ],
      "byRate": [
        {
          "id": 12314,
          "name": "Burger King 1 - LOC-001",
          "review_count": 10,
          "response_count": 8,
          "response_percent": 80.0,
          "avgRating": 4.5,
          "rank": 1
        }
      ],
      "byResponse": [
        {
          "id": 12314,
          "name": "Burger King 1 - LOC-001",
          "review_count": 10,
          "response_count": 8,
          "response_percent": 80.0,
          "avgRating": 4.5,
          "rank": 1
        }
      ],
      "overAll": [
        {
          "id": 12314,
          "name": "Burger King 1 - LOC-001",
          "review_count": 10,
          "response_count": 8,
          "response_percent": 80.0,
          "avgRating": 4.5,
          "reviewRank": 1,
          "rateRank": 2,
          "responseRank": 1,
          "totalRank": 4,
          "final_grade": "A+",
          "final_grade_point": 5
        }
      ]
    }
  }
}

Errors

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/reports/ranking" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"range_start": "2024-01-01 00:00:00", "range_end": "2024-12-31 23:59:59", "store_id": 1}'