API Documentation

Reference documentation for the StockMarketCap JSON API: the versioned read-only endpoints under /api/v1 that serve market data to approved StockMarketCap integrations.

Overview

The StockMarketCap API is the JSON API that powers our own applications: the StockMarketCap iOS app and the StockMarketCap markets terminal on Reddit both read every number they display from these endpoints. It exposes the same data you see on stockmarketcap.io: global stock rankings by market cap, live quotes, sector performance, screener fundamentals, price history, analyst ratings, dividends, and market calendars, covering listed companies across the US, Canada, Europe, and Asia.

All endpoints are read-only HTTP GET and return JSON. The base URL for every path on this page is:

https://stockmarketcap.io/api/v1

This page documents the full endpoint surface so that platform reviewers and integration partners can see exactly what the API does. It is not an open public API: see Authentication below.

Authentication

Every /api/v1 endpoint requires an application key, sent with each request in the x-smc-app-key header. Keys are issued by StockMarketCap to approved applications only; today those are our own first-party integrations, the StockMarketCap iOS app and the StockMarketCap markets terminal on Reddit. There is no self-serve signup, and requests without a valid key receive an empty HTTP 403 response.

GET /api/v1/stats HTTP/1.1
Host: stockmarketcap.io
x-smc-app-key: <application key>

Endpoints marked Plus serve premium data and additionally require a StockMarketCap Plus entitlement; without one they return HTTP 401.

If you are interested in an approved integration or data partnership, contact [email protected].

Rate limits

All endpoints are rate limited. Each approved application is provisioned with per-minute and per-day request budgets sized for its real usage. Requests over budget receive HTTP 429 with a Retry-After header indicating when the window resets. Clients are expected to honor it and back off.

Conventions

Envelope: successful responses are JSON objects with a data field and, where useful, a meta field (totals, pagination, echo of applied filters). Errors return { "error": "..." } with an appropriate HTTP status.
Currencies: prices are served in each listing's local trading currency (the currency field), alongside server-converted USD fields such as priceUsd. USD fields are null when no exchange rate is available. Aggregates like market cap and enterprise value are in USD.
Dates: all dates are ISO 8601 strings (YYYY-MM-DD).
Caching: responses carry standard Cache-Control headers with freshness matched to the data (quotes on the order of seconds to a minute, calendars and reference data longer).
Example values: the response samples on this page are illustrative shapes with rounded numbers, not live market data.

Market endpoints

Whole-market views: the global overview, the ranked universe, batch quotes, search, the full screener dataset, sector performance, and 52-week extremes.

GET/stats

Market overview: total market cap in USD with its 24h move, breadth (advancers and decliners), total volume, and the day's top gainer and loser.

{
  "data": {
    "totalMarketCap": 125000000000000,
    "totalMarketCapChangePct": 0.4,
    "totalVolume": 750000000000,
    "stockCount": 4000,
    "advancers": 2200,
    "decliners": 1600,
    "topGainer": { "symbol": "AAPL", "name": "Apple Inc.", "changePct": 5.2, "country": "US" },
    "topLoser": { "symbol": "TSLA", "name": "Tesla, Inc.", "changePct": -4.8, "country": "US" }
  }
}

GET/rankings

The ranked stock universe, paginated. This is the same table the StockMarketCap homepage renders.

view marketCap (default), gainers, losers, or active.
region global (default), us, canada, europe, or asia. Ranks are renumbered over the filtered set.
limit Rows per page, 1 to 100 (default 50).
offset Pagination offset. meta.nextOffset is null on the last page.

{
  "data": [
    {
      "rank": 1,
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "sector": "Technology",
      "exchange": "NASDAQ",
      "country": "US",
      "currency": "USD",
      "price": 210,
      "priceUsd": 210,
      "change24h": 1.2,
      "change7d": 3.5,
      "marketCap": 3200000000000,
      "volume": 45000000,
      "spark": [205, 207, 210]
    }
  ],
  "meta": { "view": "marketCap", "region": "global", "total": 4000, "limit": 50, "offset": 0, "nextOffset": 50 }
}

GET/quotes

