aljaz/tiingo-python
1
1
Fork 0
mirror of https://github.com/hydrosquall/tiingo-python.git synced 2026-02-09 12:24:25 +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

168
openapi/schemas/_index.yaml Normal file
View File

@@ -0,0 +1,168 @@
# OpenAPI Schemas Index
# This file provides a centralized index of all schema components across the Tiingo API
# organized by endpoint category. Each schema is defined with a YAML anchor and references
# the actual schema definition from its respective file.
# ========================================================================
# COMMON SCHEMAS - Shared across all endpoints
# Reference: ./common.yaml
# ========================================================================
Date: &Date
$ref: './common.yaml#/Date'
DateTime: &DateTime
$ref: './common.yaml#/DateTime'
Ticker: &Ticker
$ref: './common.yaml#/Ticker'
Currency: &Currency
$ref: './common.yaml#/Currency'
ErrorResponse: &ErrorResponse
$ref: './common.yaml#/ErrorResponse'
# ========================================================================
# END-OF-DAY STOCK PRICE SCHEMAS
# Reference: https://www.tiingo.com/documentation/end-of-day
# File: ./eod-schemas.yaml
# ========================================================================
PriceData: &PriceData
$ref: './eod-schemas.yaml#/PriceData'
TickerMetadata: &TickerMetadata
$ref: './eod-schemas.yaml#/TickerMetadata'
# ========================================================================
# NEWS API SCHEMAS
# File: ./news-schemas.yaml
# ========================================================================
NewsArticle: &NewsArticle
$ref: './news-schemas.yaml#/NewsArticle'
BulkDownloadFile: &BulkDownloadFile
$ref: './news-schemas.yaml#/BulkDownloadFile'
# ========================================================================
# CRYPTOCURRENCY API SCHEMAS
# File: ./crypto-schemas.yaml
# ========================================================================
CryptoCurrency: &CryptoCurrency
$ref: './crypto-schemas.yaml#/CryptoCurrency'
CryptoTicker: &CryptoTicker
$ref: './crypto-schemas.yaml#/CryptoTicker'
ResampleFreq: &ResampleFreq
$ref: './crypto-schemas.yaml#/ResampleFreq'
PriceDataItem: &PriceDataItem
$ref: './crypto-schemas.yaml#/PriceDataItem'
ExchangeDataItem: &ExchangeDataItem
$ref: './crypto-schemas.yaml#/ExchangeDataItem'
CryptoPrice: &CryptoPrice
$ref: './crypto-schemas.yaml#/CryptoPrice'
CryptoMetadata: &CryptoMetadata
$ref: './crypto-schemas.yaml#/CryptoMetadata'
TopOfBookData: &TopOfBookData
$ref: './crypto-schemas.yaml#/TopOfBookData'
TopOfBookExchangeData: &TopOfBookExchangeData
$ref: './crypto-schemas.yaml#/TopOfBookExchangeData'
CryptoTopOfBook: &CryptoTopOfBook
$ref: './crypto-schemas.yaml#/CryptoTopOfBook'
# ========================================================================
# FOREX API SCHEMAS
# File: ./forex-schemas.yaml
# ========================================================================
ForexTopOfBook: &ForexTopOfBook
$ref: './forex-schemas.yaml#/ForexTopOfBook'
ForexPrice: &ForexPrice
$ref: './forex-schemas.yaml#/ForexPrice'
# ========================================================================
# IEX EXCHANGE API SCHEMAS
# Reference: https://api.tiingo.com/documentation/iex
# File: ./iex-schemas.yaml
# ========================================================================
IEXTopOfBook: &IEXTopOfBook
$ref: './iex-schemas.yaml#/IEXTopOfBook'
IEXPrice: &IEXPrice
$ref: './iex-schemas.yaml#/IEXPrice'
# ========================================================================
# FUNDAMENTALS API SCHEMAS
# File: ./fundamentals-schemas.yaml
# ========================================================================
FundamentalDefinition: &FundamentalDefinition
$ref: './fundamentals-schemas.yaml#/FundamentalDefinition'
DataPoint: &DataPoint
$ref: './fundamentals-schemas.yaml#/DataPoint'
StatementData: &StatementData
$ref: './fundamentals-schemas.yaml#/StatementData'
FinancialStatement: &FinancialStatement
$ref: './fundamentals-schemas.yaml#/FinancialStatement'
DailyMetric: &DailyMetric
$ref: './fundamentals-schemas.yaml#/DailyMetric'
FundamentalMeta: &FundamentalMeta
$ref: './fundamentals-schemas.yaml#/FundamentalMeta'
# ========================================================================
# MUTUAL FUNDS AND ETF SCHEMAS
# Reference: /docs/api_extracted/mutual-fund-etf-fees.md
# File: ./funds-schemas.yaml
# ========================================================================
OtherShareClass: &OtherShareClass
$ref: './funds-schemas.yaml#/OtherShareClass'
FundOverview: &FundOverview
$ref: './funds-schemas.yaml#/FundOverview'
CustomFee: &CustomFee
$ref: './funds-schemas.yaml#/CustomFee'
FundMetrics: &FundMetrics
$ref: './funds-schemas.yaml#/FundMetrics'
# ========================================================================
# DIVIDENDS AND DISTRIBUTIONS SCHEMAS
# File: ./dividends-schemas.yaml
# ========================================================================
Distribution: &Distribution
$ref: './dividends-schemas.yaml#/Distribution'
DistributionYield: &DistributionYield
$ref: './dividends-schemas.yaml#/DistributionYield'
# ========================================================================
# STOCK SPLITS SCHEMAS
# File: ./splits-schemas.yaml
# ========================================================================
Split: &Split
$ref: './splits-schemas.yaml#/Split'
SplitArray: &SplitArray
$ref: './splits-schemas.yaml#/SplitArray'

