aljaz/tiingo-python
1
1
Fork 0
mirror of https://github.com/hydrosquall/tiingo-python.git synced 2026-01-09 22:34:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add OpenAPI specifications for Tiingo API

Browse Source 
Add OpenAPI 3.0.0 specifications covering Tiingo API endpoints:
- End-of-day prices
- IEX real-time data
- Crypto prices and metadata
- Forex rates
- News articles
- Fundamentals
- Mutual funds/ETFs
- Corporate actions (dividends, splits)

Specifications are modular with:
- Shared components (schemas, parameters, responses)
- Separate path files per endpoint category
- Common authentication and error handling
- Detailed request/response schemas

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cameron Yick
2025-12-13 22:43:05 -05:00
parent 4d9a9776a8
commit 267f6aca2e
24 changed files with 3997 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

271
openapi/paths/crypto.yaml Normal file
View File

@@ -0,0 +1,271 @@
# Crypto API Endpoints for Tiingo API
# Reference: https://www.tiingo.com/documentation/crypto
crypto-prices: &crypto-prices
get:
summary: Get cryptocurrency prices
description: |
Get real-time and historical cryptocurrency prices. Returns meta information about the crypto pair
along with OHLCV price data. Without startDate, returns latest data for the current or last business day.
With startDate, returns historical intraday data.
The response includes consolidated data from multiple exchanges, with optional raw exchange-level data
when includeRawExchangeData is enabled.
operationId: getCryptoPrices
tags:
- Crypto
parameters:
- name: tickers
in: query
required: true
schema:
type: string
pattern: '^[a-z0-9]+(,[a-z0-9]+)*$'
description: Comma-separated list of crypto tickers
example: 'btcusd,fldcbtc'
- name: startDate
in: query
required: false
schema:
type: string
format: date
pattern: '^\d{4}-\d{2}-\d{2}$'
description: Start date for historical data in YYYY-MM-DD format
example: '2019-01-02'
- name: endDate
in: query
required: false
schema:
type: string
format: date
pattern: '^\d{4}-\d{2}-\d{2}$'
description: End date for historical data in YYYY-MM-DD format
example: '2019-12-31'
- name: resampleFreq
in: query
required: false
schema:
type: string
pattern: '^[0-9]+(min|hour|day)$'
enum:
- '1min'
- '5min'
- '15min'
- '30min'
- '1hour'
- '2hour'
- '4hour'
- '1day'
description: Resampling frequency for historical data (e.g., 5min, 1hour, 1day)
example: '5min'
- name: includeRawExchangeData
in: query
required: false
schema:
type: boolean
default: false
description: Include raw exchange-level data in the response
example: true
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with cryptocurrency price data
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/crypto-schemas.yaml#/CryptoPrice'
examples:
latest-price:
summary: Latest price data
description: Get current/latest price for Bitcoin
value:
- ticker: 'btcusd'
baseCurrency: 'btc'
quoteCurrency: 'usd'
priceData:
- date: '2019-01-02T00:00:00.000Z'
close: 3610.32
high: 3701.0
low: 3600.65
open: 3690.01
volume: 1234.56
volumeNotional: 4456789.12
tradesDone: 5000
historical-prices:
summary: Historical price data with 5-minute resampling
description: Get historical intraday data for Bitcoin with 5-minute intervals
value:
- ticker: 'btcusd'
baseCurrency: 'btc'
quoteCurrency: 'usd'
priceData:
- date: '2019-01-02T00:00:00.000Z'
close: 3610.32
high: 3701.0
low: 3600.65
open: 3690.01
volume: 1234.56
volumeNotional: 4456789.12
tradesDone: 5000
- date: '2019-01-02T00:05:00.000Z'
close: 3615.50
high: 3620.0
low: 3610.0
open: 3610.32
volume: 567.89
volumeNotional: 2052345.67
tradesDone: 2345
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
crypto-meta: &crypto-meta
get:
summary: Get cryptocurrency metadata
description: |
Get metadata information for cryptocurrencies including ticker, base/quote currencies, name, and description.
Without the tickers parameter, returns metadata for all available cryptocurrencies.
With the tickers parameter, returns metadata only for the specified tickers.
operationId: getCryptoMetadata
tags:
- Crypto
parameters:
- name: tickers
in: query
required: false
schema:
type: string
pattern: '^[a-z0-9]+(,[a-z0-9]+)*$'
description: Comma-separated list of crypto tickers to filter by. If omitted, returns all tickers.
example: 'btcusd,ethusd'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with cryptocurrency metadata
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/crypto-schemas.yaml#/CryptoMetadata'
examples:
bitcoin-metadata:
summary: Bitcoin metadata
description: Get metadata for Bitcoin
value:
- ticker: 'btcusd'
baseCurrency: 'btc'
quoteCurrency: 'usd'
name: 'Bitcoin'
description: 'Bitcoin is a cryptocurrency and worldwide payment system.'
multiple-metadata:
summary: Multiple cryptocurrency metadata
description: Get metadata for Bitcoin and Ethereum
value:
- ticker: 'btcusd'
baseCurrency: 'btc'
quoteCurrency: 'usd'
name: 'Bitcoin'
description: 'Bitcoin is a cryptocurrency and worldwide payment system.'
- ticker: 'ethusd'
baseCurrency: 'eth'
quoteCurrency: 'usd'
name: 'Ethereum'
description: 'Ethereum is a decentralized platform for smart contracts.'
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
crypto-top: &crypto-top
get:
summary: Get cryptocurrency top-of-book data (DEPRECATED)
description: |
**DEPRECATED**: This endpoint has been deprecated and may be removed in a future version.
Tiingo has deprecated the top-of-book endpoint due to reliability issues with cryptocurrency exchange feeds.
The feeds have been found unreliable for constructing consistent best bid/ask data across 60+ exchanges.
Issues include inconsistent timestamps, improperly ordered messages, and varying exchange-specific quirks.
For last price information, use the `/tiingo/crypto/prices` endpoint instead.
This endpoint returns top-of-book data including bid/ask prices, last trade information, and optional
raw exchange-level data. While the endpoint remains available, it should not be used for production systems.
operationId: getCryptoTopOfBook
deprecated: true
tags:
- Crypto
parameters:
- name: tickers
in: query
required: true
schema:
type: string
pattern: '^[a-z0-9]+(,[a-z0-9]+)*$'
description: Comma-separated list of crypto tickers
example: 'btcusd,ethusd'
- name: includeRawExchangeData
in: query
required: false
schema:
type: boolean
default: false
description: Include raw exchange-level top-of-book data in the response
example: true
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with top-of-book data (DEPRECATED)
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/crypto-schemas.yaml#/CryptoTopOfBook'
examples:
bitcoin-top-of-book:
summary: Bitcoin top-of-book data
description: Get top-of-book data for Bitcoin
value:
- ticker: 'btcusd'
baseCurrency: 'btc'
quoteCurrency: 'usd'
topOfBookData:
quoteTimestamp: '2019-01-02T12:34:56.789Z'
lastSaleTimestamp: '2019-01-02T12:34:56.789Z'
lastPrice: 3610.32
lastSize: 0.5
lastSizeNotional: 1805.16
lastExchange: 'Coinbase'
bidSize: 1.2
bidPrice: 3609.50
bidExchange: 'Binance'
askSize: 0.8
askPrice: 3611.00
askExchange: 'Kraken'
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