Current price, change, and a few fundamentals for a batch of symbols (used by portfolio and watchlist views).

symbols Required. Comma-separated tickers, up to 100 (for example symbols=AAPL,MSFT).

{
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "price": 210,
      "currency": "USD",
      "priceUsd": 210,
      "changePct": 1.2,
      "sector": "Technology",
      "country": "US",
      "exchange": "NASDAQ",
      "beta": 1.1,
      "dividendYield": 0.5,
      "peRatio": 32
    }
  ]
}

GET/search

Ticker and company name search, biggest companies first.

q Required. Search text, matched against symbol and company name.
limit Max results, 1 to 20 (default 10).

{
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "country": "US",
      "exchange": "NASDAQ",
      "currency": "USD",
      "price": 210,
      "priceUsd": 210,
      "changePct": 1.2,
      "marketCap": 3200000000000
    }
  ]
}

GET/screener

One rich row per stock (quote, valuation, and fundamentals) for the whole universe, sorted by market cap. Clients use this single dataset to drive screeners, themed lists, and metric views without per-symbol round-trips.

{
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "sector": "Technology",
      "exchange": "NASDAQ",
      "country": "US",
      "currency": "USD",
      "price": 210,
      "priceUsd": 210,
      "change24h": 1.2,
      "marketCap": 3200000000000,
      "volume": 45000000,
      "peRatio": 32,
      "priceToSales": 8.5,
      "priceToBook": 45,
      "evToEbitda": 24,
      "dividendYield": 0.5,
      "beta": 1.1,
      "eps": 6.5,
      "revenueTtm": 400000000000,
      "netIncomeTtm": 100000000000,
      "freeCashFlowTtm": 105000000000,
      "grossMargin": 45,
      "profitMargin": 25,
      "returnOnEquity": 150,
      "employees": 160000
    }
  ],
  "meta": { "total": 4000 }
}

GET/sectors

Sector performance: total market cap, total volume, average 24h change, stock count, and the largest stock per sector.

{
  "data": [
    {
      "rank": 1,
      "sector": "Technology",
      "slug": "technology",
      "stockCount": 800,
      "totalMarketCap": 25000000000000,
      "totalVolume": 90000000000,
      "averageChange24h": 0.8,
      "topStock": { "symbol": "NVDA", "name": "NVIDIA Corporation", "country": "US", "exchange": "NASDAQ", "marketCap": 3500000000000 }
    }
  ],
  "meta": { "total": 11 }
}

GET/sectors/{slug}

Stocks within one sector (by slug, for example technology), ranked by market cap.

limit Max rows, 1 to 200 (default 100).

{
  "data": [
    {
      "rank": 1,
      "symbol": "NVDA",
      "name": "NVIDIA Corporation",
      "country": "US",
      "currency": "USD",
      "price": 150,
      "priceUsd": 150,
      "change24h": 2.1,
      "marketCap": 3500000000000,
      "volume": 200000000,
      "spark": [145, 148, 150]
    }
  ],
  "meta": { "sector": "Technology", "total": 800 }
}

GET/extremes

52-week extremes: each stock's 52-week high and low and where the current price sits in that range.

type high (default) for names nearest their 52-week high, low for names nearest their low.
limit Max rows, 1 to 100 (default 50).

{
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "sector": "Technology",
      "country": "US",
      "exchange": "NASDAQ",
      "currency": "USD",
      "price": 210,
      "high": 212,
      "low": 160,
      "priceUsd": 210,
      "highUsd": 212,
      "lowUsd": 160,
      "pctOfRange": 96,
      "fromHigh": -0.9,
      "fromLow": 31
    }
  ],
  "meta": { "type": "high", "total": 50 }
}

Calendar endpoints

Upcoming scheduled events, soonest first.

GET/calendar/earnings

Upcoming scheduled earnings dates for tracked companies.

limit Max rows, 1 to 200 (default 80).

{
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "sector": "Technology",
      "country": "US",
      "exchange": "NASDAQ",
      "currency": "USD",
      "nextEarnings": "2026-07-30",
      "price": 210,
      "priceUsd": 210,
      "changePct": 1.2,
      "marketCap": 3200000000000
    }
  ],
  "meta": { "total": 80 }
}