39
openapi/schemas/common.yaml Normal file
View File

@@ -0,0 +1,39 @@
Date: &Date
type: string
format: date
pattern: '^\d{4}-\d{2}-\d{2}$'
description: Date in ISO 8601 format
example: '2025-12-13'
DateTime: &DateTime
type: string
format: date-time
description: Timestamp in ISO 8601 format
example: '2025-12-13T18:00:00.000Z'
Ticker: &Ticker
type: string
pattern: '^[A-Z0-9]+$'
description: Stock, ETF, or crypto ticker symbol
example: 'AAPL'
Currency: &Currency
type: string
pattern: '^[A-Z]{3}$'
description: ISO 4217 currency code
example: 'USD'
ErrorResponse: &ErrorResponse
type: object
properties:
error:
type: string
description: Error message
detail:
type: string
description: Detailed error information
required:
- error
example:
error: "Invalid ticker symbol"
detail: "Ticker 'XYZ123' not found"

303
openapi/schemas/crypto-schemas.yaml Normal file
View File

@@ -0,0 +1,303 @@
# Crypto Schema Definitions for Tiingo API
# Reference these using: $ref: '../schemas/crypto-schemas.yaml#/SchemaName'
CryptoCurrency: &CryptoCurrency
type: string
pattern: '^[a-z0-9]+$'
description: Cryptocurrency code (lowercase)
example: 'btc'
CryptoTicker: &CryptoTicker
type: string
pattern: '^[a-z0-9]+$'
description: Cryptocurrency ticker (e.g., btcusd, ethusd)
example: 'btcusd'
ResampleFreq: &ResampleFreq
type: string
pattern: '^[0-9]+(min|hour|day)$'
description: Resampling frequency for historical data
enum:
- '1min'
- '5min'
- '15min'
- '30min'
- '1hour'
- '2hour'
- '4hour'
- '1day'
example: '5min'
# Price Data Schemas
PriceDataItem: &PriceDataItem
type: object
description: OHLCV price data for a specific time period
properties:
date:
type: string
format: date-time
description: The datetime this data pertains to, dependent on resampleFreq parameter
example: '2019-01-02T00:00:00.000Z'
open:
type: number
format: float
description: The opening price for the asset
example: 3690.01
high:
type: number
format: float
description: The high price for the asset
example: 3701.0
low:
type: number
format: float
description: The low price for the asset
example: 3600.65
close:
type: number
format: float
description: The closing price for the asset
example: 3610.32
volume:
type: number
format: float
description: The volume in the base currency
example: 1234.56
volumeNotional:
type: number
format: float
description: The volume in the quote currency (volumeNotional = close * volume)
example: 4456789.12
tradesDone:
type: integer
format: int32
description: The number of trades executed
example: 5000
required:
- date
- open
- high
- low
- close
- volume
- volumeNotional
- tradesDone
ExchangeDataItem: &ExchangeDataItem
type: object
description: Raw exchange-level price data
additionalProperties:
type: object
description: Exchange-specific data keyed by exchange name
properties:
date:
type: string
format: date-time
open:
type: number
format: float
high:
type: number
format: float
low:
type: number
format: float
close:
type: number
format: float
volume:
type: number
format: float
volumeNotional:
type: number
format: float
tradesDone:
type: integer
CryptoPrice: &CryptoPrice
type: object
description: Cryptocurrency price response with metadata and price data
properties:
ticker:
type: string
description: Ticker related to the asset
example: 'btcusd'
baseCurrency:
type: string
description: The base pair of the cryptocurrency (e.g., "btc" for "btcusd")
example: 'btc'
quoteCurrency:
type: string
description: The quote pair of the cryptocurrency (e.g., "usd" for "btcusd")
example: 'usd'
priceData:
type: array
description: Array of price data points
items:
$ref: '#/PriceDataItem'
exchangeData:
$ref: '#/ExchangeDataItem'
description: Underlying data for each exchange (only included if includeRawExchangeData=true)
required:
- ticker
- baseCurrency
- quoteCurrency
- priceData
# Metadata Schemas
CryptoMetadata: &CryptoMetadata
type: object
description: Cryptocurrency metadata information
properties:
ticker:
type: string
description: Ticker related to the asset
example: 'btcusd'
baseCurrency:
type: string
description: The base pair of the cryptocurrency
example: 'btc'
quoteCurrency:
type: string
description: The quote pair of the cryptocurrency
example: 'usd'
name:
type: string
description: Full-length name of the asset
example: 'Bitcoin'
description:
type: string
description: Long-form description of the asset
example: 'Bitcoin is a cryptocurrency and worldwide payment system.'
required:
- ticker
- baseCurrency
- quoteCurrency
- name
# Top-of-Book Schemas
TopOfBookData: &TopOfBookData
type: object
description: Top-of-book data with bid/ask and last trade information
properties:
quoteTimestamp:
type: string
format: date-time
description: Timestamp when quote (bid/ask) data was last received
example: '2019-01-02T12:34:56.789Z'
lastSaleTimestamp:
type: string
format: date-time
description: Timestamp when last trade data was received
example: '2019-01-02T12:34:56.789Z'
lastPrice:
type: number
format: float
description: Last executed price on any exchange
example: 3610.32
lastSize:
type: number
format: float
description: Volume of the last trade in base currency
example: 0.5
lastSizeNotional:
type: number
format: float
description: Notional value of last trade (lastSizeNotional = lastPrice * lastSize)
example: 1805.16
lastExchange:
type: string
description: Full name of the exchange where last trade occurred
example: 'Coinbase'
bidSize:
type: number
format: float
description: Amount at the bid price
example: 1.2
bidPrice:
type: number
format: float
description: Current bid price
example: 3609.50
bidExchange:
type: string
description: Full name of the exchange with the best bid
example: 'Binance'
askSize:
type: number
format: float
description: Amount at the ask price
example: 0.8
askPrice:
type: number
format: float
description: Current ask price
example: 3611.00
askExchange:
type: string
description: Full name of the exchange with the best ask
example: 'Kraken'
TopOfBookExchangeData: &TopOfBookExchangeData
type: object
description: Exchange-level top-of-book data
additionalProperties:
type: object
description: Exchange-specific top-of-book data keyed by exchange name
properties:
quoteTimestamp:
type: string
format: date-time
lastSaleTimestamp:
type: string
format: date-time
lastPrice:
type: number
format: float
lastSize:
type: number
format: float
bidSize:
type: number
format: float
bidPrice:
type: number
format: float
askSize:
type: number
format: float
askPrice:
type: number
format: float
CryptoTopOfBook: &CryptoTopOfBook
type: object
description: Cryptocurrency top-of-book response with metadata and book data (DEPRECATED)
deprecated: true
properties:
ticker:
type: string
description: Ticker related to the asset
example: 'btcusd'
baseCurrency:
type: string
description: The base pair of the cryptocurrency
example: 'btc'
quoteCurrency:
type: string
description: The quote pair of the cryptocurrency
example: 'usd'
topOfBookData:
$ref: '#/TopOfBookData'
description: Top-of-book data
exchangeData:
$ref: '#/TopOfBookExchangeData'
description: Underlying data for each exchange (only included if includeRawExchangeData=true)
required:
- ticker
- baseCurrency
- quoteCurrency
- topOfBookData

