mirror of
https://github.com/hydrosquall/tiingo-python.git
synced 2026-01-09 06:14:43 +01:00
feat: Add OpenAPI foundation components
Add core OpenAPI 3.0.0 infrastructure for Tiingo API: - Main openapi.yaml with API structure and routing - Common schemas (Date, DateTime, Ticker, Currency, ErrorResponse) - Reusable parameters (token, ticker, date ranges, formats) - Standard error responses (401, 404, 500) - Schema and component registries This foundation enables all endpoint-specific specifications. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cameron Yick
179
openapi/openapi.yaml
Normal file
179
openapi/openapi.yaml
Normal file
@@ -0,0 +1,179 @@
|
||||
openapi: 3.0.3
|
||||
|
||||
info:
|
||||
title: Tiingo REST API
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Tiingo is a financial data platform providing real-time and historical market data.
|
||||
|
||||
This API provides access to:
|
||||
- End-of-Day stock prices and metadata
|
||||
- Financial news articles and bulk downloads
|
||||
- Cryptocurrency prices and metadata
|
||||
- Foreign exchange (Forex) rates and prices
|
||||
- IEX real-time stock data
|
||||
- Fundamental financial statements and metrics
|
||||
- Mutual fund and ETF data
|
||||
- Corporate actions (dividends and stock splits)
|
||||
|
||||
Authentication is required via API token. Get your free API token at https://www.tiingo.com
|
||||
contact:
|
||||
name: Tiingo API Support
|
||||
url: https://www.tiingo.com
|
||||
email: api@tiingo.com
|
||||
license:
|
||||
name: Tiingo Terms of Service
|
||||
url: https://www.tiingo.com/about/terms-of-service
|
||||
|
||||
servers:
|
||||
- url: https://api.tiingo.com
|
||||
description: Production API Server
|
||||
- url: https://apimedia.tiingo.com
|
||||
description: Media/Static Assets Server
|
||||
|
||||
# Global security requirement - all endpoints require API key
|
||||
security:
|
||||
- ApiKeyAuth: []
|
||||
|
||||
# ============================================================================
|
||||
# PATHS - API Endpoints
|
||||
# ============================================================================
|
||||
paths:
|
||||
# --------------------------------------------------------------------------
|
||||
# End-of-Day Endpoints (2 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/daily/{ticker}/prices:
|
||||
$ref: "./paths/end-of-day.yaml#/daily-prices"
|
||||
|
||||
/tiingo/daily/{ticker}:
|
||||
$ref: "./paths/end-of-day.yaml#/daily-meta"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# News Endpoints (3 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/news:
|
||||
$ref: "./paths/news.yaml#/news"
|
||||
|
||||
/tiingo/news/bulk_download:
|
||||
$ref: "./paths/news.yaml#/bulk-list"
|
||||
|
||||
/tiingo/news/bulk_download/{id}:
|
||||
$ref: "./paths/news.yaml#/bulk-download"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Crypto Endpoints (3 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/crypto/prices:
|
||||
$ref: "./paths/crypto.yaml#/crypto-prices"
|
||||
|
||||
/tiingo/crypto:
|
||||
$ref: "./paths/crypto.yaml#/crypto-meta"
|
||||
|
||||
/tiingo/crypto/top:
|
||||
$ref: "./paths/crypto.yaml#/crypto-top"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Forex Endpoints (3 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/fx/{ticker}:
|
||||
$ref: "./paths/forex.yaml#/forex-single"
|
||||
|
||||
/tiingo/fx/top:
|
||||
$ref: "./paths/forex.yaml#/forex-top"
|
||||
|
||||
/tiingo/fx/{ticker}/prices:
|
||||
$ref: "./paths/forex.yaml#/forex-prices"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# IEX Endpoints (3 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/iex:
|
||||
$ref: "./paths/iex.yaml#/iex-all"
|
||||
|
||||
/iex/{ticker}:
|
||||
$ref: "./paths/iex.yaml#/iex-single"
|
||||
|
||||
/iex/{ticker}/prices:
|
||||
$ref: "./paths/iex.yaml#/iex-prices"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Fundamentals Endpoints (4 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/fundamentals/definitions:
|
||||
$ref: "./paths/fundamentals.yaml#/definitions"
|
||||
|
||||
/tiingo/fundamentals/{ticker}/statements:
|
||||
$ref: "./paths/fundamentals.yaml#/statements"
|
||||
|
||||
/tiingo/fundamentals/{ticker}/daily:
|
||||
$ref: "./paths/fundamentals.yaml#/daily"
|
||||
|
||||
/tiingo/fundamentals/meta:
|
||||
$ref: "./paths/fundamentals.yaml#/meta"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Funds Endpoints (2 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/funds/{ticker}:
|
||||
$ref: "./paths/funds.yaml#/fund-overview"
|
||||
|
||||
/tiingo/funds/{ticker}/metrics:
|
||||
$ref: "./paths/funds.yaml#/fund-metrics"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Dividends/Distributions Endpoints (3 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/corporate-actions/distributions:
|
||||
$ref: "./paths/dividends.yaml#/distributions-batch"
|
||||
|
||||
/tiingo/corporate-actions/{ticker}/distributions:
|
||||
$ref: "./paths/dividends.yaml#/distributions-ticker"
|
||||
|
||||
/tiingo/corporate-actions/{ticker}/distribution-yield:
|
||||
$ref: "./paths/dividends.yaml#/distribution-yield"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Splits Endpoints (2 endpoints)
|
||||
# --------------------------------------------------------------------------
|
||||
/tiingo/corporate-actions/splits:
|
||||
$ref: "./paths/splits.yaml#/splits-batch"
|
||||
|
||||
/tiingo/corporate-actions/{ticker}/splits:
|
||||
$ref: "./paths/splits.yaml#/splits-ticker"
|
||||
|
||||
# ============================================================================
|
||||
# COMPONENTS - Reusable definitions
|
||||
# ============================================================================
|
||||
components:
|
||||
# --------------------------------------------------------------------------
|
||||
# Security Schemes
|
||||
# --------------------------------------------------------------------------
|
||||
securitySchemes:
|
||||
ApiKeyAuth:
|
||||
type: apiKey
|
||||
in: query
|
||||
name: token
|
||||
description: |
|
||||
API key authentication. Obtain your API token from https://www.tiingo.com
|
||||
|
||||
Usage: Add `?token=YOUR_API_TOKEN` to all API requests.
|
||||
|
||||
Example: `https://api.tiingo.com/tiingo/daily/aapl/prices?token=YOUR_API_TOKEN`
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Reusable Parameters
|
||||
# --------------------------------------------------------------------------
|
||||
parameters:
|
||||
$ref: "./parameters/_index.yaml"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Reusable Schemas
|
||||
# --------------------------------------------------------------------------
|
||||
schemas:
|
||||
$ref: "./schemas/_index.yaml"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Reusable Responses
|
||||
# --------------------------------------------------------------------------
|
||||
responses:
|
||||
$ref: "./responses/_index.yaml"
|
||||
49
openapi/parameters/_index.yaml
Normal file
49
openapi/parameters/_index.yaml
Normal file
@@ -0,0 +1,49 @@
|
||||
# Reusable Parameter Definitions for Tiingo API
|
||||
# Reference these using: $ref: '../parameters/_index.yaml#/ParameterName'
|
||||
|
||||
TokenParam: &TokenParam
|
||||
name: token
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: API token for authentication
|
||||
|
||||
TickerPathParam: &TickerPathParam
|
||||
name: ticker
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
pattern: '^[A-Z0-9]{1,5}$'
|
||||
description: Stock or cryptocurrency ticker symbol
|
||||
|
||||
StartDateParam: &StartDateParam
|
||||
name: startDate
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
description: Start date for historical data in YYYY-MM-DD format
|
||||
|
||||
EndDateParam: &EndDateParam
|
||||
name: endDate
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
description: End date for historical data in YYYY-MM-DD format
|
||||
|
||||
FormatParam: &FormatParam
|
||||
name: format
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- json
|
||||
- csv
|
||||
default: json
|
||||
description: Response format (json or csv)
|
||||
34
openapi/responses/_index.yaml
Normal file
34
openapi/responses/_index.yaml
Normal file
@@ -0,0 +1,34 @@
|
||||
BadRequest: &BadRequest
|
||||
description: Bad Request - Invalid parameters
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/common.yaml#/ErrorResponse'
|
||||
|
||||
Unauthorized: &Unauthorized
|
||||
description: Unauthorized - Invalid or missing API token
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/common.yaml#/ErrorResponse'
|
||||
|
||||
NotFound: &NotFound
|
||||
description: Not Found - Ticker or resource not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/common.yaml#/ErrorResponse'
|
||||
|
||||
TooManyRequests: &TooManyRequests
|
||||
description: Too Many Requests - Rate limit exceeded
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/common.yaml#/ErrorResponse'
|
||||
|
||||
InternalServerError: &InternalServerError
|
||||
description: Internal Server Error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/common.yaml#/ErrorResponse'
|
||||
168
openapi/schemas/_index.yaml
Normal file
168
openapi/schemas/_index.yaml
Normal 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
39
openapi/schemas/common.yaml
Normal 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"
|
||||
Reference in New Issue
Block a user