214
openapi/paths/dividends.yaml Normal file
View File

@@ -0,0 +1,214 @@
# Tiingo Dividends API Endpoints
# Corporate Actions - Distribution and Yield Endpoints
distributions-batch: &distributions-batch
get:
summary: Get batch distribution data
description: |
Retrieve past, present, and future dividends and distributions for multiple tickers.
Returns detailed dividend and distribution data for stocks, ETFs, or mutual funds.
The response includes distribution frequency, which is the declared frequency of the
distribution that you can use to customize your calculations to determine yield.
Available for current and future dates. Requires End-of-Day endpoint entitlement.
operationId: getBatchDistributions
tags:
- Corporate Actions
parameters:
- name: exDate
in: query
required: false
schema:
type: string
format: date
description: |
Filter distributions by ex-date. Can be a future date or historical date.
If not specified, returns distributions with an ex-date of the current day.
Format: YYYY-MM-DD
example: '2023-08-25'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with array of distribution objects
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/dividends-schemas.yaml#/Distribution'
examples:
multipleDistributions:
summary: Multiple distributions for a specific ex-date
value:
- permaTicker: AAPL
ticker: AAPL
exDate: '2023-08-25T00:00:00.000Z'
paymentDate: '2023-09-07T00:00:00.000Z'
recordDate: '2023-08-28T00:00:00.000Z'
declarationDate: '2023-07-27T00:00:00.000Z'
distribution: 0.24
distributionFreqency: q
- permaTicker: MSFT
ticker: MSFT
exDate: '2023-08-25T00:00:00.000Z'
paymentDate: '2023-09-21T00:00:00.000Z'
recordDate: '2023-08-31T00:00:00.000Z'
declarationDate: '2023-07-25T00:00:00.000Z'
distribution: 0.68
distributionFreqency: q
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
distributions-ticker: &distributions-ticker
get:
summary: Get distribution data for a specific ticker
description: |
Retrieve historical distribution timeseries data for a specific ticker.
Similar to the batch endpoint, but allows you to specify a ticker to limit the query.
Supports stocks, ETFs, and mutual funds.
Returns full history by default, or can be limited to a date range using
startExDate and endExDate parameters.
operationId: getTickerDistributions
tags:
- Corporate Actions
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- name: startExDate
in: query
required: false
description: |
Start of the ex-date range to query. Format: YYYY-MM-DD
schema:
type: string
format: date
example: '2023-01-01'
- name: endExDate
in: query
required: false
description: |
End of the ex-date range to query. Format: YYYY-MM-DD
schema:
type: string
format: date
example: '2024-01-01'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with array of distribution objects for the specified ticker
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/dividends-schemas.yaml#/Distribution'
examples:
yearlyDistributions:
summary: AAPL quarterly distributions for 2023
value:
- permaTicker: AAPL
ticker: AAPL
exDate: '2023-02-10T00:00:00.000Z'
paymentDate: '2023-02-23T00:00:00.000Z'
recordDate: '2023-02-13T00:00:00.000Z'
declarationDate: '2023-01-26T00:00:00.000Z'
distribution: 0.22
distributionFreqency: q
- permaTicker: AAPL
ticker: AAPL
exDate: '2023-05-12T00:00:00.000Z'
paymentDate: '2023-05-25T00:00:00.000Z'
recordDate: '2023-05-15T00:00:00.000Z'
declarationDate: '2023-04-27T00:00:00.000Z'
distribution: 0.22
distributionFreqency: q
- permaTicker: AAPL
ticker: AAPL
exDate: '2023-08-11T00:00:00.000Z'
paymentDate: '2023-08-24T00:00:00.000Z'
recordDate: '2023-08-14T00:00:00.000Z'
declarationDate: '2023-07-27T00:00:00.000Z'
distribution: 0.24
distributionFreqency: q
- permaTicker: AAPL
ticker: AAPL
exDate: '2023-11-10T00:00:00.000Z'
paymentDate: '2023-11-23T00:00:00.000Z'
recordDate: '2023-11-13T00:00:00.000Z'
declarationDate: '2023-10-26T00:00:00.000Z'
distribution: 0.24
distributionFreqency: q
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
distribution-yield: &distribution-yield
get:
summary: Get historical yield data for a ticker
description: |
Retrieve current and historical information about yield data for stocks, ETFs,
or mutual funds. Yield data is available for tickers after their End-of-Day
price data has been processed.
Note: Tiingo will continue to add new daily metrics over time. Use the 'columns'
parameter to ensure constant output format, even if additional columns are added.
operationId: getDistributionYield
tags:
- Corporate Actions
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- name: columns
in: query
required: false
schema:
type: string
description: |
Comma-separated list of column names to return. This ensures only specified
fields are returned in exact order, providing consistent output format across
API updates. Example: 'trailingDiv1Y' will always return only that field.
example: trailingDiv1Y
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with array of yield objects
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/dividends-schemas.yaml#/DistributionYield'
examples:
historicalYield:
summary: Historical trailing 1-year dividend yield for AAPL
value:
- date: '2024-01-01T00:00:00.000Z'
trailingDiv1Y: '0.92'
- date: '2024-01-02T00:00:00.000Z'
trailingDiv1Y: '0.92'
- date: '2024-01-03T00:00:00.000Z'
trailingDiv1Y: '0.92'
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