92
openapi/schemas/dividends-schemas.yaml Normal file
View File

@@ -0,0 +1,92 @@
# Dividend and Distribution Schemas for Tiingo Corporate Actions API
# Reference these using: $ref: '../schemas/dividends-schemas.yaml#/SchemaName'
Distribution: &Distribution
type: object
description: Detailed dividend and distribution data for a stock, ETF, or mutual fund
properties:
permaTicker:
type: string
description: The Tiingo permaticker
example: AAPL
ticker:
type: string
description: Ticker related to the asset
example: AAPL
exDate:
$ref: './common.yaml#/DateTime'
description: The ex-date of the distribution. In the Tiingo EOD Endpoints, this is the date where "divCash" will be non-zero. This is also the date used for dividend price adjustments.
example: '2023-08-25T00:00:00.000Z'
paymentDate:
type: string
format: date-time
nullable: true
description: The payment date of the distribution
example: '2023-09-07T00:00:00.000Z'
recordDate:
type: string
format: date-time
nullable: true
description: The record date of the distribution
example: '2023-08-28T00:00:00.000Z'
declarationDate:
type: string
format: date-time
nullable: true
description: The declaration date of the distribution
example: '2023-07-27T00:00:00.000Z'
distribution:
type: number
format: float
description: The total distribution for the given date
example: 0.24
distributionFreqency:
type: string
description: |
The frequency associated with this distribution. Frequency codes:
- w: Weekly
- bm: Bimonthly
- m: Monthly
- tm: Trimesterly
- q: Quarterly
- sa: Semiannually
- a: Annually
- ir: Irregular
- f: Final
- u: Unspecified
- c: Cancelled
enum:
- w
- bm
- m
- tm
- q
- sa
- a
- ir
- f
- u
- c
example: q
required:
- permaTicker
- ticker
- exDate
- distribution
- distributionFreqency
DistributionYield: &DistributionYield
type: object
description: Historical yield metrics for a ticker's dividend distributions
properties:
date:
$ref: './common.yaml#/DateTime'
description: Date associated with the yield
example: '2024-01-01T00:00:00.000Z'
trailingDiv1Y:
type: string
description: The trailing distribution yield for the asset based on the previous 1 year of distributions
example: '0.92'
required:
- date
- trailingDiv1Y

119
openapi/schemas/eod-schemas.yaml Normal file
View File