GET/calendar/dividends

Upcoming ex-dividend events for tracked tickers, with the per-share amount and yield.

{
  "data": [
    {
      "symbol": "KO",
      "name": "The Coca-Cola Company",
      "country": "US",
      "exchange": "NYSE",
      "currency": "USD",
      "exDate": "2026-07-15",
      "paymentDate": "2026-08-01",
      "dividend": 0.51,
      "dividendUsd": 0.51,
      "yield": 2.9
    }
  ],
  "meta": { "total": 40 }
}

GET/calendar/ipos

Upcoming IPOs, soonest first.

{
  "data": [
    {
      "symbol": "NEWCO",
      "company": "Newco Holdings",
      "date": "2026-07-20",
      "exchange": "NASDAQ",
      "shares": 10000000,
      "priceRange": "18.00-20.00"
    }
  ],
  "meta": { "total": 12 }
}

Stock endpoints

Per-symbol data. {symbol} is the ticker as listed on StockMarketCap (for example AAPL). Unknown symbols return a 404 with an error body.

GET/stocks/{symbol}

Company profile with the live quote and key valuation stats. Aggregate figures such as enterpriseValue are served in USD.

{
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "exchange": "NASDAQ",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "description": "Apple Inc. designs, manufactures, and markets smartphones...",
    "website": "https://www.apple.com",
    "sharesOutstanding": 15000000000,
    "employees": 160000,
    "quote": {
      "price": 210,
      "change": 2.5,
      "changePct": 1.2,
      "dayHigh": 211,
      "dayLow": 207,
      "previousClose": 207.5,
      "volume": 45000000,
      "marketCap": 3200000000000
    },
    "stats": {
      "peRatio": 32,
      "eps": 6.5,
      "dividendYield": 0.5,
      "beta": 1.1,
      "week52High": 212,
      "week52Low": 160,
      "priceToSales": 8.5,
      "priceToBook": 45,
      "enterpriseValue": 3250000000000,
      "evToEbitda": 24,
      "profitMargin": 25,
      "returnOnEquity": 150,
      "revenueTtm": 400000000000
    }
  }
}

GET/stocks/{symbol}/history

Daily OHLCV bars for charting, oldest first.

range 1M, 3M, 6M, 1Y (default), or 5Y (all available history).

{
  "data": [
    { "date": "2026-07-09", "open": 208, "high": 211, "low": 207, "close": 210, "volume": 45000000 }
  ],
  "meta": { "symbol": "AAPL", "range": "1Y", "count": 250 }
}

GET/stocks/{symbol}/analysts

Analyst consensus, price targets, the rating distribution, and the latest rating actions for one symbol.

{
  "data": {
    "ratings": {
      "consensus": "Buy",
      "targetConsensus": 235,
      "targetHigh": 280,
      "targetLow": 180,
      "strongBuy": 12,
      "buy": 20,
      "hold": 8,
      "sell": 2,
      "strongSell": 0,
      "nextEarnings": "2026-07-30"
    },
    "actions": [
      { "date": "2026-07-01", "firm": "Example Securities", "action": "upgrade", "fromGrade": "Hold", "toGrade": "Buy" }
    ]
  }
}

GET/stocks/{symbol}/dividends

Dividend payment history (up to the last 24 events), newest first.

{
  "data": [
    { "exDate": "2026-05-12", "paymentDate": "2026-05-22", "amount": 0.26, "frequency": "Quarterly" }
  ]
}

GET/stocks/{symbol}/peers

Same-sector competitors with price, change, and market cap.

{
  "data": [
    {
      "symbol": "MSFT",
      "name": "Microsoft Corporation",
      "industry": "Software",
      "price": 450,
      "currency": "USD",
      "priceUsd": 450,
      "changePct": 0.8,
      "marketCap": 3300000000000
    }
  ]
}

GET/stocks/{symbol}/financialsPlus

Annual financial statements for the last five fiscal years (income, balance sheet, cash flow) plus revenue segment breakdowns by product and geography. Balance and cash flow rows carry the full set of reported line items.

