Data behavior

Financial datasets have different clocks and completeness rules. This guide explains how to combine them without making stronger assumptions than the response supports.

Symbols and listings

The API uses provider-compatible listing symbols rather than company names. A company with multiple share classes or exchange listings can have multiple symbols. Preserve dots and hyphens when they are part of the symbol, URL-encode the path segment, and use the returned uppercase symbol as the canonical value for that request.

A profile's activelyTrading field is provider metadata. It does not confirm availability through a particular broker and does not identify an onchain token contract. Use GET /catalog to find verified Robinhood Chain stock-token addresses and logo URLs. A public-company symbol is not a contract address, and a company quote is not a tradable token quote. Check your execution venue before placing an order.

Quotes and historical prices

Quote values describe the latest observation supplied to Naven. Read asOf before comparing the quote with another source. Markets close, trading can halt, and exchanges have different sessions; the most recent quote is not necessarily from the current wall-clock minute.

Price history defaults to end-of-day rows. Set interval for intraday candles. from and to are inclusive request boundaries, but non-trading days normally have no item. Do not manufacture weekend rows or carry the last close forward unless that is an explicit choice in your application.

Intraday bars use UTC timestamps for the start of each candle. They cover regular trading sessions in America/New_York, including daylight-saving changes. Do not add a fixed UTC offset or treat intraday timestamps as daily dates. Short sessions can end with a shorter final candle. The current candle can change until it closes. Check interval and actual coverage before calculating returns; a one-minute cache lifetime is not a one-minute candle interval.

Price and percentage fields use ordinary JSON numbers. changePercent: 1.5 means 1.5%, not 0.015. Monetary fields follow the security's quote currency; use the profile's currency when displaying them.

Earnings

An earnings event may contain estimates, actuals, or both. Upcoming events commonly have null actuals. Recently reported events can be updated after the first release. Treat the event date as a calendar date, not a guaranteed announcement time.

Naven calculates surprise percentages only when an actual and a non-zero estimate are both available. Missing surprise values are returned as null.

Financial statements

Financials starts from each available income-statement period and joins a balance sheet and cash flow with the same reporting date or fiscal year and period. This prevents a newer cash flow from being attached to an older income statement. A newly filed period can therefore contain null balance sheet or cash-flow values until matching data is available.

Key details:

• period=quarter requests quarterly filings; period=annual requests annual filings.
• date is the reporting date. filingDate and acceptedDate describe filing publication.
• fiscalYear and fiscalPeriod are strings because issuer conventions differ.
• capitalExpenditure is commonly negative. Do not invert its sign without checking your calculation.
• Restatements and provider corrections can change historical values.

News

News items come from third-party publishers. Naven normalizes metadata but does not rewrite, verify, or endorse an article. Keep sourceUrl attached to any summary or claim derived from an item, and expect some optional publisher, summary, site, or image fields to be null.

Do not treat article count as sentiment or importance. Publishers can syndicate the same story, and one event may appear in multiple items.

Null and empty values

null means a specific field was not supplied or could not be normalized. It does not mean zero. An empty items array means the dataset had no rows for the requested combination of symbol and filters.

For automated workflows:

1. Check the HTTP status and code before reading data.
2. Validate the returned symbol, date range, and period.
3. Define which nullable inputs are required for your calculation.
4. Stop or degrade gracefully when required data is absent.
5. Record the source timestamp or reporting date with the derived result.

Freshness and retries

Honor the response's Cache-Control header. A 502 or 503 should not cause an agent to reuse an arbitrarily old value without labeling it. If your product maintains a longer-lived cache, store the fetch time and the dataset's own date or timestamp, and show users when fallback data is being used.

Retry 502 and 503 responses with exponential backoff and jitter. When Retry-After is present, wait at least that long. Never turn a failed provider request into an invented zero, empty financial period, or current quote.