@@ -0,0 +1,119 @@
# End-of-Day Stock Price API Schemas
# Reference: https://www.tiingo.com/documentation/end-of-day
PriceData: &PriceData
type: array
description: Array of End-of-Day price data objects with OHLCV (Open, High, Low, Close, Volume) data
items:
type: object
properties:
date:
$ref: '../schemas/common.yaml#/Date'
description: The date this data pertains to
open:
type: number
format: float
description: The opening price for the asset on the given date
example: 150.25
high:
type: number
format: float
description: The high price for the asset on the given date
example: 152.50
low:
type: number
format: float
description: The low price for the asset on the given date
example: 149.75
close:
type: number
format: float
description: The closing price for the asset on the given date
example: 151.80
volume:
type: integer
format: int64
description: The number of shares traded for the asset
example: 50000000
adjOpen:
type: number
format: float
description: The adjusted opening price for the asset on the given date (includes splits and dividends)
example: 150.25
adjHigh:
type: number
format: float
description: The adjusted high price for the asset on the given date (includes splits and dividends)
example: 152.50
adjLow:
type: number
format: float
description: The adjusted low price for the asset on the given date (includes splits and dividends)
example: 149.75
adjClose:
type: number
format: float
description: The adjusted closing price for the asset on the given date (includes splits and dividends)
example: 151.80
adjVolume:
type: integer
format: int64
description: The number of shares traded for the asset (adjusted for splits)
example: 50000000
divCash:
type: number
format: float
description: The dividend paid out on the given date (note that date will be the exDate for the dividend)
example: 0.0
splitFactor:
type: number
format: float
description: The factor used to adjust prices when a company splits, reverse splits, or pays a distribution
example: 1.0
required:
- date
- close
- volume
TickerMetadata: &TickerMetadata
type: object
description: Metadata information about a stock ticker
properties:
ticker:
$ref: '../schemas/common.yaml#/Ticker'
description: Ticker related to the asset
name:
type: string
description: Full-length name of the asset
example: "Apple Inc"
exchangeCode:
type: string
description: An identifier that maps which Exchange this asset is listed on
enum:
- NASDAQ
- NYSE
- AMEX
- OTC
- BATS
- IEX
example: "NASDAQ"
description:
type: string
description: Long-form description of the asset
example: "Apple Inc is an American multinational technology company that specializes in consumer electronics, software and online services."
startDate:
type: string
format: date
nullable: true
description: The earliest date we have price data available for the asset. When null, no price data is available
example: "1990-01-01"
endDate:
type: string
format: date
nullable: true
description: The latest date we have price data available for the asset. When null, no price data is available
example: "2024-01-01"
required:
- ticker
- name
- exchangeCode

106
openapi/schemas/forex-schemas.yaml Normal file
View File

@@ -0,0 +1,106 @@
# Tiingo Forex API Schema Definitions
# Reference these using: $ref: './forex-schemas.yaml#/ForexTopOfBook'
ForexTopOfBook: &ForexTopOfBook
type: object
description: Real-time top-of-book data for a forex pair including bid/ask prices and sizes
properties:
ticker:
type: string
description: Forex ticker pair
pattern: '^[a-z]{6}$'
example: eurusd
quoteTimestamp:
type: string
format: date-time
description: The timestamp when the data was last refreshed (ISO 8601 format with timezone)
example: '2019-07-01T21:00:01.289000+00:00'
midPrice:
type: number
format: float
nullable: true
description: The mid price calculated as (bidPrice + askPrice) / 2.0 when both bid and ask prices are not null
example: 1.11865
bidSize:
type: number
format: float
description: The amount of units available at the bid price
example: 1000000.0
bidPrice:
type: number
format: float
nullable: true
description: The current bid price
example: 1.1186
askSize:
type: number
format: float
description: The amount of units available at the ask price
example: 1000000.0
askPrice:
type: number
format: float
nullable: true
description: The current ask price
example: 1.1187
required:
- ticker
- quoteTimestamp
- bidSize
- askSize
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
ForexPrice: &ForexPrice
type: object
description: Historical OHLC (Open, High, Low, Close) price data for a forex pair
properties:
date:
type: string
format: date-time
description: The date/time this data pertains to (ISO 8601 format). Format depends on resampleFreq parameter
example: '2019-06-28T20:00:00.000Z'
open:
type: number
format: float
description: The opening price for the asset in the given period
example: 1.1232
high:
type: number
format: float
description: The high price for the asset in the given period
example: 1.1254
low:
type: number
format: float
description: The low price for the asset in the given period
example: 1.1220
close:
type: number
format: float
description: The closing price for the asset in the given period
example: 1.1245
volume:
type: number
format: float
nullable: true
description: Trading volume for the period (when available)
example: null
required:
- date
- open
- high
- low
- close
example:
date: '2019-06-28T20:00:00.000Z'
open: 1.1232
high: 1.1254
low: 1.1220
close: 1.1245

255
openapi/schemas/fundamentals-schemas.yaml Normal file
View File

