CEORater

API Documentation

Programmatic access to CEO performance metrics and company data

Base URL

https://ceorater-api.onrender.com

Quick Navigation

Authentication Get API Metadata List Companies Get Company by Ticker Search Companies Companies & Tickers Health Check Data Formats Field Reference Code Examples Error Responses

Authentication

Public (free) key: CEORATER_PUBLIC_V1. Send it in the x-api-key header. We may rotate this key; if requests stop working, check the API Viewer for the current key.

All API requests require authentication using an API key. You can authenticate in two ways:

Option 1: Header (Recommended)

x-api-key: your_api_key_here

Option 2: Query Parameter

GET /v1/companies?api_key=your_api_key_here

401 Unauthorized: Missing or invalid API key

Endpoints

GET /v1/meta

Returns information about the current dataset.

Response Example:

{
  "count": 1247,
  "last_loaded": "2025-09-30T08:00:00.000Z"
}

GET /v1/companies

Retrieve a paginated list of companies with CEO ratings.

Query Parameters:

Parameter Type Default Description
limit integer 50 Number of results (max: 2000)
offset integer 0 Starting position for pagination
format string ui Response format: ui or raw

Example Request:

GET /v1/companies?limit=20&offset=0&format=ui
x-api-key: your_api_key_here

Response Example:

{
  "items": [
    {
      "Company Name": "Apple Inc.",
      "Ticker": "AAPL",
      "Sector": "Technology",
      "Industry": "Computer Manufacturing",
      "CEO Name": "Tim Cook",
      "Founder (Y/N)": "N",
      "CEORaterScore": 80,
      "AlphaScore": 83,
      "CompScore": "C",
      "TSR During Tenure": "2,140%",
      "Avg. Annual TSR": "152%",
      "TSR vs. QQQ": "949%",
      "Avg Annual TSR vs. QQQ": "67%",
      "Compensation ($ millions)": "$74.6M",
      "CEO Compensation Cost / 1% Avg TSR": "$0.492M",
      "Tenure (years)": "14.1 years"
    }
  ],
  "total": 1247,
  "offset": 0,
  "limit": 20
}

GET /v1/company/:ticker

Retrieve detailed information for a specific company.

Path Parameters:

ticker (string) - Stock ticker symbol (case-insensitive)

Query Parameters:

format (string) - Response format: ui or raw (default: ui)

Example Request:

GET /v1/company/AAPL?format=ui
x-api-key: your_api_key_here

Response Example (UI Format):

{
  "Company Name": "Apple Inc.",
  "Ticker": "AAPL",
  "Sector": "Technology",
  "Industry": "Computer Manufacturing",
  "CEO Name": "Tim Cook",
  "Founder (Y/N)": "N",
  "CEORaterScore": 80,
  "AlphaScore": 83,
  "CompScore": "C",
  "TSR During Tenure": "2,140%",
  "Avg. Annual TSR": "152%",
  "TSR vs. QQQ": "949%",
  "Avg Annual TSR vs. QQQ": "67%",
  "Compensation ($ millions)": "$74.6M",
  "CEO Compensation Cost / 1% Avg TSR": "$0.492M",
  "Tenure (years)": "14.1 years"
}

Response Example (Raw Format):

{
  "companyName": "Apple Inc.",
  "ticker": "AAPL",
  "sector": "Technology",
  "industry": "Computer Manufacturing",
  "ceo": "Tim Cook",
  "founderCEO": false,
  "ceoraterScore": 80,
  "alphaScore": 83,
  "compScore": "C",
  "tsrMultiple": 21.40,
  "tenureYears": 14.1,
  "avgAnnualTsrRatio": 1.52,
  "compensationMM": 74.6,
  "compPer1PctTsrMM": 0.492,
  "tsrVsQqqRatio": 9.49,
  "avgAnnualVsQqqRatio": 0.67
}

GET /status

Check API status and data freshness. No authentication required

Response Example:

{
  "state": "ok",
  "last_loaded": "2025-09-30T08:00:00.000Z",
  "total": 1247
}