191
openapi/paths/end-of-day.yaml Normal file
View File

@@ -0,0 +1,191 @@
# End-of-Day Stock Price API Paths
# Reference: https://www.tiingo.com/documentation/end-of-day
daily-prices: &daily-prices
get:
summary: Get End-of-Day Stock Prices
description: |
Returns End-of-Day price data for a given stock ticker.
Tiingo's End-of-Day prices use a proprietary error checking framework to help clean data feeds
and catch missing corporate actions (splits, dividends, and exchange listing changes).
**Pricing Availability:**
- Most US Equity prices are available at 5:30 PM EST
- Exchanges may send corrections until 8 PM EST
- Mutual Fund NAVs available after 12 AM EST
**Price Adjustments:**
- Both raw and adjusted prices are available
- Adjustment methodology follows CRSP (Center for Research in Security Prices) standard
- Incorporates both split and dividend adjustments
operationId: getEndOfDayPrices
tags:
- End-of-Day
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
- $ref: '../parameters/_index.yaml#/StartDateParam'
- $ref: '../parameters/_index.yaml#/EndDateParam'
- $ref: '../parameters/_index.yaml#/FormatParam'
- name: resampleFreq
in: query
required: false
schema:
type: string
enum:
- daily
- weekly
- monthly
- annually
- 1min
- 5min
- 15min
- 30min
- 1hour
- 4hour
description: Resample frequency for OHLC bars (e.g., daily, monthly, weekly, 5min, 1hour)
- name: sort
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: Sort order for results (ascending or descending by date)
- name: columns
in: query
required: false
schema:
type: string
description: Comma-separated list of specific columns to return (e.g., "date,close,volume")
example: "date,close,volume"
responses:
'200':
description: Successful response with price data
content:
application/json:
schema:
$ref: '../schemas/eod-schemas.yaml#/PriceData'
examples:
singleDay:
summary: Single day price data
value:
- date: "2024-01-01"
open: 150.25
high: 152.50
low: 149.75
close: 151.80
volume: 50000000
adjOpen: 150.25
adjHigh: 152.50
adjLow: 149.75
adjClose: 151.80
adjVolume: 50000000
divCash: 0.0
splitFactor: 1.0
historicalData:
summary: Multiple days historical data
value:
- date: "2024-01-01"
open: 150.25
high: 152.50
low: 149.75
close: 151.80
volume: 50000000
adjOpen: 150.25
adjHigh: 152.50
adjLow: 149.75
adjClose: 151.80
adjVolume: 50000000
divCash: 0.0
splitFactor: 1.0
- date: "2024-01-02"
open: 151.90
high: 153.20
low: 151.50
close: 152.40
volume: 48000000
adjOpen: 151.90
adjHigh: 153.20
adjLow: 151.50
adjClose: 152.40
adjVolume: 48000000
divCash: 0.0
splitFactor: 1.0
text/csv:
schema:
type: string
format: binary
example: |
date,open,high,low,close,volume,adjOpen,adjHigh,adjLow,adjClose,adjVolume,divCash,splitFactor
2024-01-01,150.25,152.50,149.75,151.80,50000000,150.25,152.50,149.75,151.80,50000000,0.0,1.0
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
daily-meta: &daily-meta
get:
summary: Get Stock Ticker Metadata
description: |
Returns metadata information about a specific stock ticker.
Meta information comes from a variety of sources and is used to help communicate
details about an asset in the Tiingo database to users.
**Response Fields:**
- Ticker symbol and full name
- Exchange where the asset is listed
- Description of the company/asset
- Date range for available price data
operationId: getTickerMetadata
tags:
- End-of-Day
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with ticker metadata
content:
application/json:
schema:
$ref: '../schemas/eod-schemas.yaml#/TickerMetadata'
examples:
appleMetadata:
summary: Apple Inc metadata
value:
ticker: "AAPL"
name: "Apple Inc"
exchangeCode: "NASDAQ"
description: "Apple Inc is an American multinational technology company that specializes in consumer electronics, software and online services."
startDate: "1990-01-01"
endDate: "2024-01-01"
noDataTicker:
summary: Ticker with no price data
value:
ticker: "NEWCO"
name: "New Company Inc"
exchangeCode: "NYSE"
description: "A newly listed company"
startDate: null
endDate: null
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

200
openapi/paths/forex.yaml Normal file
View File