@@ -0,0 +1,255 @@
# Tiingo Fundamentals API Schemas
# Reference these using: $ref: '../schemas/fundamentals-schemas.yaml#/SchemaName'
FundamentalDefinition: &FundamentalDefinition
type: object
description: Definition of a fundamental metric field
properties:
dataCode:
type: string
description: An identifier representing the fundamentals field the value belongs to (e.g., "peRatio")
example: "peRatio"
name:
type: string
description: A human-friendly readable name of the field
example: "Price/Earnings Ratio"
description:
type: string
description: A description of the field
example: "The price to earnings ratio of the company"
statementType:
type: string
description: Which statement this value belongs to
enum:
- balanceSheet
- incomeStatement
- cashFlow
- overview
example: "overview"
units:
type: string
description: The unit the field value is in. Value is either "$", "%" or blank. If blank, value may either be an integer (like shares outstanding) or a ratio
enum:
- "$"
- "%"
- ""
example: ""
required:
- dataCode
- name
- description
- statementType
- units
DataPoint: &DataPoint
type: object
description: A single data point with a code and value
properties:
dataCode:
type: string
description: An identifier representing the fundamentals field the value belongs to (e.g., "peRatio")
example: "totalAssets"
value:
type: number
format: float
description: The value of the field corresponding to the dataCode
example: 352755000000
required:
- dataCode
- value
StatementData: &StatementData
type: object
description: Statement data broken out by four different statement types
properties:
balanceSheet:
type: array
description: Balance sheet data (assets, liabilities, equity)
items:
$ref: '#/DataPoint'
incomeStatement:
type: array
description: Income statement data (revenue, expenses, income)
items:
$ref: '#/DataPoint'
cashFlow:
type: array
description: Cash flow statement data (operating, investing, financing activities)
items:
$ref: '#/DataPoint'
overview:
type: array
description: Metrics and ratios that may be a combination of fields from various statements
items:
$ref: '#/DataPoint'
required:
- balanceSheet
- incomeStatement
- cashFlow
- overview
FinancialStatement: &FinancialStatement
type: object
description: Historical quarterly or annual financial statement
properties:
date:
type: string
format: date-time
description: The date the statement data was released to the public
example: "2023-12-29T00:00:00.000Z"
quarter:
type: integer
format: int32
description: An integer corresponding to the fiscal quarter reported. A value of "0" means this is an Annual Report. A value of "1" through "4" corresponds to the respective fiscal quarter
minimum: 0
maximum: 4
example: 1
year:
type: integer
format: int32
description: An integer corresponding to the fiscal year reported
example: 2024
statementData:
$ref: '#/StatementData'
required:
- date
- quarter
- year
- statementData
DailyMetric: &DailyMetric
type: object
description: Daily fundamental metrics that rely on price data and update daily
properties:
date:
type: string
format: date-time
description: The date the daily data corresponds to
example: "2023-12-29T00:00:00.000Z"
marketCap:
type: number
format: float
description: The value of the field corresponding to the market capitalization
example: 3050000000000
nullable: true
enterpriseVal:
type: number
format: float
description: The value of the field corresponding to the enterprise value
example: 2950000000000
nullable: true
peRatio:
type: number
format: float
description: The value of the field corresponding to the price/earnings ratio
example: 29.45
nullable: true
pbRatio:
type: number
format: float
description: The value of the field corresponding to the price/book ratio
example: 48.32
nullable: true
trailingPEG1Y:
type: number
format: float
description: The value of the field corresponding to the trailing 1 year PEG Ratio
example: 2.15
nullable: true
required:
- date
additionalProperties: true
x-note: "New daily metrics are continuously added, so fields will change over time. Use the 'columns' parameter to ensure consistent output."
FundamentalMeta: &FundamentalMeta
type: object
description: Company metadata and information about when data was last updated
properties:
permaTicker:
type: string
description: Permanent Tiingo Ticker mapping to the security. Can be used as a primary key
example: "AAPL"
ticker:
type: string
description: Ticker related to the asset
example: "AAPL"
name:
type: string
description: Full-length name of the asset
example: "Apple Inc."
isActive:
type: boolean
description: Boolean describing whether or not the ticker is still actively traded. If false, this ticker is delisted
example: true
isADR:
type: boolean
description: Boolean describing whether or not the ticker is an ADR. Value is true if listed ticker is an ADR
example: false
sector:
type: string
description: Sector information that is derived from sicSector and is meant to approximate GICS
example: "Technology"
nullable: true
industry:
type: string
description: Industry information that is derived from sicIndustry and is meant to approximate GICS
example: "Consumer Electronics"
nullable: true
sicCode:
type: integer
format: int32
description: SIC Code that represents company's business activities
example: 3571
nullable: true
sicSector:
type: string
description: Sector as determined by the SIC Code
example: "Industrial and Commercial Machinery and Computer Equipment"
nullable: true
sicIndustry:
type: string
description: Industry as determined by the SIC Code
example: "Electronic Computers"
nullable: true
reportingCurrency:
type: string
description: The currency the company reports their SEC statement filings in
example: "USD"
nullable: true
location:
type: string
description: Location/domicile of the company. States are included for U.S. companies, otherwise countries for non-US companies
example: "California"
nullable: true
companyWebsite:
type: string
format: uri
description: The website of the company when available
example: "https://www.apple.com"
nullable: true
secFilingWebsite:
type: string
format: uri
description: A URL to where you can find the company's SEC filings directly on the SEC website
example: "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=&dateb=&owner=exclude&count=100"
nullable: true
statementLastUpdated:
type: string
format: date-time
description: The timestamp the statement data/endpoint was last updated for the ticker
example: "2024-01-15T10:30:00.000Z"
nullable: true
dailyLastUpdated:
type: string
format: date-time
description: The timestamp the daily data/endpoint was last updated for the ticker
example: "2024-01-15T08:00:00.000Z"
nullable: true
required:
- permaTicker
- ticker
- name
- isActive
- isADR
additionalProperties: true
x-note: "As new meta data about companies and their fundamentals is added, the endpoint output will change. Use the 'columns' parameter to ensure consistent output."

235
openapi/schemas/funds-schemas.yaml Normal file
View File

