Ranking report

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. (Same route/controller/request validation as Ranking report (full payload); this is the minimal-payload example without store_id.)

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

POST /api/v1/reports/ranking

Authentication

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

• Who can call it: Partner and Account tokens.

• 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.

• With no store_id, the ranked set is every store in the caller's scope.

• Per-role difference: a location-level user (bundle_id=2 / assign_location) gets only its assigned store(s); an account-level user gets all stores under the account's location-account children.

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

Response

• data.account_name (string) — the parent account company name (null if no account resolved).
• data.interval (object) — start and end, echoed from the request.
• data.locationRank (object):
• byReview (array) — ranked by review_count; row: id, name, review_count, response_count, response_percent, avgRating, rank.
• byRate (array) — same shape, ranked by avgRating.
• byResponse (array) — same shape, ranked by response_percent.
• overAll (array) — adds reviewRank, rateRank, responseRank, totalRank, final_grade (A+/A/B/C/D), final_grade_point; with 10+ distinct total ranks each row also carries a percentage_rank band.
• All four arrays are empty when no location has data in the window.

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