Stocks

Endpoints for discovering, resolving, and reading stock data — identity search, price history, fundamentals links, news, and peer/competitor relationships.

Ticker format: All tickers use SYMBOL.EXCHANGE notation (e.g. NVDA.US, 7203.JP, 2330.TW, BTC-USD.CC).

---

Endpoints

Method	Path	Description
GET	/v1/stocks	Search by name/ticker, or screener mode
POST	/v1/stocks/resolve	Batch identity resolution
GET	/v1/stocks/dividends	Dividend-paying stocks ranked by yield/streak/CAGR
GET	/v1/stocks/prices	Batch EOD prices for multiple tickers
GET	/v1/stocks/:id/ohlcv	OHLCV price history for one stock
GET	/v1/stocks/:id/prices	Latest price + key stats for one stock
GET	/v1/stocks/:id/profile	Company profile (description, metadata)
GET	/v1/stocks/:id/news	News that impacts this stock
GET	/v1/stocks/:id/competitors	Direct competitors
GET	/v1/stocks/:id/peers	Theme-based peer companies

---

GET /v1/stocks

Two modes depending on which parameters are provided.

Mode A — Identity search (?q=)

Resolve a company name, partial ticker, or ISIN to a stock. Uses lexical + semantic matching.

Parameter	Type	Required	Description
q	string	✅	Name, ticker, or ISIN to look up.
country	string	—	Restrict results to an ISO-2 country (e.g. US, JP).
limit	integer	—	Max results. Default 10, max 100.

Search for Apple

GET /v1/stocks?q=Apple&country=US

Exact ticker lookup

GET /v1/stocks?q=NVDA.US

Mode B — News-driven screener

When megatrend, gics, or country is provided without ?q=, the endpoint returns a news-impact screener: stocks that appear in recent news related to the scope.

Parameter	Type	Required	Description
megatrend	integer	(one req'd)	Megatrend node id.
gics	string	(one req'd)	2/4/6/8-digit GICS code.
country	string	(one req'd)	ISO-2 country code.
exposure	string	—	core, secondary, or all (default). How central the theme is to the company.
gate	string	—	both (default) — membership + epicenter match. membership — membership only (looser).
order_by	string	—	news_count, relevance, or market_cap.
limit	integer	—	Page size. Default 20.
offset	integer	—	Pagination offset.

US stocks in EV theme with heavy news coverage

GET /v1/stocks?megatrend=10010000&country=US&order_by=news_count

---

POST /v1/stocks/resolve

Batch identity resolution — resolve many company names or tickers in a single call. Each query gets its own candidate list and a match_quality hint (strong / weak / none).

Request body

{
  "queries": ["Apple", "TSMC", "Volkswagen", "NVDA.US"],
  "limit": 3,
  "country": "US"
}

Field	Type	Required	Description
queries	string[]	✅	List of names/tickers to resolve. Max 25 entries, each max 200 chars.
limit	integer	—	Candidates per query. Default 5, max 25.
country	string	—	Bias results toward a country (ISO-2).

Response shape

{
  "count": 4,
  "results": [
    {
      "query": "Apple",
      "match_quality": "strong",
      "matches": [
        { "ticker": "AAPL.US", "name": "Apple Inc.", "exchange": "US", ... }
      ]
    }
  ]
}

match_quality values:

• strong — single match, or the top match is clearly ahead of the runner-up
• weak — multiple similar candidates; human disambiguation recommended
• none — no match found

---

GET /v1/stocks/dividends

Dividend-paying stocks ranked by yield, streak, or CAGR. Useful for pure dividend screens — for combining with TA or fundamental conditions, use POST /v1/screen with the dividend leg instead.

Parameter	Type	Required	Description
order_by	string	—	yield (default), streak, or cagr.
country	string	—	Filter by ISO-2 country.
gics	string	—	Filter by 2/4/6/8-digit GICS code.
limit	integer	—	Page size. Default 20.
offset	integer	—	Pagination offset.

Top dividend yielders in Japan

GET /v1/stocks/dividends?country=JP&order_by=yield&limit=20

---

GET /v1/stocks/prices

Batch EOD prices for up to 20 tickers at once.

Parameter	Type	Required	Description
tickers	string	✅	Comma-separated tickers in SYMBOL.EXCHANGE format.

GET /v1/stocks/prices?tickers=NVDA.US,TSLA.US,AAPL.US

---

GET /v1/stocks/:id/ohlcv

Full OHLCV (open/high/low/close/volume) history for a single stock. :id accepts either a SYMBOL.EXCHANGE ticker or an integer listing id.

Parameter	Type	Required	Description
tf	string	—	day (default), week, or month.
adjust	string	—	split (default) — split-adjusted. raw — unadjusted. splitdiv — split + dividend adjusted.
limit	integer	—	Number of bars. Default 300.
from	string	—	Start date YYYY-MM-DD.
to	string	—	End date YYYY-MM-DD.

2 years of weekly bars for AAPL

GET /v1/stocks/AAPL.US/ohlcv?tf=week&limit=104

Daily bars from a specific date

GET /v1/stocks/TSLA.US/ohlcv?tf=day&from=2025-01-01&to=2025-12-31

---

GET /v1/stocks/:id/prices

Current price and key daily stats (open, high, low, close, volume, change %). No parameters beyond the path :id.

GET /v1/stocks/NVDA.US/prices

---

GET /v1/stocks/:id/profile

Company profile: description, sector/industry, website, employee count, market cap, and listing metadata. No additional parameters.

GET /v1/stocks/TSMC.TW/profile

:::info Ticker format for :id All :id path parameters accept either a SYMBOL.EXCHANGE ticker (e.g. NVDA.US) or an integer listing id. Tickers are resolved to the canonical listing. :::

---

GET /v1/stocks/:id/news

News that impacts this stock — combines direct mentions and impact-mapped articles. Equivalent to /v1/news/by-tickers?ticker=<id> scoped to one stock.

Parameter	Type	Required	Description
order_by	string	—	recency (default), impact, or relevance.
news_type	string	—	Comma-separated news type filter.
limit	integer	—	Page size. Default 20.
offset	integer	—	Pagination offset.

GET /v1/stocks/AAPL.US/news?order_by=impact&limit=10

---

GET /v1/stocks/:id/competitors

Direct product/market competitors of the stock, ranked by competitive closeness. No additional parameters.

GET /v1/stocks/NVDA.US/competitors

---

GET /v1/stocks/:id/peers

Theme-based peer companies — other companies sharing the same megatrend exposures.

Parameter	Type	Required	Description
exposure	string	—	core (default) — only core-exposure peers. all — include secondary exposures.
grouped	integer	—	1 — return peers grouped by theme axis. 0 (default) — flat list.

Grouped peers by theme

GET /v1/stocks/TSLA.US/peers?grouped=1