@@ -0,0 +1,200 @@
# Tiingo Forex API Paths
# Reference these using: $ref: './forex.yaml#/forex-single'
forex-single: &forex-single
get:
tags:
- Forex
summary: Get top-of-book data for a specific forex pair
description: |
Returns real-time top-of-book data including bid/ask prices and sizes for a specific forex pair.
This endpoint provides institutional-grade quality forex quotes from tier-1 banks and FX dark pools.
Market hours are Sunday 8pm EST through Friday 5pm EST.
operationId: getForexTopOfBook
parameters:
- name: ticker
in: path
required: true
schema:
type: string
pattern: '^[a-z]{6}$'
description: Forex ticker pair (e.g., eurusd, gbpusd, audusd)
example: eurusd
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with forex top-of-book data
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/forex-schemas.yaml#/ForexTopOfBook'
example:
- ticker: eurusd
quoteTimestamp: '2019-07-01T21:00:01.289000+00:00'
bidPrice: 1.1186
bidSize: 1000000.0
askPrice: 1.1187
askSize: 1000000.0
midPrice: 1.11865
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
forex-top: &forex-top
get:
tags:
- Forex
summary: Get top-of-book data for multiple forex pairs
description: |
Returns real-time top-of-book data including bid/ask prices and sizes for multiple forex pairs.
This endpoint allows you to query multiple forex tickers in a single request.
Supports 140+ forex ticker pairs with quotes updated to the latest microsecond during market hours.
operationId: getForexTopOfBookMultiple
parameters:
- name: tickers
in: query
required: true
schema:
type: string
description: Comma-separated list of forex ticker pairs (e.g., eurusd,gbpusd,audusd)
example: eurusd,gbpusd
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with forex top-of-book data for multiple tickers
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/forex-schemas.yaml#/ForexTopOfBook'
example:
- ticker: audusd
quoteTimestamp: '2019-07-01T21:00:01.289000+00:00'
bidPrice: 0.6963
bidSize: 100000.0
askPrice: 0.6965
askSize: 100000.0
midPrice: 0.6964
- ticker: eurusd
quoteTimestamp: '2019-07-01T21:00:01.289000+00:00'
bidPrice: 1.1186
bidSize: 1000000.0
askPrice: 1.1187
askSize: 1000000.0
midPrice: 1.11865
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
forex-prices: &forex-prices
get:
tags:
- Forex
summary: Get historical intraday OHLC prices for a forex pair
description: |
Returns historical intraday OHLC (Open, High, Low, Close) prices for a forex pair.
Supports multiple resample frequencies from 1-minute to daily bars.
Default date range is current date minus 1 year to current date.
operationId: getForexPrices
parameters:
- name: ticker
in: path
required: true
schema:
type: string
pattern: '^[a-z]{6}$'
description: Forex ticker pair (e.g., eurusd, gbpusd, audusd)
example: eurusd
- name: startDate
in: query
required: false
schema:
type: string
format: date
description: Start date for historical data in YYYY-MM-DD format (default is current date minus 1 year)
example: '2019-06-30'
- name: endDate
in: query
required: false
schema:
type: string
format: date
description: End date for historical data in YYYY-MM-DD format (default is current date)
example: '2019-07-01'
- name: resampleFreq
in: query
required: false
schema:
type: string
enum:
- 1min
- 5min
- 15min
- 30min
- 1hour
- 1day
default: 1day
description: Frequency to resample data to
example: 5min
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with historical forex price data
content:
application/json:
schema:
type: object
properties:
ticker:
type: string
description: Forex ticker pair
example: eurusd
priceData:
type: array
items:
$ref: '../schemas/forex-schemas.yaml#/ForexPrice'
example:
ticker: eurusd
priceData:
- date: '2019-06-28T20:00:00.000Z'
open: 1.1232
high: 1.1254
low: 1.1220
close: 1.1245
- date: '2019-06-28T20:05:00.000Z'
open: 1.1245
high: 1.1268
low: 1.1242
close: 1.1260
- date: '2019-06-28T20:10:00.000Z'
open: 1.1260
high: 1.1275
low: 1.1258
close: 1.1268
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

360
openapi/paths/fundamentals.yaml Normal file
View File