@@ -0,0 +1,235 @@
# Tiingo Mutual Fund and ETF Fees API Schemas
# Reference: /docs/api_extracted/mutual-fund-etf-fees.md
OtherShareClass: &OtherShareClass
type: object
description: Information about a related share class of the fund
properties:
ticker:
type: string
description: Ticker related to the fund
example: "VTSMX"
name:
type: string
description: Full-length name of the fund
example: "Vanguard Total Stock Market Index Fund"
shareClass:
type: string
description: Share class of the fund as described by the parent fund company
example: "Investor Shares"
netExpense:
type: number
format: float
description: The top-level net expense ratio for the fund (expressed as decimal, e.g., 0.0055 = 0.55%)
example: 0.0055
required:
- ticker
- name
- shareClass
- netExpense
FundOverview: &FundOverview
type: object
description: Top-level fund data including description and share classes
properties:
ticker:
type: string
description: Ticker related to the fund
example: "VTSAX"
name:
type: string
description: Full-length name of the fund
example: "Vanguard Total Stock Market Index Fund"
description:
type: string
description: Long-form description of the fund
example: "Long description of the fund..."
shareClass:
type: string
description: Share class of the fund as described by the parent fund company
example: "Admiral Shares"
netExpense:
type: number
format: float
description: The top-level net expense ratio for the fund (expressed as decimal, e.g., 0.0035 = 0.35%)
example: 0.0035
otherShareClasses:
type: array
description: An array of objects representing related share classes of the given fund
items:
$ref: '#/OtherShareClass'
required:
- ticker
- name
- description
- shareClass
- netExpense
- otherShareClasses
CustomFee: &CustomFee
type: object
description: Custom fee charged by the fund (e.g., check processing fee)
properties:
label:
type: string
description: Label related to the custom fee
example: "Check Processing Fee"
value:
type: number
format: float
description: Value of the custom fee field
example: 0.0000
units:
type: string
description: '"$" if the value is in dollars or "%" if the value is in percentage terms'
enum:
- "$"
- "%"
example: "$"
parentFee:
type: string
description: The parent fee the custom fee belongs under
example: "shareholderFee"
required:
- label
- value
- units
- parentFee
FundMetrics: &FundMetrics
type: object
description: Detailed current and historical fee data for a mutual fund or ETF
properties:
prospectusDate:
allOf:
- $ref: './common.yaml#/Date'
description: The prospectus date when the corresponding fund expense data was published
example: "2024-01-15"
netExpense:
type: number
format: float
description: Fund's net expense ratio, or the net expenses related to the fund (expressed as decimal)
example: 0.0035
grossExpense:
type: number
format: float
description: Fund's gross expense ratio, or the expenses related to running the fund (expressed as decimal)
example: 0.0040
managementFee:
type: number
format: float
description: Fund's management fee, or the fees paid to the manager and/or advisors (expressed as decimal)
example: 0.0025
12b1:
type: number
format: float
description: Fund's fee related to marketing expenses (expressed as decimal)
example: 0.0000
non12b1:
type: number
format: float
description: Fund's fee related to distribution and similar non-12b-1 fees (expressed as decimal)
example: 0.0000
otherExpenses:
type: number
format: float
description: Fund's other expenses, or expenses related to legal, administrative, custodial, etc. (expressed as decimal)
example: 0.0015
acquiredFundFees:
type: number
format: float
description: Fund's acquired fund fees, or expenses related to underlying businesses or funds (expressed as decimal)
example: 0.0000
feeWaiver:
type: number
format: float
description: Fund's fee waiver, or discount on fees (expressed as decimal)
example: 0.0005
exchangeFeeUSD:
type: number
format: float
description: Fund's exchange fee if charged in USD, or expenses related to exchanging or transferring funds to another fund in the fund's family
example: 0.0000
exchangeFeePercent:
type: number
format: float
description: Fund's exchange fee if charged as a percentage, or expenses related to exchanging or transferring funds to another fund in the fund's family (expressed as decimal)
example: 0.0000
frontLoad:
type: number
format: float
description: Fund's front load fee, or the upfront fee charged when investing in the fund (expressed as decimal)
example: 0.0000
backLoad:
type: number
format: float
description: Fund's back load fee, or the back-end fee charged when redeeming from the fund (expressed as decimal)
example: 0.0000
dividendLoad:
type: number
format: float
description: Dividend load fee, or charges on reinvested dividends (expressed as decimal)
example: 0.0000
shareholderFee:
type: number
format: float
description: Fund's shareholder fees, or the potential fees when buying/selling a fund (expressed as decimal)
example: 0.0000
accountFeeUSD:
type: number
format: float
description: Fund's account fees if charged in USD, or the fee required to maintain your account in USD
example: 0.0000
accountFeePercent:
type: number
format: float
description: Fund's account fees if charged as a percentage, or the fee required to maintain your account in percentage terms (expressed as decimal)
example: 0.0000
redemptionFeeUSD:
type: number
format: float
description: Fund's redemption fees if charged in USD, or the fee charged if funds are redeemed early (as defined by the fund company)
example: 0.0000
redemptionFeePercent:
type: number
format: float
description: Fund's redemption fees as a percentage, or the fee charged if funds are redeemed early (as defined by the fund company) (expressed as decimal)
example: 0.0000
portfolioTurnover:
type: number
format: float
description: Portfolio turnover (expressed as decimal)
example: 0.05
miscFees:
type: number
format: float
description: Fund's miscellaneous fees (expressed as decimal)
example: 0.0000
customFees:
type: array
description: Fund's custom fees. Array of custom fee objects
items:
$ref: '#/CustomFee'
required:
- prospectusDate
- netExpense
- grossExpense
- managementFee
- 12b1
- non12b1
- otherExpenses
- acquiredFundFees
- feeWaiver
- exchangeFeeUSD
- exchangeFeePercent
- frontLoad
- backLoad
- dividendLoad
- shareholderFee
- accountFeeUSD
- accountFeePercent
- redemptionFeeUSD
- redemptionFeePercent
- portfolioTurnover
- miscFees
- customFees