Data Formats

UI Format (Default)

Human-readable format with formatted values:

  • Percentages with % symbol
  • Money with $ and M suffix
  • Tenure with years suffix
  • CompScore as letter grade (A-F)

Raw Format

Machine-readable format with numeric values:

  • All ratios as decimals (e.g., 21.40 for 2,140%)
  • Money values as pure numbers
  • Boolean for founder status
  • Null values for missing data

Field Reference

UI Format Field Raw Format Field Description Example
Company Name companyName Company Name "Apple Inc."
Ticker ticker Ticker Symbol "AAPL"
Sector sector Sector "Technology"
Industry industry Industry "Computer Manufacturing"
CEO Name ceo Current CEO Name "Tim Cook"
Founder (Y/N) founderCEO Founder CEO (Y/N) "N" / false
CEORaterScore ceoraterScore Overall Rating (0-100) 80
AlphaScore alphaScore Alpha Performance (0-100) 83
CompScore compScore Compensation Efficiency (A-F) "C"
TSR During CEO Tenure tsrMultiple Total Shareholder Return (TSR) "2,140%" / 21.40
Avg. Annual TSR avgAnnualTsrRatio Average Annual TSR "152%" / 1.52
TSR vs. QQQ tsrVsQqqRatio TSR vs. QQQ "949%" / 9.49
Avg Annual TSR vs. QQQ avgAnnualVsQqqRatio Avg Annual TSR vs. QQQ "67%" / 0.67
CEO Compensation ($ millions) compensationMM Total CEO Compensation "$74.6M" / 74.6
CEO Compensation / 1% Avg TSR compPer1PctTsrMM CEO Compensation Cost per Percentage Point TSR "$0.492M" / 0.492
Tenure (years) tenureYears CEO Tenure "14.1 years" / 14.1

Code Examples

JavaScript / Fetch

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://ceorater-api.onrender.com';

async function searchCompanies(query) {
  const response = await fetch(
    `${BASE_URL}/v1/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        'x-api-key': API_KEY
      }
    }
  );
  return response.json();
}

// Usage
const results = await searchCompanies('apple');
console.log(results.items);

Swift / iOS

struct CEORaterAPI {
    let baseURL = "https://ceorater-api.onrender.com"
    let apiKey = "your_api_key_here"
    
    func getCompany(ticker: String) async throws -> Company {
        let url = URL(string: "\(baseURL)/v1/company/\(ticker)?format=raw")!
        var request = URLRequest(url: url)
        request.addValue(apiKey, forHTTPHeaderField: "x-api-key")
        
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode(Company.self, from: data)
    }
}

Python

import requests

API_KEY = 'your_api_key_here'
BASE_URL = 'https://ceorater-api.onrender.com'

def list_companies(limit=50, offset=0):
    response = requests.get(
        f'{BASE_URL}/v1/companies',
        headers={'x-api-key': API_KEY},
        params={'limit': limit, 'offset': offset, 'format': 'raw'}
    )
    return response.json()

# Usage
data = list_companies(limit=20)
print(f"Total companies: {data['total']}")

cURL

# Search for companies
curl -X GET "https://ceorater-api.onrender.com/v1/search?q=technology" \
  -H "x-api-key: your_api_key_here"

# Get specific company
curl -X GET "https://ceorater-api.onrender.com/v1/company/AAPL?format=raw" \
  -H "x-api-key: your_api_key_here"

Error Responses

401 Unauthorized

{
  "error": "Missing or invalid API key"
}

404 Not Found

{
  "error": "Not found"
}

400 Bad Request

{
  "ok": false,
  "error": "Expected array at top level"
}

Rate Limiting & Caching

  • Cache-Control: Responses are cached for 60 seconds with stale-while-revalidate up to 10 minutes
  • CORS: Enabled for all origins
  • Data Refresh: Snapshot updates daily at configured UTC time

Support

For API access, technical support, or feature requests, please contact:

Email: support@ceorater.com

Web: https://www.ceorater.com/support.html