Social Reviews (Star Ratings)

The Social Reviews Read API allows partners to retrieve aggregated page-level star rating data for a conversation or article.

This API is designed for building custom rating widgets and displaying Social Reviews data outside of OpenWeb surfaces.

Use Cases

Common use cases include:

• Displaying article star ratings and review counts
• Building custom publisher-side rating widgets
• Syncing Social Reviews data into analytics or internal UI systems

Base URL

https://api-2-0.spot.im

Authentication

Include the following headers in every request.

x-spot-id: {spot-id}
x-post-id: {post-id}

Endpoints

Get Star Rating Summary

Returns aggregated rating data for a conversation or page.

GET /v1.0.0/star-rating/summary/{conversation-id}

Path Parameters

Example:

sp_123_post1

Request Headers

Request Example

curl --location 'https://api-2-0.spot.im/v1.0.0/star-rating/summary/sp_123_post1' \
--header 'x-spot-id: sp_123' \
--header 'x-post-id: post1'

Response

HTTP Status

200 OK

Response Body

Example Response

{
  "summary": {
    "1": 60,
    "2": 50,
    "3": 74,
    "4": 102,
    "5": 174
  },
  "total": 460,
  "average": 3.6086957,
  "status": "ok"
}

Behavior

• Returns aggregated rating data for the requested page or conversation
• Data reflects submitted ratings from Social Reviews
• If no ratings exist:
  • total returns 0
  • average may return 0 or null

Constraints and Notes

Keep the following implementation details and requirements in mind when integrating with the API:

• conversation-id must match the {spot-id}_{post-id} format used by Conversations
• This API is read-only
• Access control is aligned with existing public APIs
• The response structure is intended to remain stable for UI integrations

Limitations

This API intentionally provides aggregated read-only rating data and does not support the following functionality.

• Individual user ratings
• Rating history or trends
• Real-time updates
• Write or update capabilities

Updated results require a page refresh or a new API request.

Dependencies

The following requirements must be met:

• Social Reviews must be enabled on the page
• The provided spot-id and post-id values must be valid and mapped correctly

Suggested UX Patterns

Display Patterns

Here are a few common ways partners may choose to display rating data:

• ⭐ 4.2 (128 reviews)
• Star icons with total rating count
• Empty-state messaging such as "No ratings yet"

Interaction Patterns

For the best user experience, treat the widget as a lightweight entry point into the full Social Reviews experience rather than a standalone rating system.

When a user clicks the widget or star rating:

• Scroll the user to the Conversation section
• Focus the interactive star rating module within the conversation header