From 267f6aca2ed7d9d9d1c54f44e763b84dedc3e7d4 Mon Sep 17 00:00:00 2001 From: Cameron Yick Date: Sat, 13 Dec 2025 22:43:05 -0500 Subject: [PATCH] feat: Add OpenAPI specifications for Tiingo API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .beads/issues.jsonl | 22 ++ openapi/openapi.yaml | 179 +++++++++++ openapi/parameters/_index.yaml | 49 +++ openapi/paths/crypto.yaml | 271 ++++++++++++++++ openapi/paths/dividends.yaml | 214 +++++++++++++ openapi/paths/end-of-day.yaml | 191 ++++++++++++ openapi/paths/forex.yaml | 200 ++++++++++++ openapi/paths/fundamentals.yaml | 360 ++++++++++++++++++++++ openapi/paths/funds.yaml | 132 ++++++++ openapi/paths/iex.yaml | 269 ++++++++++++++++ openapi/paths/news.yaml | 212 +++++++++++++ openapi/paths/splits.yaml | 144 +++++++++ openapi/responses/_index.yaml | 34 ++ openapi/schemas/_index.yaml | 168 ++++++++++ openapi/schemas/common.yaml | 39 +++ openapi/schemas/crypto-schemas.yaml | 303 ++++++++++++++++++ openapi/schemas/dividends-schemas.yaml | 92 ++++++ openapi/schemas/eod-schemas.yaml | 119 +++++++ openapi/schemas/forex-schemas.yaml | 106 +++++++ openapi/schemas/fundamentals-schemas.yaml | 255 +++++++++++++++ openapi/schemas/funds-schemas.yaml | 235 ++++++++++++++ openapi/schemas/iex-schemas.yaml | 220 +++++++++++++ openapi/schemas/news-schemas.yaml | 114 +++++++ openapi/schemas/splits-schemas.yaml | 69 +++++ 24 files changed, 3997 insertions(+) create mode 100644 .beads/issues.jsonl create mode 100644 openapi/openapi.yaml create mode 100644 openapi/parameters/_index.yaml create mode 100644 openapi/paths/crypto.yaml create mode 100644 openapi/paths/dividends.yaml create mode 100644 openapi/paths/end-of-day.yaml create mode 100644 openapi/paths/forex.yaml create mode 100644 openapi/paths/fundamentals.yaml create mode 100644 openapi/paths/funds.yaml create mode 100644 openapi/paths/iex.yaml create mode 100644 openapi/paths/news.yaml create mode 100644 openapi/paths/splits.yaml create mode 100644 openapi/responses/_index.yaml create mode 100644 openapi/schemas/_index.yaml create mode 100644 openapi/schemas/common.yaml create mode 100644 openapi/schemas/crypto-schemas.yaml create mode 100644 openapi/schemas/dividends-schemas.yaml create mode 100644 openapi/schemas/eod-schemas.yaml create mode 100644 openapi/schemas/forex-schemas.yaml create mode 100644 openapi/schemas/fundamentals-schemas.yaml create mode 100644 openapi/schemas/funds-schemas.yaml create mode 100644 openapi/schemas/iex-schemas.yaml create mode 100644 openapi/schemas/news-schemas.yaml create mode 100644 openapi/schemas/splits-schemas.yaml diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl new file mode 100644 index 0000000..58eb94d --- /dev/null +++ b/.beads/issues.jsonl @@ -0,0 +1,22 @@ +{"id":"tiingo-python-3ra","title":"Create main openapi.yaml index file","description":"Create openapi/openapi.yaml main index file with $ref references to all 9 path files, common components (parameters, schemas, responses), servers config, and security schemes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.246571-05:00","updated_at":"2025-12-13T21:12:36.8245-05:00","closed_at":"2025-12-13T21:12:36.8245-05:00","dependencies":[{"issue_id":"tiingo-python-3ra","depends_on_id":"tiingo-python-3ui","type":"blocks","created_at":"2025-12-13T18:33:53.94051-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-3ui","title":"Create schemas index file","description":"Create openapi/schemas/_index.yaml that references all schema files: common.yaml, eod-schemas.yaml, news-schemas.yaml, crypto-schemas.yaml, forex-schemas.yaml, iex-schemas.yaml, fundamentals-schemas.yaml, funds-schemas.yaml, dividends-schemas.yaml, splits-schemas.yaml","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:17.925327-05:00","updated_at":"2025-12-13T20:12:10.346339-05:00","closed_at":"2025-12-13T20:12:10.346339-05:00","dependencies":[{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-db3","type":"blocks","created_at":"2025-12-13T18:33:53.617742-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-hv6","type":"blocks","created_at":"2025-12-13T18:33:53.647897-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-qui","type":"blocks","created_at":"2025-12-13T18:33:53.6761-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-8g5","type":"blocks","created_at":"2025-12-13T18:33:53.704791-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-r9g","type":"blocks","created_at":"2025-12-13T18:33:53.733829-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-zxc","type":"blocks","created_at":"2025-12-13T18:33:53.763228-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-b3u","type":"blocks","created_at":"2025-12-13T18:33:53.795726-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-j56","type":"blocks","created_at":"2025-12-13T18:33:53.827326-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-yfj","type":"blocks","created_at":"2025-12-13T18:33:53.857293-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-4bk","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.391477-05:00","updated_at":"2025-12-13T18:14:16.391477-05:00"} +{"id":"tiingo-python-5bx","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.48674-05:00","updated_at":"2025-12-13T18:14:16.48674-05:00"} +{"id":"tiingo-python-8g5","title":"Generate OpenAPI spec for Forex endpoints","description":"Read docs/api_extracted/forex.md and create openapi/paths/forex.yaml and openapi/schemas/forex-schemas.yaml. Include endpoints: /tiingo/fx/{ticker}, /tiingo/fx/top, /tiingo/fx/{ticker}/prices. Schemas: ForexTopOfBook, ForexPrice","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:22.828837-05:00","updated_at":"2025-12-13T19:39:23.801863-05:00","closed_at":"2025-12-13T19:39:23.801863-05:00","dependencies":[{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:44.295421-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:44.335832-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:44.362837-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-aeb","title":"Validate complete OpenAPI specification","description":"Run OpenAPI validation tools to ensure all $ref references resolve correctly, all schemas are valid, and the specification passes OpenAPI 3.0.3 validation. Fix any issues found.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:19.12959-05:00","updated_at":"2025-12-13T22:30:08.827714-05:00","closed_at":"2025-12-13T22:30:08.827714-05:00","dependencies":[{"issue_id":"tiingo-python-aeb","depends_on_id":"tiingo-python-3ra","type":"blocks","created_at":"2025-12-13T18:33:54.021641-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-b3u","title":"Generate OpenAPI spec for Mutual Fund/ETF Fees endpoints","description":"Read docs/api_extracted/mutual-fund-etf-fees.md and create openapi/paths/funds.yaml and openapi/schemas/funds-schemas.yaml. Include endpoints: /tiingo/funds/{ticker}, /tiingo/funds/{ticker}/metrics. Schemas: FundOverview, FundMetrics","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.299961-05:00","updated_at":"2025-12-13T19:39:23.803006-05:00","closed_at":"2025-12-13T19:39:23.803006-05:00","dependencies":[{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.465575-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.503921-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.536194-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-db3","title":"Generate OpenAPI spec for End-of-Day endpoints","description":"Read docs/api_extracted/end-of-day.md and create openapi/paths/end-of-day.yaml and openapi/schemas/eod-schemas.yaml. Include endpoints: /tiingo/daily/{ticker}/prices, /tiingo/daily/{ticker}. Schemas: PriceData, TickerMetadata","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.300561-05:00","updated_at":"2025-12-13T19:39:23.799437-05:00","closed_at":"2025-12-13T19:39:23.799437-05:00","dependencies":[{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.019056-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.048754-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.087225-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-gco","title":"Create common OpenAPI parameters file","description":"Create openapi/parameters/_index.yaml with reusable parameters: TokenParam, TickerPathParam, StartDateParam, EndDateParam, FormatParam","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.019038-05:00","updated_at":"2025-12-13T19:10:56.633329-05:00","closed_at":"2025-12-13T19:10:56.633329-05:00"} +{"id":"tiingo-python-hv6","title":"Generate OpenAPI spec for News endpoints","description":"Read docs/api_extracted/news.md and create openapi/paths/news.yaml and openapi/schemas/news-schemas.yaml. Include endpoints: /tiingo/news, /tiingo/news/bulk_download, /tiingo/news/bulk_download/{id}. Schemas: NewsArticle, BulkDownloadFile","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.43936-05:00","updated_at":"2025-12-13T19:39:23.800886-05:00","closed_at":"2025-12-13T19:39:23.800886-05:00","dependencies":[{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.51446-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.547333-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.577716-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-j56","title":"Generate OpenAPI spec for Dividends endpoints","description":"Read docs/api_extracted/dividends.md and create openapi/paths/dividends.yaml and openapi/schemas/dividends-schemas.yaml. Include endpoints: /tiingo/corporate-actions/distributions, /tiingo/corporate-actions/{ticker}/distributions, /tiingo/corporate-actions/{ticker}/distribution-yield. Schemas: Distribution, DistributionYield","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.537928-05:00","updated_at":"2025-12-13T19:39:23.803357-05:00","closed_at":"2025-12-13T19:39:23.803357-05:00","dependencies":[{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.916691-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.949027-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.979509-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-jyg","title":"Create common OpenAPI responses file","description":"Create openapi/responses/_index.yaml with standard error responses (400, 401, 404, 429, 500) using ErrorResponse schema","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.102764-05:00","updated_at":"2025-12-13T19:10:56.634733-05:00","closed_at":"2025-12-13T19:10:56.634733-05:00"} +{"id":"tiingo-python-kf1","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.295251-05:00","updated_at":"2025-12-13T18:14:16.295251-05:00"} +{"id":"tiingo-python-oy5","title":"Create common OpenAPI schemas file","description":"Create openapi/schemas/common.yaml with reusable schemas: Date (YYYY-MM-DD), DateTime (ISO 8601), Ticker (string pattern), Currency, ErrorResponse","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.186823-05:00","updated_at":"2025-12-13T19:10:56.635466-05:00","closed_at":"2025-12-13T19:10:56.635466-05:00"} +{"id":"tiingo-python-qui","title":"Generate OpenAPI spec for Crypto endpoints","description":"Read docs/api_extracted/crypto.md and create openapi/paths/crypto.yaml and openapi/schemas/crypto-schemas.yaml. Include endpoints: /tiingo/crypto/prices, /tiingo/crypto, /tiingo/crypto/top (deprecated). Schemas: CryptoPrice, CryptoMetadata, CryptoTopOfBook","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.611042-05:00","updated_at":"2025-12-13T19:39:23.801412-05:00","closed_at":"2025-12-13T19:39:23.801412-05:00","dependencies":[{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.878154-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.906201-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.935488-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-r9g","title":"Generate OpenAPI spec for IEX endpoints","description":"Read docs/api_extracted/iex.md and create openapi/paths/iex.yaml and openapi/schemas/iex-schemas.yaml. Include endpoints: /iex, /iex/{ticker}, /iex/{ticker}/prices. Schemas: IEXTopOfBook, IEXPrice","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:22.930732-05:00","updated_at":"2025-12-13T19:39:23.802213-05:00","closed_at":"2025-12-13T19:39:23.802213-05:00","dependencies":[{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:44.661321-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:44.692337-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:44.72001-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-rse","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.64347-05:00","updated_at":"2025-12-13T18:14:16.64347-05:00"} +{"id":"tiingo-python-tsp","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.300538-05:00","updated_at":"2025-12-13T18:14:16.300538-05:00"} +{"id":"tiingo-python-wm4","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.759112-05:00","updated_at":"2025-12-13T18:14:16.759112-05:00"} +{"id":"tiingo-python-y7a","title":"Generate modular OpenAPI 3.0 specification for Tiingo API","description":"Create a complete, modular OpenAPI 3.0.3 specification for all 9 Tiingo REST API endpoint categories. The spec will use a maintainable file structure with separate files for paths, schemas, parameters, and responses, all referenced via the main openapi.yaml index file.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-13T18:14:33.229701-05:00","updated_at":"2025-12-13T22:38:59.777612-05:00","closed_at":"2025-12-13T22:38:59.777612-05:00"} +{"id":"tiingo-python-yfj","title":"Generate OpenAPI spec for Splits endpoints","description":"Read docs/api_extracted/splits.md and create openapi/paths/splits.yaml and openapi/schemas/splits-schemas.yaml. Include endpoints: /tiingo/corporate-actions/splits, /tiingo/corporate-actions/{ticker}/splits. Schemas: Split","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.708985-05:00","updated_at":"2025-12-13T19:39:23.80368-05:00","closed_at":"2025-12-13T19:39:23.80368-05:00","dependencies":[{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:46.383795-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:46.412601-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:46.441969-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-zxc","title":"Generate OpenAPI spec for Fundamentals endpoints","description":"Read docs/api_extracted/fundamentals.md and create openapi/paths/fundamentals.yaml and openapi/schemas/fundamentals-schemas.yaml. Include endpoints: /tiingo/fundamentals/definitions, /tiingo/fundamentals/{ticker}/statements, /tiingo/fundamentals/{ticker}/daily, /tiingo/fundamentals/meta. Schemas: FundamentalDefinition, FinancialStatement, DailyMetric, FundamentalMeta","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:23.024124-05:00","updated_at":"2025-12-13T19:39:23.802546-05:00","closed_at":"2025-12-13T19:39:23.802546-05:00","dependencies":[{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.098824-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.138032-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.176957-05:00","created_by":"daemon"}]} diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 0000000..3d947b7 --- /dev/null +++ b/openapi/openapi.yaml @@ -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" diff --git a/openapi/parameters/_index.yaml b/openapi/parameters/_index.yaml new file mode 100644 index 0000000..fa7c144 --- /dev/null +++ b/openapi/parameters/_index.yaml @@ -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) diff --git a/openapi/paths/crypto.yaml b/openapi/paths/crypto.yaml new file mode 100644 index 0000000..96e4cd3 --- /dev/null +++ b/openapi/paths/crypto.yaml @@ -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' diff --git a/openapi/paths/dividends.yaml b/openapi/paths/dividends.yaml new file mode 100644 index 0000000..bbb799e --- /dev/null +++ b/openapi/paths/dividends.yaml @@ -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' diff --git a/openapi/paths/end-of-day.yaml b/openapi/paths/end-of-day.yaml new file mode 100644 index 0000000..c618a45 --- /dev/null +++ b/openapi/paths/end-of-day.yaml @@ -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' diff --git a/openapi/paths/forex.yaml b/openapi/paths/forex.yaml new file mode 100644 index 0000000..58453ad --- /dev/null +++ b/openapi/paths/forex.yaml @@ -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' diff --git a/openapi/paths/fundamentals.yaml b/openapi/paths/fundamentals.yaml new file mode 100644 index 0000000..3d113a8 --- /dev/null +++ b/openapi/paths/fundamentals.yaml @@ -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' diff --git a/openapi/paths/funds.yaml b/openapi/paths/funds.yaml new file mode 100644 index 0000000..a496765 --- /dev/null +++ b/openapi/paths/funds.yaml @@ -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' diff --git a/openapi/paths/iex.yaml b/openapi/paths/iex.yaml new file mode 100644 index 0000000..582c858 --- /dev/null +++ b/openapi/paths/iex.yaml @@ -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' diff --git a/openapi/paths/news.yaml b/openapi/paths/news.yaml new file mode 100644 index 0000000..f5eb155 --- /dev/null +++ b/openapi/paths/news.yaml @@ -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' diff --git a/openapi/paths/splits.yaml b/openapi/paths/splits.yaml new file mode 100644 index 0000000..9d3519b --- /dev/null +++ b/openapi/paths/splits.yaml @@ -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' diff --git a/openapi/responses/_index.yaml b/openapi/responses/_index.yaml new file mode 100644 index 0000000..7bb652b --- /dev/null +++ b/openapi/responses/_index.yaml @@ -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' diff --git a/openapi/schemas/_index.yaml b/openapi/schemas/_index.yaml new file mode 100644 index 0000000..2742ec8 --- /dev/null +++ b/openapi/schemas/_index.yaml @@ -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' diff --git a/openapi/schemas/common.yaml b/openapi/schemas/common.yaml new file mode 100644 index 0000000..5bdaf49 --- /dev/null +++ b/openapi/schemas/common.yaml @@ -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" diff --git a/openapi/schemas/crypto-schemas.yaml b/openapi/schemas/crypto-schemas.yaml new file mode 100644 index 0000000..6ba3d60 --- /dev/null +++ b/openapi/schemas/crypto-schemas.yaml @@ -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 diff --git a/openapi/schemas/dividends-schemas.yaml b/openapi/schemas/dividends-schemas.yaml new file mode 100644 index 0000000..42907f3 --- /dev/null +++ b/openapi/schemas/dividends-schemas.yaml @@ -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 diff --git a/openapi/schemas/eod-schemas.yaml b/openapi/schemas/eod-schemas.yaml new file mode 100644 index 0000000..1c123a3 --- /dev/null +++ b/openapi/schemas/eod-schemas.yaml @@ -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 diff --git a/openapi/schemas/forex-schemas.yaml b/openapi/schemas/forex-schemas.yaml new file mode 100644 index 0000000..47496e3 --- /dev/null +++ b/openapi/schemas/forex-schemas.yaml @@ -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 diff --git a/openapi/schemas/fundamentals-schemas.yaml b/openapi/schemas/fundamentals-schemas.yaml new file mode 100644 index 0000000..d3fc938 --- /dev/null +++ b/openapi/schemas/fundamentals-schemas.yaml @@ -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." diff --git a/openapi/schemas/funds-schemas.yaml b/openapi/schemas/funds-schemas.yaml new file mode 100644 index 0000000..0dfd1e6 --- /dev/null +++ b/openapi/schemas/funds-schemas.yaml @@ -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 diff --git a/openapi/schemas/iex-schemas.yaml b/openapi/schemas/iex-schemas.yaml new file mode 100644 index 0000000..6aa7f5b --- /dev/null +++ b/openapi/schemas/iex-schemas.yaml @@ -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 diff --git a/openapi/schemas/news-schemas.yaml b/openapi/schemas/news-schemas.yaml new file mode 100644 index 0000000..680a462 --- /dev/null +++ b/openapi/schemas/news-schemas.yaml @@ -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 diff --git a/openapi/schemas/splits-schemas.yaml b/openapi/schemas/splits-schemas.yaml new file mode 100644 index 0000000..664343f --- /dev/null +++ b/openapi/schemas/splits-schemas.yaml @@ -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'