Developer Reference

Business Insights API

Pull your review sentiment, competitor benchmarking and regional performance data programmatically. A read-only, key-authenticated REST API returning JSON.

base url /api/v1 Format JSON Rate limit 120/min
Overview

Introduction

The Business Insights API gives you programmatic, read-only access to the same analytics you see in your dashboard: sentiment, competitor benchmarking and regional performance, returned as JSON. Every request is authenticated with your business API key and scoped to your business only.

All endpoints are GET requests under /api/v1.

curl https://www.ratecrest.com/api/v1/insights/sentiment-analysis \
  -H "X-Api-Key: rc_your_key_here"
const res = await fetch(
  "https://www.ratecrest.com/api/v1/insights/sentiment-analysis",
  { headers: { "X-Api-Key": "rc_your_key_here" } }
);
const data = await res.json();
$ch = curl_init("https://www.ratecrest.com/api/v1/insights/sentiment-analysis");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: rc_your_key_here"]);
$data = json_decode(curl_exec($ch), true);
Step 1

Get your API key

Your API key is tied to your business. Generate one from your business settings under API Access. The full key is shown once at generation, so copy it and store it safely. Lose it and you simply generate a new one; the old key stops working immediately.

Generate a key in Settings 
# Looks like:
rc_3f9a1c8e2b7d40a5e1f6c9b8a2d4e7f0
Step 2

Authentication

Send your key with every request using any one of these three methods. Requests without a valid key for an active business return 401.

MethodHow
HeaderX-Api-Key: KEY
BearerAuthorization: Bearer KEY
Query?api_key=KEY
Keep it secret. Prefer the header or Bearer methods server-side. The query parameter is handy for testing but can leak into logs.
# Header (recommended)
curl https://www.ratecrest.com/api/v1/insights \
  -H "X-Api-Key: rc_your_key_here"

# Bearer
curl https://www.ratecrest.com/api/v1/insights \
  -H "Authorization: Bearer rc_your_key_here"
fetch("https://www.ratecrest.com/api/v1/insights", {
  headers: { "Authorization": "Bearer rc_your_key_here" }
});
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer rc_your_key_here"
]);

Selecting a period

By default an endpoint returns the most recent month that has data. Request a specific month, or an aggregated range, with query parameters.

ParameterDescription
year, monthA single month. Month is 1 to 12.
year_from month_from year_to month_toAn aggregated range. All four required together.
# A specific month
curl "https://www.ratecrest.com/api/v1/insights?year=2026&month=3" \
  -H "X-Api-Key: rc_your_key_here"

# A range
curl "https://www.ratecrest.com/api/v1/insights/sentiment-analysis/trends?year_from=2026&month_from=1&year_to=2026&month_to=3" \
  -H "X-Api-Key: rc_your_key_here"

Response shape

Every successful response shares the same envelope: a success flag, a meta block describing the period, and a data block. Inside data you always get a summary, plus a nested data object holding the endpoint-specific fields.

When there is no data for the requested period, the response is still 200 with "data": null and an explanatory message.
{
  "success": true,
  "meta": {
    "year": 2026, "month": 3,
    "period_label": "March 2026",
    "available_months": [
      { "year": 2026, "month": 3, "label": "March 2026" }
    ]
  },
  "data": {
    "summary": {
      "total_reviews": 352, "avg_rating": 3.7,
      "net_sentiment_score": 45, "response_rate": 45.2,
      "avg_response_time_hours": 38.12
    },
    "data": { /* endpoint-specific, see below */ }
  }
}

Errors

Authentication failures return 401; exceeding the rate limit returns 429.

StatusMeaning
200Success. A period with no data is still 200 with a null data block.
401Missing, invalid, or inactive-business key.
429Rate limit exceeded (120/min).
{
  "success": false,
  "message": "Invalid or inactive API key."
}
Sentiment Analysis
GET/insights/sentiment-analysis
Sentiment overview
data.data: statsdistribution
GET/insights/sentiment-analysis/trends
Sentiment trends
data.data: statstrend_alerts
GET/insights/sentiment-analysis/aspect-based-sentiment
Aspect-Based Sentiment
data.data: aspects
GET/insights/sentiment-analysis/emotions-experience
Emotions and experience
data.data: emotionsemotion_alerts
GET/insights/sentiment-analysis/drivers-topics
Drivers and topics
data.data: topics
GET/insights/sentiment-analysis/language-tone
Language and tone
data.data: tonestone_alerts
GET/insights/sentiment-analysis/response-impact
Response Impact
data.data: response_impact
GET/insights/sentiment-analysis/alerts
Sentiment alerts
data.data: alertstrend_alertsemotion_alertstone_alerts
{
  "data": { "data": {
    "stats": {
      "total_reviews": 352, "net_sentiment": 45,
      "avg_rating": 3.7, "response_rate": 45.2,
      "response_rate_change": 2.1
    },
    "distribution": [
      { "label": "Positive", "percent": 63, "count": 221 }
    ]
  } }
}
Competitor Benchmarking
GET/insights/competitor-benchmarking
Competitor overview
data.data: executivecomparison_tablestrengthsopportunitiesoverview_insights
GET/insights/competitor-benchmarking/trends
Competitor trends
data.data: comparison_tabletrends_insightsvelocity
GET/insights/competitor-benchmarking/theme-sentiment
Theme Sentiment
data.data: theme_sentimenttheme_sentiment_insightsexecutive
GET/insights/competitor-benchmarking/regional-performance
Regional Performance
data.data: regional_matrixregional_insights
GET/insights/competitor-benchmarking/alerts-movement
Alerts and movement
data.data: insightsmarket_position
GET/insights/competitor-benchmarking/industry-leaderboard
Industry Leaderboard
data.data: leaderboardratings_leaderboardgrowth_leaderboardresponsiveness_leaderboardsentiment_leaderboardleaderboard_insights
{
  "data": { "data": {
    "executive": {
      "avg_rating": 3.7, "net_sentiment": 45,
      "competitor_avg_rating": 3.3, "competitor_count": 4
    },
    "comparison_table": [
      { "name": "Your Business", "rating": 3.7,
        "reviews": 352, "response_rate": "45%" }
    ]
  } }
}
Regional Heatmap
GET/insights/regional-heatmap
Regional overview
data.data: total_regionsmost_activefastest_growingavg_per_statestates
GET/insights/regional-heatmap/review-activity-heatmap
Review Activity Heatmap
data.data: states
GET/insights/regional-heatmap/review-velocity
Review Velocity
data.data: states
GET/insights/regional-heatmap/issue-frequency-by-region
Issue Frequency by Region
data.data: issue_frequency
GET/insights/regional-heatmap/emerging-risk-zones
Emerging Risk Zones
data.data: risk_alerts
GET/insights/regional-heatmap/engagement-response-gaps
Engagement and response gaps
data.data: engagement_gaps
GET/insights/regional-heatmap/regional-trends
Regional Trends
data.data: trend_alerts
{
  "data": { "data": {
    "total_regions": 32,
    "most_active": "Ebonyi", "most_active_count": 18,
    "fastest_growing": "Ebonyi", "avg_per_state": 11,
    "states": [
      { "state": "Ebonyi", "total_reviews": 18,
        "avg_rating": 3.8, "net_sentiment": 33 }
    ]
  } }
}