@@ -0,0 +1,360 @@
# Tiingo Fundamentals API Endpoints
# Reference these using: $ref: './fundamentals.yaml#/definitions'
definitions: &definitions
get:
summary: Get Fundamental Definitions
description: |
Returns available fundamental metrics and their metadata. Use this endpoint to discover
which fields are available and what they represent.
operationId: getFundamentalDefinitions
tags:
- Fundamentals
parameters:
- $ref: '../parameters/_index.yaml#/TokenParam'
- name: tickers
in: query
required: false
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: |
Specific tickers to return meta data for. If no string passed, will return meta data
for all available tickers. Can either be a single ticker, a comma-separated list of tickers,
or an array of strings (string[]).
examples:
single:
value: "AAPL"
summary: Single ticker
multiple:
value: "AAPL,GOOGL,MSFT"
summary: Multiple tickers (comma-separated)
array:
value: ["AAPL", "GOOGL", "MSFT"]
summary: Array of tickers
- $ref: '../parameters/_index.yaml#/FormatParam'
responses:
'200':
description: Successful response with fundamental definitions
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/fundamentals-schemas.yaml#/FundamentalDefinition'
examples:
definitions:
summary: Example fundamental definitions
value:
- dataCode: "peRatio"
name: "Price/Earnings Ratio"
description: "The price to earnings ratio of the company"
statementType: "overview"
units: ""
- dataCode: "netIncome"
name: "Net Income"
description: "The net income of the company"
statementType: "incomeStatement"
units: "$"
text/csv:
schema:
type: string
description: CSV formatted data
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
statements: &statements
get:
summary: Get Financial Statements
description: |
Returns historical statement data extracted from quarterly and annual statements
(Balance Sheet, Income Statement, Cash Flow, and Overview metrics). Data is updated
usually within 12-24 hours of being made available by the SEC.
The `asReported` parameter controls whether you get the most recent revised data
(false, default) or the data as it was originally reported (true).
operationId: getFinancialStatements
tags:
- Fundamentals
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
- name: asReported
in: query
required: false
schema:
type: boolean
default: false
description: |
When false (default), returns the most recent data including any revisions for the reporting period.
The dates will correspond to the fiscal end of the quarter or year.
When true, returns the data as it was reported on the release date.
The date will correspond to the date the filings were posted on the SEC.
- $ref: '../parameters/_index.yaml#/StartDateParam'
- $ref: '../parameters/_index.yaml#/EndDateParam'
- name: sort
in: query
required: false
schema:
type: string
enum:
- date
- -date
default: date
description: |
Sort direction and column to sort by. Prepend "-" for descending order,
otherwise ascending. For Fundamentals statements, only the "date" field may be sorted upon.
examples:
ascending:
value: "date"
summary: Sort by date ascending
descending:
value: "-date"
summary: Sort by date descending
- $ref: '../parameters/_index.yaml#/FormatParam'
responses:
'200':
description: Successful response with financial statements
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/fundamentals-schemas.yaml#/FinancialStatement'
examples:
statements:
summary: Example financial statement
value:
- date: "2023-12-29T00:00:00.000Z"
quarter: 1
year: 2024
statementData:
balanceSheet:
- dataCode: "totalAssets"
value: 352755000000
incomeStatement:
- dataCode: "revenue"
value: 383285000000
- dataCode: "netIncome"
value: 96995000000
cashFlow:
- dataCode: "operatingCashFlow"
value: 110543000000
overview:
- dataCode: "peRatio"
value: 29.45
text/csv:
schema:
type: string
description: CSV formatted data (flat/2-D structure for spreadsheet compatibility)
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
daily: &daily
get:
summary: Get Daily Fundamentals
description: |
Returns daily fundamental metrics that rely on price data and update daily
(Market Capitalization, P/E Ratios, P/B Ratios, etc.).
IMPORTANT: New daily metrics are continuously added, so fields will change over time.
Use the `columns` parameter if you require specific columns in a particular order.
operationId: getDailyFundamentals
tags:
- Fundamentals
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
- $ref: '../parameters/_index.yaml#/StartDateParam'
- $ref: '../parameters/_index.yaml#/EndDateParam'
- name: sort
in: query
required: false
schema:
type: string
pattern: '^-?[a-zA-Z]+$'
description: |
Sort direction and column to sort by. Prepend "-" for descending order,
otherwise ascending. E.g. sort=date (ascending) or sort=-date (descending).
examples:
ascending:
value: "date"
summary: Sort by date ascending
descending:
value: "-date"
summary: Sort by date descending
- name: columns
in: query
required: false
schema:
type: string
pattern: '^[a-zA-Z]+(,[a-zA-Z]+)*$'
description: |
Comma-separated list of columns to return. Ensures consistent output even as
new metrics are added. E.g. columns=date,marketCap,peRatio will always return
only those columns in that exact order.
examples:
basic:
value: "date,marketCap,peRatio"
summary: Basic metrics
extended:
value: "date,marketCap,enterpriseVal,peRatio,pbRatio,trailingPEG1Y"
summary: Extended metrics
- $ref: '../parameters/_index.yaml#/FormatParam'
responses:
'200':
description: Successful response with daily fundamental metrics
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/fundamentals-schemas.yaml#/DailyMetric'
examples:
daily:
summary: Example daily fundamentals
value:
- date: "2023-12-29T00:00:00.000Z"
marketCap: 3050000000000
enterpriseVal: 2950000000000
peRatio: 29.45
pbRatio: 48.32
trailingPEG1Y: 2.15
- date: "2023-12-28T00:00:00.000Z"
marketCap: 3040000000000
enterpriseVal: 2940000000000
peRatio: 29.38
pbRatio: 48.20
trailingPEG1Y: 2.14
text/csv:
schema:
type: string
description: CSV formatted data
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
meta: &meta
get:
summary: Get Fundamentals Metadata
description: |
Returns company metadata and information about when data was last updated.
IMPORTANT: As new meta data about companies and their fundamentals is added,
the endpoint output will change. Use the `columns` parameter if you require
specific columns in a particular order.
operationId: getFundamentalsMeta
tags:
- Fundamentals
parameters:
- $ref: '../parameters/_index.yaml#/TokenParam'
- name: tickers
in: query
required: false
schema:
oneOf:
- type: string
- type: array
items:
type: string
description: |
Specific tickers to return meta data for. If no string passed, will return meta data
for all available tickers. Can either be a single ticker, a comma-separated list of tickers,
or an array of strings (string[]).
examples:
single:
value: "AAPL"
summary: Single ticker
multiple:
value: "AAPL,GOOGL"
summary: Multiple tickers (comma-separated)
array:
value: ["AAPL", "GOOGL"]
summary: Array of tickers
- name: columns
in: query
required: false
schema:
type: string
pattern: '^[a-zA-Z]+(,[a-zA-Z]+)*$'
description: |
Comma-separated list of columns to return. Ensures consistent output even as
new metadata is added. E.g. columns=ticker,name will always return only those
columns in that exact order.
examples:
basic:
value: "ticker,name"
summary: Basic info
extended:
value: "ticker,name,sector,industry,isActive"
summary: Extended info
- $ref: '../parameters/_index.yaml#/FormatParam'
responses:
'200':
description: Successful response with company metadata
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/fundamentals-schemas.yaml#/FundamentalMeta'
examples:
meta:
summary: Example company metadata
value:
- permaTicker: "AAPL"
ticker: "AAPL"
name: "Apple Inc."
isActive: true
isADR: false
sector: "Technology"
industry: "Consumer Electronics"
sicCode: 3571
sicSector: "Industrial and Commercial Machinery and Computer Equipment"
sicIndustry: "Electronic Computers"
reportingCurrency: "USD"
location: "California"
companyWebsite: "https://www.apple.com"
secFilingWebsite: "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=&dateb=&owner=exclude&count=100"
statementLastUpdated: "2024-01-15T10:30:00.000Z"
dailyLastUpdated: "2024-01-15T08:00:00.000Z"
text/csv:
schema:
type: string
description: CSV formatted data
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

132
openapi/paths/funds.yaml Normal file
View File