{
  "data": {
    "income": [
      { "year": 2025, "revenue": 400000000000, "grossProfit": 180000000000, "operatingIncome": 120000000000, "netIncome": 100000000000, "ebitda": 135000000000, "eps": 6.5 }
    ],
    "balance": [{ "year": 2025, "totalAssets": 350000000000, "totalLiabilities": 290000000000 }],
    "cashflow": [{ "year": 2025, "operatingCashFlow": 115000000000, "freeCashFlow": 105000000000 }],
    "segments": { "source": [], "geography": [] }
  }
}

GET/stocks/{symbol}/forecastPlus

Forward-looking view: analyst price targets and the multi-year revenue forecast with its low-high range.

{
  "data": {
    "targets": { "consensus": "Buy", "targetConsensus": 235, "targetHigh": 280, "targetLow": 180 },
    "revenue": [
      { "fiscalYear": 2027, "revenueAvg": 440000000000, "revenueLow": 420000000000, "revenueHigh": 460000000000 }
    ]
  }
}

GET/stocks/{symbol}/tradesPlus

Insider transactions and congressional trading activity reported for one symbol, from public filings.

{
  "data": {
    "insider": [
      { "name": "Jane Doe", "role": "Chief Financial Officer", "type": "Sale", "shares": 10000, "value": 2100000, "date": "2026-06-20" }
    ],
    "congress": [
      { "name": "Example Member", "chamber": "House", "type": "Purchase", "amount": "$15,001 - $50,000", "date": "2026-06-15" }
    ]
  }
}

Activity endpoints

Market-wide activity feeds across all symbols, newest first. Figures come from public filings and published analyst actions.

GET/analyst-actions

Latest analyst upgrades and downgrades across the whole market.

limit Max rows, 1 to 150 (default 60).

{
  "data": [
    {
      "symbol": "AAPL",
      "companyName": "Apple Inc.",
      "country": "US",
      "exchange": "NASDAQ",
      "firm": "Example Securities",
      "action": "upgrade",
      "fromGrade": "Hold",
      "toGrade": "Buy",
      "date": "2026-07-01"
    }
  ]
}

GET/congressPlus

Latest congressional trades across all symbols, as reported in public disclosures.

limit Max rows, 1 to 150 (default 60).

{
  "data": [
    {
      "symbol": "NVDA",
      "companyName": "NVIDIA Corporation",
      "country": "US",
      "exchange": "NASDAQ",
      "name": "Example Member",
      "chamber": "Senate",
      "type": "Purchase",
      "amount": "$15,001 - $50,000",
      "date": "2026-06-15",
      "disclosureDate": "2026-07-01"
    }
  ]
}

GET/insiderPlus

Latest insider transactions across all symbols, from public filings.

limit Max rows, 1 to 150 (default 60).

{
  "data": [
    {
      "symbol": "NVDA",
      "companyName": "NVIDIA Corporation",
      "country": "US",
      "exchange": "NASDAQ",
      "name": "Jane Doe",
      "role": "Chief Financial Officer",
      "type": "Sale",
      "shares": 10000,
      "value": 1500000,
      "date": "2026-06-20"
    }
  ]
}

Reference endpoints

Static reference content used by client apps.

GET/glossary

The investing glossary, grouped into sections of plain-language term definitions.

{
  "data": [
    {
      "title": "Valuation",
      "terms": [
        { "term": "Market cap", "def": "Total value of all shares: price times shares outstanding." }
      ]
    }
  ]
}

GET/meta

Client configuration: the standard disclaimer, attribution, data freshness copy, and the minimum supported client app version.

{
  "data": {
    "disclaimer": "Information is provided for general informational purposes only and is not investment advice.",
    "attribution": "Market data from licensed third-party sources.",
    "dataDelay": "Quotes refresh continuously throughout the trading day, including extended hours for US listings.",
    "minSupportedVersion": "1.0.0"
  }
}

Data use & contact

Market data from licensed third-party sources. Data returned by this API is licensed for display inside approved integrations only: it may not be stored in bulk, redistributed, resold, or used to build derivative datasets. All information is provided for general informational purposes only and is not investment advice.

Questions, partnership inquiries, or integration requests: [email protected].