News Sentiment

Overview

Financial-news headlines published in the last 30 days for any US ticker from TradingKey, MarketBeat, MarketScreener and Yahoo Finance fallback feeds, with AI sentiment (keyword fallback), source links, publishers, dates and `bullSummary`/`bearSummary` recaps. `sentimentWindow` states the exact headline count, time limit, included range and equal-weight score method behind the top-level sentiment. Older feed entries and future-dated rows are rejected before classification, so a newly generated snapshot cannot label historical news as current. Provider-controlled `sourceUrl` values are published only when they are absolute HTTP(S) URLs without embedded credentials. Before replacing last-good data, the cache verifies headline/count/sentiment agreement, exact oldest/newest dates, safe URLs, classification coverage and reconciliation between every provider status and aggregate health. An inconsistent builder result is treated as a failed refresh, never as fresh news. `quality` discloses whether classification was AI, mixed or lexicon fallback and its exact coverage. Where a model reads the text, the response states its version (`sentimentModel`), never the supplier behind it: which vendor runs the model is an implementation detail that can change without the reading changing, and it belongs in the privacy documents that have to name sub-processors. `insights` classifies the main catalysts and reports publisher/provider diversity, source concentration, bull/bear disagreement and evidence confidence. Duplicate stories keep their corroborating sources and feeds: `crossProviderCorroborationRate` measures that extra coverage and contributes to confidence, while a lack of it is disclosed rather than presented as independently confirmed news. Lexicon fallback also lowers confidence explicitly. Per-source `providerStatus` and aggregate `providerHealth` describe the returned snapshot. The server caches each ticker for 30 minutes and refreshes expired data in the background. Sequential `fresh=1` requests respect a five-minute minimum after a successful build; `cache.refreshDeferredReason`, `cache.retryAfterSeconds` and `Retry-After` disclose the deferral without repeating provider or AI work. If a refresh fails, it preserves the last good snapshot for less than 24 hours from its original `updatedAt`, with `cache.status=stale` and `freshness.stale=true`. That last good snapshot is also kept on disk, so a deploy or a process restart no longer throws it away: the first reader afterwards is served the stored answer instead of a 502 when every provider happens to be failing at that moment. Failed refreshes impose a five-minute per-ticker cooldown. Empty coverage with provider errors is a failed refresh, not fresh neutral sentiment. HTTP responses are private and no-store; this does not disable the server cache. Repeated `ticker` or `fresh` parameters return HTTP 400 rather than silently selecting one value. `dayChangePct` is the stock's price move on the day the snapshot was built, given as context for the headlines and taken from the same quote source as the rest of the site. `insights.evidence` counts the publishers and providers behind the reading (`publisherCount`, `providerCount`, `dominantPublisher` and its share, `crossProviderCorroboratedHeadlines`, `directionalHeadlineCount`, `disagreementIndex`), and `insights.confidence.factors` breaks confidence into sample depth, publisher diversity, provider availability and classification coverage. Each headline keeps the `corroboration.urls` its duplicates came from, so the corroboration can be checked rather than trusted. The whole response is declared field by field in the frozen contract at `/api/v1/schema?product=stock-news`, which the test suite validates every response against — including an outage, an empty feed and a cached fallback, the cases a healthy sample never shows. The same response is also served at `/api/stock-news` (alias of this path, byte-identical behavior).

Use it toCheck whether the news flow on a stock is positive or negative — the press angle, not social.

Coverage

Call it

Send your ra_live_… key in the x-api-key header. Pick your language:

curl "https://raspberrytrades.com/api/news?ticker=NVDA" \
  -H "x-api-key: ra_live_your_key_here"