@@ -0,0 +1,132 @@
# Tiingo Mutual Fund and ETF Fees API Endpoints
# Reference: /docs/api_extracted/mutual-fund-etf-fees.md
fund-overview: &fund-overview
get:
summary: Get Fund Overview
description: |
Obtain top-level fund data, including description and share classes.
This endpoint provides comprehensive information about a mutual fund or ETF,
including its full name, description, share class, net expense ratio, and
related share classes with their respective expense ratios.
**Note:** This endpoint is available for enterprise and institutional clients only.
Contact Sales@tiingo.com for licensing and pricing.
operationId: getFundOverview
tags:
- Funds
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with fund overview data
content:
application/json:
schema:
$ref: '../schemas/funds-schemas.yaml#/FundOverview'
examples:
vtsax:
summary: Vanguard Total Stock Market Index Fund
value:
ticker: "VTSAX"
name: "Vanguard Total Stock Market Index Fund"
description: "Long description of the fund..."
shareClass: "Admiral Shares"
netExpense: 0.0035
otherShareClasses:
- ticker: "VTSMX"
name: "Vanguard Total Stock Market Index Fund"
shareClass: "Investor Shares"
netExpense: 0.0055
- ticker: "VTSIX"
name: "Vanguard Total Stock Market Index Fund"
shareClass: "Institutional Shares"
netExpense: 0.0020
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
fund-metrics: &fund-metrics
get:
summary: Get Fund Fee Metrics
description: |
Obtain detailed current and historical fee data for a mutual fund or ETF.
This endpoint provides comprehensive fee information including net and gross expense ratios,
management fees, 12b-1 fees, load fees, redemption fees, and custom fees. The data includes
both current and historical fee information with prospectus dates.
Fee data covers:
- Expense ratios (net/gross)
- Management and distribution fees
- Load fees (front/back/dividend)
- Shareholder and account fees
- Redemption and exchange fees
- Custom fees (e.g., check processing fees)
All fee values are expressed as decimals (e.g., 0.0035 = 0.35%).
**Note:** This endpoint is available for enterprise and institutional clients only.
Contact Sales@tiingo.com for licensing and pricing.
operationId: getFundMetrics
tags:
- Funds
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with detailed fund fee metrics
content:
application/json:
schema:
$ref: '../schemas/funds-schemas.yaml#/FundMetrics'
examples:
vtsax:
summary: Vanguard Total Stock Market Index Fund Fees
value:
prospectusDate: "2024-01-15"
netExpense: 0.0035
grossExpense: 0.0040
managementFee: 0.0025
12b1: 0.0000
non12b1: 0.0000
otherExpenses: 0.0015
acquiredFundFees: 0.0000
feeWaiver: 0.0005
exchangeFeeUSD: 0.0000
exchangeFeePercent: 0.0000
frontLoad: 0.0000
backLoad: 0.0000
dividendLoad: 0.0000
shareholderFee: 0.0000
accountFeeUSD: 0.0000
accountFeePercent: 0.0000
redemptionFeeUSD: 0.0000
redemptionFeePercent: 0.0000
portfolioTurnover: 0.05
miscFees: 0.0000
customFees:
- label: "Check Processing Fee"
value: 0.0000
units: "$"
parentFee: "shareholderFee"
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

269
openapi/paths/iex.yaml Normal file
View File

