Skip to content
oneapi.finance API Reference

Conventions

These rules apply to every endpoint. They are deliberately industry-standard where one exists, so migrating from another financial-data API should not require a wire-format adapter.

JSON shape

  • Top-level responses are objects, never bare arrays. The single exception is the time-series values array, which is a field inside the response object.
  • Property names are camelCase on the wire (e.g. previousClose, changePercent, marketCap). The Pydantic models in oneapi_core.responses use snake_case Python attribute names with alias= to bridge the two — your application code does not need to.
  • Unknown fields are rejected by the producer. If you see an extra field in a response, it has been intentionally added in a backwards-compatible way and is documented in the changelog.
  • Missing data is represented by null, not by an absent key. Numeric metrics like eps or peRatio will be null for entities that do not report them (early-stage IPOs, ETFs, indices) rather than 0.0 or omitted.

Timestamps

Every datetime value is ISO 8601 with explicit Z for UTC:

2026-05-04T20:00:00Z
2026-05-04T20:14:32.512Z

Date-only fields use YYYY-MM-DD with no time component:

2026-05-04

We never return Unix epochs in response bodies. Rate-limit headers are the only place we use epoch seconds; that follows widespread HTTP convention.

When the underlying data has a precision coarser than a second (for example, EOD bars), the timestamp normalizes to YYYY-MM-DDT00:00:00Z for that exchange day in UTC.

Symbols

  • Symbols are uppercase ASCII: AAPL, MSFT, BMW.DE. Lowercase input is accepted on requests and normalized server-side.
  • Multi-listed instruments take a Yahoo-style suffix: BMW.DE for the XETR listing, BMW.PA for the Euronext Paris listing. See exchanges for the full suffix table.
  • Forex pairs use BASE/QUOTE: USD/EUR, GBP/JPY. The slash is significant.
  • Crypto pairs use BASE-QUOTE to avoid colliding with FX: BTC-USD, ETH-EUR.

Currencies

Currency codes are ISO 4217 three-letter codes with three exchange-specific sub-unit additions:

CodeMeaningWhere used
USDUS dollarNASDAQ, NYSE, BATS
EUREuroXETR, Euronext, BME, Borsa Italiana
GBPBritish poundLSE main board (large caps)
GBXBritish pence (1/100 of GBP)LSE small/mid caps
ILSIsraeli shekelTASE main board
ILAIsraeli agorot (1/100 of ILS)TASE most listings
ZARSouth African randJSE
ZACSouth African cents (1/100 of ZAR)JSE most listings

If you are computing portfolio totals across multiple currencies, normalize sub-units to their parent before summing. The currency field tells you exactly what price is denominated in.

Numbers

  • Prices are decimal floats, not strings. We never serialize money as a string.
  • Percentages are returned as plain numbers in the human reading (e.g. 0.53 means 0.53%, not 53%). The dividendYield field on /v1/statistics is the exception: it is returned as a fractional rate (e.g. 0.0142 for 1.42%) to align with the SEC EDGAR convention.
  • Volumes and shares-outstanding are 64-bit integers.
  • Market caps and enterprise values are floats in source currency.

Booleans and enums

Booleans are JSON true / false. Enums are lowercase snake_case strings. Examples: "active", "delisted", "common_stock", "etf", "yahoo_query1", "sec_edgar".

Snake-case in error envelopes

The error envelope (code, message, status, details) uses lowercase keys with no underscores at the top level. Only details.* may contain snake_case keys, because those mirror the upstream response shape we are reporting on.

What’s next