220
openapi/schemas/iex-schemas.yaml Normal file
View File

@@ -0,0 +1,220 @@
# IEX Exchange API Response Schemas
# Reference: https://api.tiingo.com/documentation/iex
IEXTopOfBook: &IEXTopOfBook
type: object
description: |
Top-of-book and last price data for a stock on IEX Exchange.
Note: Fields marked with "*IEX entitlement required*" will return null unless you are
registered with the IEX Exchange and have a market data policy in place. These fields
provide full TOPS feed data including direct bid/ask/last data from IEX.
Tiingo-enriched fields (tngoLast, mid, open, high, low) are calculated by Tiingo
and do not require IEX entitlement.
properties:
ticker:
$ref: '../schemas/common.yaml#/Ticker'
description: Ticker symbol for the asset
timestamp:
$ref: '../schemas/common.yaml#/DateTime'
description: Timestamp when the data was last refreshed
quoteTimestamp:
type: string
format: date-time
nullable: true
description: |
Timestamp when the last quote (bid/ask) data was received from IEX.
Requires IEX entitlement. Null if not entitled.
lastSaleTimeStamp:
type: string
format: date-time
nullable: true
description: |
Timestamp when the last trade (last/lastSize) data was received from IEX.
Requires IEX entitlement. Null if not entitled.
last:
type: number
format: double
nullable: true
description: |
Last trade price executed on IEX.
Requires IEX entitlement. Null if not entitled.
example: 162.37
lastSize:
type: integer
format: int32
nullable: true
description: |
Number of shares traded at the last price on IEX.
Requires IEX entitlement. Null if not entitled.
example: 100
tngoLast:
type: number
format: double
description: |
Tiingo-calculated last price. Either the last trade price or mid price.
The mid price is only used if the spread is not considered too wide by Tiingo's algorithm.
After the official exchange print comes in, this value changes to that value.
This is a Tiingo-enriched field and does not require IEX entitlement.
example: 162.33
prevClose:
type: number
format: double
description: |
Previous day's closing price of the security.
Can be from any exchange (NYSE, NASDAQ, IEX, etc.)
example: 154.68
open:
type: number
format: double
nullable: true
description: |
Opening price of the asset on the current day.
Tiingo-calculated field, does not require IEX entitlement.
example: 161.83
high:
type: number
format: double
nullable: true
description: |
High price of the asset on the current day.
Tiingo-calculated field, does not require IEX entitlement.
example: 163.25
low:
type: number
format: double
nullable: true
description: |
Low price of the asset on the current day.
Tiingo-calculated field, does not require IEX entitlement.
example: 160.38
mid:
type: number
format: double
nullable: true
description: |
Mid price at current timestamp when both bidPrice and askPrice are not null.
Formula: mid = (bidPrice + askPrice) / 2.0
Tiingo-calculated field, does not require IEX entitlement.
example: 162.67
volume:
type: integer
format: int64
description: |
Volume data. IEX volume throughout the trading day.
Once the official closing price is received, reflects total volume across all exchanges.
This field is provided for convenience.
example: 0
bidSize:
type: number
format: double
nullable: true
description: |
Number of shares available at the bid price.
Requires IEX entitlement. Null if not entitled.
example: 100
bidPrice:
type: number
format: double
nullable: true
description: |
Current bid price.
Requires IEX entitlement. Null if not entitled.
example: 162.34
askSize:
type: number
format: double
nullable: true
description: |
Number of shares available at the ask price.
Requires IEX entitlement. Null if not entitled.
example: 100
askPrice:
type: number
format: double
nullable: true
description: |
Current ask price.
Requires IEX entitlement. Null if not entitled.
example: 163.0
required:
- ticker
- timestamp
- tngoLast
- prevClose
- volume
example:
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
IEXPrice: &IEXPrice
type: object
description: |
Historical intraday price data in OHLC format from IEX Exchange.
The time period covered by each bar is determined by the resampleFreq parameter.
Volume data is IEX-only and must be explicitly requested using the columns parameter.
properties:
date:
$ref: '../schemas/common.yaml#/DateTime'
description: |
Timestamp for this OHLC bar. Marks the beginning of the time period.
Format: ISO 8601 (RFC 3339)
open:
type: number
format: double
description: Opening price for the time period
example: 154.74
high:
type: number
format: double
description: Highest price during the time period
example: 155.52
low:
type: number
format: double
description: Lowest price during the time period
example: 154.58
close:
type: number
format: double
description: Closing price for the time period
example: 154.76
volume:
type: integer
format: int64
nullable: true
description: |
Number of shares traded on IEX only during the time period.
This field is only included if explicitly requested via the columns parameter
(e.g., ?columns=open,high,low,close,volume)
example: 16102
required:
- date
- open
- high
- low
- close
example:
date: '2019-01-02T14:30:00.000Z'
open: 154.74
high: 155.52
low: 154.58
close: 154.76
volume: 16102