@@ -0,0 +1,269 @@
# IEX Exchange API Endpoints
# Reference: https://api.tiingo.com/documentation/iex
iex-all: &iex-all
get:
summary: Get current top-of-book and last price for all or multiple tickers
description: |
Retrieve current top-of-book (bid/ask) and last price data for all available tickers or a specified list of tickers.
Returns real-time reference prices or full TOPS feed data (requires IEX Exchange registration).
This endpoint provides:
- Top-of-Book (Bid/Ask) data
- Last Sale (trade) data
- Tiingo-enriched convenience fields (tngoLast, mid, open, high, low)
- Volume data (IEX only during trading, all exchanges after close)
operationId: getAllIEXQuotes
tags:
- IEX
parameters:
- name: tickers
in: query
required: false
schema:
type: string
pattern: '^[A-Z0-9]+(,[A-Z0-9]+)*$'
description: |
Comma-separated list of ticker symbols. If omitted, returns data for all available tickers.
example: 'AAPL,SPY,QQQ'
- $ref: '../parameters/_index.yaml#/FormatParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with top-of-book and last price data
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/iex-schemas.yaml#/IEXTopOfBook'
examples:
multiple-tickers:
summary: Multiple tickers response
value:
- ticker: 'AAPL'
timestamp: '2019-01-30T10:33:38.186520297-05:00'
quoteTimestamp: '2019-01-30T10:33:38.186520297-05:00'
lastSaleTimeStamp: '2019-01-30T10:33:34.176037579-05:00'
last: 162.37
lastSize: 100
tngoLast: 162.33
prevClose: 154.68
open: 161.83
high: 163.25
low: 160.38
mid: 162.67
volume: 0
bidSize: 100
bidPrice: 162.34
askSize: 100
askPrice: 163.0
- ticker: 'SPY'
timestamp: '2019-01-30T11:12:29.505261845-05:00'
quoteTimestamp: '2019-01-30T11:12:29.505261845-05:00'
lastSaleTimeStamp: '2019-01-30T11:12:16.643833612-05:00'
last: 265.41
lastSize: 617
tngoLast: 265.405
prevClose: 263.41
open: 264.62
high: 265.445
low: 264.225
mid: 265.405
volume: 0
bidSize: 500
bidPrice: 265.39
askSize: 100
askPrice: 265.42
text/csv:
schema:
type: string
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
iex-single: &iex-single
get:
summary: Get current top-of-book and last price for a specific ticker
description: |
Retrieve current top-of-book (bid/ask) and last price data for a specific ticker symbol.
Returns real-time reference prices or full TOPS feed data (requires IEX Exchange registration).
This endpoint provides:
- Top-of-Book (Bid/Ask) data
- Last Sale (trade) data
- Tiingo-enriched convenience fields (tngoLast, mid, open, high, low)
- Volume data (IEX only during trading, all exchanges after close)
- Quotes updated to nanosecond precision
operationId: getIEXQuote
tags:
- IEX
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/FormatParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with top-of-book and last price data
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/iex-schemas.yaml#/IEXTopOfBook'
minItems: 1
maxItems: 1
examples:
single-ticker:
summary: Single ticker response
value:
- ticker: 'AAPL'
timestamp: '2019-01-30T10:33:38.186520297-05:00'
quoteTimestamp: '2019-01-30T10:33:38.186520297-05:00'
lastSaleTimeStamp: '2019-01-30T10:33:34.176037579-05:00'
last: 162.37
lastSize: 100
tngoLast: 162.33
prevClose: 154.68
open: 161.83
high: 163.25
low: 160.38
mid: 162.67
volume: 0
bidSize: 100
bidPrice: 162.34
askSize: 100
askPrice: 163.0
text/csv:
schema:
type: string
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
iex-prices: &iex-prices
get:
summary: Get historical intraday prices
description: |
Retrieve historical intraday prices for a stock in OHLC format. Supports various resampling frequencies
from 1-minute to daily bars.
Features:
- OHLC (Open, High, Low, Close) data
- Configurable time intervals (1min to daily)
- Optional after-hours data inclusion
- Force-fill option for gaps in data
- IEX-only volume data (available with explicit columns parameter)
Example use cases:
- Current day OHLC: `resampleFreq=1day`
- 5-minute bars: `startDate=2019-01-02&resampleFreq=5min`
- Hourly bars with gaps filled: `startDate=2025-12-01&resampleFreq=1hour&forceFill=true`
operationId: getIEXHistoricalPrices
tags:
- IEX
parameters:
- $ref: '../parameters/_index.yaml#/TickerPathParam'
- $ref: '../parameters/_index.yaml#/StartDateParam'
- $ref: '../parameters/_index.yaml#/EndDateParam'
- name: resampleFreq
in: query
required: false
schema:
type: string
pattern: '^\d+(min|hour|day)$'
default: '5min'
description: |
Frequency for resampling OHLC data. Format: number + unit (min/hour/day).
Minimum value is 1min.
Examples: '1min', '5min', '15min', '1hour', '4hour', '1day'
example: '5min'
- name: afterHours
in: query
required: false
schema:
type: boolean
default: false
description: If true, includes pre-market and post-market data if available
- name: forceFill
in: query
required: false
schema:
type: boolean
default: false
description: |
If true, fills gaps in data by using the previous OHLC values when no trade/quote update
occurred for a given time period
- name: columns
in: query
required: false
schema:
type: string
pattern: '^[a-z]+(,[a-z]+)*$'
description: |
Comma-separated list of columns to include in response.
Available columns: open, high, low, close, volume.
Note: Volume data is only exposed if explicitly requested.
example: 'open,high,low,close,volume'
- $ref: '../parameters/_index.yaml#/FormatParam'
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with historical intraday price data
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/iex-schemas.yaml#/IEXPrice'
examples:
five-minute-bars:
summary: 5-minute OHLC bars
value:
- date: '2019-01-02T14:30:00.000Z'
open: 154.74
high: 155.52
low: 154.58
close: 154.76
volume: 16102
- date: '2019-01-02T14:35:00.000Z'
open: 154.8
high: 155.0
low: 154.31
close: 154.645
volume: 19127
daily-bar:
summary: Daily OHLC bar
value:
- date: '2019-01-02T00:00:00.000Z'
open: 154.89
high: 158.85
low: 154.23
close: 157.92
text/csv:
schema:
type: string
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

212
openapi/paths/news.yaml Normal file
View File

@@ -0,0 +1,212 @@
# News API Path Definitions
# Reference these using: $ref: '../paths/news.yaml#/PathName'
news: &news
get:
summary: Get latest news articles
description: |
Retrieves the latest news articles from Tiingo's comprehensive news feeds.
Tiingo incorporates financial news sites as well as financial blogs and tags them using proprietary algorithms.
On a typical day, Tiingo adds over 8,000-12,000 articles.
This endpoint supports filtering by tickers, tags, source domains, and date ranges.
Results can be sorted by either publishedDate or crawlDate in descending order.
operationId: getNews
tags:
- News
parameters:
- $ref: '../parameters/_index.yaml#/TokenParam'
- name: tickers
in: query
required: false
schema:
type: array
items:
type: string
pattern: '^[A-Z0-9]+$'
style: form
explode: false
description: Comma-separated list of ticker symbols to filter news articles
example: ["AAPL", "GOOGL"]
- name: tags
in: query
required: false
schema:
type: array
items:
type: string
style: form
explode: false
description: Comma-separated list of tags/countries/topics to filter news articles
example: ["election", "argentina"]
- name: source
in: query
required: false
schema:
type: array
items:
type: string
format: hostname
style: form
explode: false
description: Comma-separated list of source domains to filter news articles
example: ["bloomberg.com", "reuters.com"]
- $ref: '../parameters/_index.yaml#/StartDateParam'
- $ref: '../parameters/_index.yaml#/EndDateParam'
- name: limit
in: query
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 100
description: Maximum number of news objects to return. Default is 100, max is 1000. Contact support@tiingo.com for adjustments.
- name: offset
in: query
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
description: Pagination variable used alongside limit. Returns results shifted by offset. Example - limit=100, offset=2 returns results 2-102 instead of 0-99.
- name: sortBy
in: query
required: false
schema:
type: string
enum:
- publishedDate
- crawlDate
default: publishedDate
description: The date field to sort results by in descending order. Defaults to publishedDate.
responses:
'200':
description: Successful response with news articles
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/news-schemas.yaml#/NewsArticle'
examples:
singleArticle:
summary: Example news article
value:
- source: "cnbc.com"
crawlDate: "2019-01-29T22:20:01.696871Z"
description: "Apple CEO Tim Cook told CNBC that trade tensions between the U.S. and China have improved since late December."
url: "https://www.cnbc.com/2019/01/29/apples-ceo-sees-optimism-as-trade-tension-between-us-and-china-lessens.html"
publishedDate: "2019-01-29T22:17:00Z"
tags: ["China", "Economic Measures", "Economics", "Markets", "Stock", "Technology"]
tickers: ["AAPL"]
title: "Apple's CEO sees optimism as trade tension between U.S. and China lessens"
id: 28515261
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
bulk-list: &bulk-list
get:
summary: List available bulk download files
description: |
Returns a list of all available bulk download files for the entire news database.
An "incremental" batchType file is added every evening. At 12am EST, a batch process
runs saving all news articles for the past 24 hours.
**Note:** Bulk Download is only available to institutional clients.
operationId: listBulkDownloadFiles
tags:
- News
parameters:
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with list of bulk download files
content:
application/json:
schema:
type: array
items:
$ref: '../schemas/news-schemas.yaml#/BulkDownloadFile'
examples:
bulkFileList:
summary: Example list of bulk download files
value:
- id: 755
filename: "bulkfile_2019-01-28_2019-01-29.tar.gz"
batchType: "incremental"
startDate: "2019-01-28T05:00:00Z"
endDate: "2019-01-29T05:00:00Z"
url: "https://api.tiingo.com/tiingo/news/bulk_download/755?token=YOUR_API_TOKEN"
fileSizeUncompressed: 10385878
fileSizeCompressed: 3018550
- id: 754
filename: "bulkfile_2019-01-27_2019-01-28.tar.gz"
batchType: "incremental"
startDate: "2019-01-27T05:00:00Z"
endDate: "2019-01-28T05:00:00Z"
url: "https://api.tiingo.com/tiingo/news/bulk_download/754?token=YOUR_API_TOKEN"
fileSizeUncompressed: 9854321
fileSizeCompressed: 2945678
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
bulk-download: &bulk-download
get:
summary: Download a specific bulk news file
description: |
Downloads a specific batch file by ID. The file contains news articles in compressed format (gzip).
Use the bulk-list endpoint to get the list of available files and their IDs.
The downloaded file is in tar.gz format and contains news articles for the specified date range.
**Note:** Bulk Download is only available to institutional clients.
operationId: downloadBulkFile
tags:
- News
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
description: The unique ID that corresponds to the batch file you would like to download
example: 755
- $ref: '../parameters/_index.yaml#/TokenParam'
responses:
'200':
description: Successful response with bulk download file (binary tar.gz)
content:
application/gzip:
schema:
type: string
format: binary
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'

144
openapi/paths/splits.yaml Normal file
View File

@@ -0,0 +1,144 @@
# Splits API Endpoint Definitions
# Corporate Actions - Splits endpoints for historical and future split data
splits-batch: &splits-batch
get:
summary: Get batch split data
description: >
Get past, present, and future splits for all tickers. Returns detailed split data
for stocks, ETFs, and mutual funds. Split status can be either active ("a") or
cancelled ("c"). This endpoint is in beta and available to customers with the
End-of-Day endpoint entitlement.
operationId: getSplitsBatch
tags:
- Corporate Actions
parameters:
- $ref: '../parameters/_index.yaml#/TokenParam'
- name: exDate
in: query
required: false
schema:
type: string
format: date
description: >
The ex-date to filter splits. Returns splits with the specified ex-date.
Defaults to current date if not provided
example: '2023-08-25'
- name: tickers
in: query
required: false
schema:
type: string
description: Comma-separated list of tickers to filter results
example: 'AAPL,TSLA'
responses:
'200':
description: Successful response with array of splits
content:
application/json:
schema:
$ref: '../schemas/splits-schemas.yaml#/SplitArray'
examples:
multipleSplits:
summary: Multiple splits on a specific date
value:
- permaTicker: 'AAPL'
ticker: 'AAPL'
exDate: '2023-08-25'
splitFrom: 1.0
splitTo: 1.04347826
splitFactor: 1.04347826
splitStatus: 'a'
- permaTicker: 'TSLA'
ticker: 'TSLA'
exDate: '2023-08-28'
splitFrom: 1.0
splitTo: 3.0
splitFactor: 3.0
splitStatus: 'a'
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'
splits-ticker: &splits-ticker
get:
summary: Get split data for specific ticker
description: >
Get historical and future split timeseries data for a specific ticker.
This endpoint allows you to query past and future split data for stocks, ETFs,
and mutual funds. Split status can be either active ("a") or cancelled ("c").
Use startExDate and endExDate parameters to filter the date range.
operationId: getSplitsByTicker
tags:
- Corporate Actions
parameters:
- name: ticker
in: path
required: true
schema:
type: string
pattern: '^[A-Z0-9]+$'
description: The stock ticker symbol (e.g., AAPL, CVS, TSLA)
example: 'CVS'
- $ref: '../parameters/_index.yaml#/TokenParam'
- name: startExDate
in: query
required: false
schema:
type: string
format: date
description: >
The starting ex-date for historical split timeseries data.
Returns splits from this date onward. Defaults to current date if not provided
example: '2002-08-25'
- name: endExDate
in: query
required: false
schema:
type: string
format: date
description: >
The ending ex-date for filtering splits. Returns splits up to this date
example: '2023-12-31'
responses:
'200':
description: Successful response with array of historical splits
content:
application/json:
schema:
$ref: '../schemas/splits-schemas.yaml#/SplitArray'
examples:
historicalSplits:
summary: Historical splits for CVS
value:
- permaTicker: 'CVS'
ticker: 'CVS'
exDate: '2002-08-25'
splitFrom: 1.0
splitTo: 2.0
splitFactor: 2.0
splitStatus: 'a'
- permaTicker: 'CVS'
ticker: 'CVS'
exDate: '2015-06-01'
splitFrom: 1.0
splitTo: 1.0
splitFactor: 1.0
splitStatus: 'c'
'400':
$ref: '../responses/_index.yaml#/BadRequest'
'401':
$ref: '../responses/_index.yaml#/Unauthorized'
'404':
$ref: '../responses/_index.yaml#/NotFound'
'429':
$ref: '../responses/_index.yaml#/TooManyRequests'
'500':
$ref: '../responses/_index.yaml#/InternalServerError'