114
openapi/schemas/news-schemas.yaml Normal file
View File

@@ -0,0 +1,114 @@
# News API Schema Definitions
# Reference these using: $ref: '../schemas/news-schemas.yaml#/SchemaName'
NewsArticle: &NewsArticle
type: object
description: A news article with ticker and tag associations
properties:
id:
type: integer
format: int32
description: Unique identifier specific to the news article
example: 28515261
title:
type: string
description: Title of the news article
example: "Apple's CEO sees optimism as trade tension between U.S. and China lessens"
url:
type: string
format: uri
description: URL of the news article
example: "https://www.cnbc.com/2019/01/29/apples-ceo-sees-optimism-as-trade-tension-between-us-and-china-lessens.html"
description:
type: string
description: Long-form description of the news story
example: "Apple CEO Tim Cook told CNBC that trade tensions between the U.S. and China have improved since late December."
publishedDate:
type: string
format: date-time
description: The datetime the news story was published in UTC. Usually reported by the news source, or the time discovered by Tiingo's crawler if not declared.
example: "2019-01-29T22:17:00Z"
crawlDate:
type: string
format: date-time
description: The datetime the news story was added to the database in UTC. Always recorded by Tiingo. Large gaps between crawlDate and publishedDate indicate backfilled articles.
example: "2019-01-29T22:20:01.696871Z"
source:
type: string
description: The domain the news source is from
example: "cnbc.com"
tickers:
type: array
items:
type: string
pattern: '^[A-Z0-9]+$'
description: Tickers mentioned in the news story using Tiingo's proprietary tagging algorithm
example: ["AAPL"]
tags:
type: array
items:
type: string
description: Tags mapped and discovered by Tiingo using Tiingo's proprietary tagging algorithm
example: ["China", "Economic Measures", "Economics", "Markets", "Stock", "Technology"]
required:
- id
- title
- url
- publishedDate
- crawlDate
- source
BulkDownloadFile: &BulkDownloadFile
type: object
description: Metadata for a bulk news download file (institutional clients only)
properties:
id:
type: integer
format: int32
description: Unique identifier specific to the bulk download file. Used to select which file to download.
example: 755
filename:
type: string
description: The filename of the batch file
example: "bulkfile_2019-01-28_2019-01-29.tar.gz"
batchType:
type: string
enum:
- base
- incremental
description: "Describes what kind of batch file this is: 'base' is an entire dump of the data, 'incremental' is a partial dump of the data"
example: "incremental"
startDate:
type: string
format: date-time
description: The start date used to select the News objects to generate the batch file. This is inclusive (publishedDate >= startDate).
example: "2019-01-28T05:00:00Z"
endDate:
type: string
format: date-time
description: The end date used to select the News objects to generate the batch file. This is not inclusive (publishedDate < endDate).
example: "2019-01-29T05:00:00Z"
url:
type: string
format: uri
description: A url to directly download the batch file. NOTE - This url contains your Auth Token and is meant to be a copy/paste url for convenience.
example: "https://api.tiingo.com/tiingo/news/bulk_download/755?token=YOUR_API_TOKEN"
fileSizeUncompressed:
type: integer
format: int64
description: The size of the file in bytes uncompressed
example: 10385878
fileSizeCompressed:
type: integer
format: int64
description: The size of the file in bytes compressed using gzip
example: 3018550
required:
- id
- filename
- batchType
- startDate
- endDate
- url
- fileSizeUncompressed
- fileSizeCompressed

69
openapi/schemas/splits-schemas.yaml Normal file
View File

@@ -0,0 +1,69 @@
# Splits API Schema Definitions
# Reference these using: $ref: '../schemas/splits-schemas.yaml#/SchemaName'
Split: &Split
type: object
description: Split data for a stock, ETF, or mutual fund
properties:
permaTicker:
type: string
description: The Tiingo permaticker (persistent identifier)
example: 'AAPL'
ticker:
$ref: './common.yaml#/Ticker'
exDate:
type: string
format: date
description: >
The ex-date of the split. In the Tiingo EOD Endpoints, this is the date where
"splitFactor" will not be 1.0. This is also the date used for split adjustments
example: '2023-08-25'
splitFrom:
type: number
format: float
description: The prior split ratio
example: 1.0
splitTo:
type: number
format: float
description: >
The new split ratio, i.e. how many shares of "splitTo" are given for each
share of "splitFrom"
example: 2.0
splitFactor:
type: number
format: float
description: >
The ratio of splitTo from splitFrom. Formula: splitFactor = splitTo/splitFrom.
This ratio is helpful in calculating split price adjustments
example: 2.0
splitStatus:
type: string
enum:
- 'a'
- 'c'
description: >
A code representing the status of split: 'a' = Active, 'c' = Cancelled
example: 'a'
required:
- permaTicker
- ticker
- exDate
- splitFrom
- splitTo
- splitFactor
- splitStatus
example:
permaTicker: 'AAPL'
ticker: 'AAPL'
exDate: '2023-08-25'
splitFrom: 1.0
splitTo: 1.04347826
splitFactor: 1.04347826
splitStatus: 'a'
SplitArray: &SplitArray
type: array
description: Array of split data objects
items:
$ref: '#/Split'