mirror of
https://github.com/hydrosquall/tiingo-python.git
synced 2026-01-11 07:14:42 +01:00
feat: Add corporate action endpoints (Dividends, Splits)
Add OpenAPI specifications for corporate events: - Dividend distributions and payment dates - Stock splits and reverse splits 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cameron Yick
214
openapi/paths/dividends.yaml
Normal file
214
openapi/paths/dividends.yaml
Normal file
@@ -0,0 +1,214 @@
|
||||
# Tiingo Dividends API Endpoints
|
||||
# Corporate Actions - Distribution and Yield Endpoints
|
||||
|
||||
distributions-batch: &distributions-batch
|
||||
get:
|
||||
summary: Get batch distribution data
|
||||
description: |
|
||||
Retrieve past, present, and future dividends and distributions for multiple tickers.
|
||||
Returns detailed dividend and distribution data for stocks, ETFs, or mutual funds.
|
||||
The response includes distribution frequency, which is the declared frequency of the
|
||||
distribution that you can use to customize your calculations to determine yield.
|
||||
|
||||
Available for current and future dates. Requires End-of-Day endpoint entitlement.
|
||||
operationId: getBatchDistributions
|
||||
tags:
|
||||
- Corporate Actions
|
||||
parameters:
|
||||
- name: exDate
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
description: |
|
||||
Filter distributions by ex-date. Can be a future date or historical date.
|
||||
If not specified, returns distributions with an ex-date of the current day.
|
||||
Format: YYYY-MM-DD
|
||||
example: '2023-08-25'
|
||||
- $ref: '../parameters/_index.yaml#/TokenParam'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response with array of distribution objects
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '../schemas/dividends-schemas.yaml#/Distribution'
|
||||
examples:
|
||||
multipleDistributions:
|
||||
summary: Multiple distributions for a specific ex-date
|
||||
value:
|
||||
- permaTicker: AAPL
|
||||
ticker: AAPL
|
||||
exDate: '2023-08-25T00:00:00.000Z'
|
||||
paymentDate: '2023-09-07T00:00:00.000Z'
|
||||
recordDate: '2023-08-28T00:00:00.000Z'
|
||||
declarationDate: '2023-07-27T00:00:00.000Z'
|
||||
distribution: 0.24
|
||||
distributionFreqency: q
|
||||
- permaTicker: MSFT
|
||||
ticker: MSFT
|
||||
exDate: '2023-08-25T00:00:00.000Z'
|
||||
paymentDate: '2023-09-21T00:00:00.000Z'
|
||||
recordDate: '2023-08-31T00:00:00.000Z'
|
||||
declarationDate: '2023-07-25T00:00:00.000Z'
|
||||
distribution: 0.68
|
||||
distributionFreqency: q
|
||||
'400':
|
||||
$ref: '../responses/_index.yaml#/BadRequest'
|
||||
'401':
|
||||
$ref: '../responses/_index.yaml#/Unauthorized'
|
||||
'404':
|
||||
$ref: '../responses/_index.yaml#/NotFound'
|
||||
'429':
|
||||
$ref: '../responses/_index.yaml#/TooManyRequests'
|
||||
'500':
|
||||
$ref: '../responses/_index.yaml#/InternalServerError'
|
||||
|
||||
distributions-ticker: &distributions-ticker
|
||||
get:
|
||||
summary: Get distribution data for a specific ticker
|
||||
description: |
|
||||
Retrieve historical distribution timeseries data for a specific ticker.
|
||||
Similar to the batch endpoint, but allows you to specify a ticker to limit the query.
|
||||
Supports stocks, ETFs, and mutual funds.
|
||||
|
||||
Returns full history by default, or can be limited to a date range using
|
||||
startExDate and endExDate parameters.
|
||||
operationId: getTickerDistributions
|
||||
tags:
|
||||
- Corporate Actions
|
||||
parameters:
|
||||
- $ref: '../parameters/_index.yaml#/TickerPathParam'
|
||||
- name: startExDate
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
Start of the ex-date range to query. Format: YYYY-MM-DD
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
example: '2023-01-01'
|
||||
- name: endExDate
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
End of the ex-date range to query. Format: YYYY-MM-DD
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
example: '2024-01-01'
|
||||
- $ref: '../parameters/_index.yaml#/TokenParam'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response with array of distribution objects for the specified ticker
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '../schemas/dividends-schemas.yaml#/Distribution'
|
||||
examples:
|
||||
yearlyDistributions:
|
||||
summary: AAPL quarterly distributions for 2023
|
||||
value:
|
||||
- permaTicker: AAPL
|
||||
ticker: AAPL
|
||||
exDate: '2023-02-10T00:00:00.000Z'
|
||||
paymentDate: '2023-02-23T00:00:00.000Z'
|
||||
recordDate: '2023-02-13T00:00:00.000Z'
|
||||
declarationDate: '2023-01-26T00:00:00.000Z'
|
||||
distribution: 0.22
|
||||
distributionFreqency: q
|
||||
- permaTicker: AAPL
|
||||
ticker: AAPL
|
||||
exDate: '2023-05-12T00:00:00.000Z'
|
||||
paymentDate: '2023-05-25T00:00:00.000Z'
|
||||
recordDate: '2023-05-15T00:00:00.000Z'
|
||||
declarationDate: '2023-04-27T00:00:00.000Z'
|
||||
distribution: 0.22
|
||||
distributionFreqency: q
|
||||
- permaTicker: AAPL
|
||||
ticker: AAPL
|
||||
exDate: '2023-08-11T00:00:00.000Z'
|
||||
paymentDate: '2023-08-24T00:00:00.000Z'
|
||||
recordDate: '2023-08-14T00:00:00.000Z'
|
||||
declarationDate: '2023-07-27T00:00:00.000Z'
|
||||
distribution: 0.24
|
||||
distributionFreqency: q
|
||||
- permaTicker: AAPL
|
||||
ticker: AAPL
|
||||
exDate: '2023-11-10T00:00:00.000Z'
|
||||
paymentDate: '2023-11-23T00:00:00.000Z'
|
||||
recordDate: '2023-11-13T00:00:00.000Z'
|
||||
declarationDate: '2023-10-26T00:00:00.000Z'
|
||||
distribution: 0.24
|
||||
distributionFreqency: q
|
||||
'400':
|
||||
$ref: '../responses/_index.yaml#/BadRequest'
|
||||
'401':
|
||||
$ref: '../responses/_index.yaml#/Unauthorized'
|
||||
'404':
|
||||
$ref: '../responses/_index.yaml#/NotFound'
|
||||
'429':
|
||||
$ref: '../responses/_index.yaml#/TooManyRequests'
|
||||
'500':
|
||||
$ref: '../responses/_index.yaml#/InternalServerError'
|
||||
|
||||
distribution-yield: &distribution-yield
|
||||
get:
|
||||
summary: Get historical yield data for a ticker
|
||||
description: |
|
||||
Retrieve current and historical information about yield data for stocks, ETFs,
|
||||
or mutual funds. Yield data is available for tickers after their End-of-Day
|
||||
price data has been processed.
|
||||
|
||||
Note: Tiingo will continue to add new daily metrics over time. Use the 'columns'
|
||||
parameter to ensure constant output format, even if additional columns are added.
|
||||
operationId: getDistributionYield
|
||||
tags:
|
||||
- Corporate Actions
|
||||
parameters:
|
||||
- $ref: '../parameters/_index.yaml#/TickerPathParam'
|
||||
- name: columns
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: |
|
||||
Comma-separated list of column names to return. This ensures only specified
|
||||
fields are returned in exact order, providing consistent output format across
|
||||
API updates. Example: 'trailingDiv1Y' will always return only that field.
|
||||
example: trailingDiv1Y
|
||||
- $ref: '../parameters/_index.yaml#/TokenParam'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response with array of yield objects
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '../schemas/dividends-schemas.yaml#/DistributionYield'
|
||||
examples:
|
||||
historicalYield:
|
||||
summary: Historical trailing 1-year dividend yield for AAPL
|
||||
value:
|
||||
- date: '2024-01-01T00:00:00.000Z'
|
||||
trailingDiv1Y: '0.92'
|
||||
- date: '2024-01-02T00:00:00.000Z'
|
||||
trailingDiv1Y: '0.92'
|
||||
- date: '2024-01-03T00:00:00.000Z'
|
||||
trailingDiv1Y: '0.92'
|
||||
'400':
|
||||
$ref: '../responses/_index.yaml#/BadRequest'
|
||||
'401':
|
||||
$ref: '../responses/_index.yaml#/Unauthorized'
|
||||
'404':
|
||||
$ref: '../responses/_index.yaml#/NotFound'
|
||||
'429':
|
||||
$ref: '../responses/_index.yaml#/TooManyRequests'
|
||||
'500':
|
||||
$ref: '../responses/_index.yaml#/InternalServerError'
|
||||
144
openapi/paths/splits.yaml
Normal file
144
openapi/paths/splits.yaml
Normal file
@@ -0,0 +1,144 @@
|
||||
# Splits API Endpoint Definitions
|
||||
# Corporate Actions - Splits endpoints for historical and future split data
|
||||
|
||||
splits-batch: &splits-batch
|
||||
get:
|
||||
summary: Get batch split data
|
||||
description: >
|
||||
Get past, present, and future splits for all tickers. Returns detailed split data
|
||||
for stocks, ETFs, and mutual funds. Split status can be either active ("a") or
|
||||
cancelled ("c"). This endpoint is in beta and available to customers with the
|
||||
End-of-Day endpoint entitlement.
|
||||
operationId: getSplitsBatch
|
||||
tags:
|
||||
- Corporate Actions
|
||||
parameters:
|
||||
- $ref: '../parameters/_index.yaml#/TokenParam'
|
||||
- name: exDate
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
description: >
|
||||
The ex-date to filter splits. Returns splits with the specified ex-date.
|
||||
Defaults to current date if not provided
|
||||
example: '2023-08-25'
|
||||
- name: tickers
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: Comma-separated list of tickers to filter results
|
||||
example: 'AAPL,TSLA'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response with array of splits
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/splits-schemas.yaml#/SplitArray'
|
||||
examples:
|
||||
multipleSplits:
|
||||
summary: Multiple splits on a specific date
|
||||
value:
|
||||
- permaTicker: 'AAPL'
|
||||
ticker: 'AAPL'
|
||||
exDate: '2023-08-25'
|
||||
splitFrom: 1.0
|
||||
splitTo: 1.04347826
|
||||
splitFactor: 1.04347826
|
||||
splitStatus: 'a'
|
||||
- permaTicker: 'TSLA'
|
||||
ticker: 'TSLA'
|
||||
exDate: '2023-08-28'
|
||||
splitFrom: 1.0
|
||||
splitTo: 3.0
|
||||
splitFactor: 3.0
|
||||
splitStatus: 'a'
|
||||
'400':
|
||||
$ref: '../responses/_index.yaml#/BadRequest'
|
||||
'401':
|
||||
$ref: '../responses/_index.yaml#/Unauthorized'
|
||||
'404':
|
||||
$ref: '../responses/_index.yaml#/NotFound'
|
||||
'429':
|
||||
$ref: '../responses/_index.yaml#/TooManyRequests'
|
||||
'500':
|
||||
$ref: '../responses/_index.yaml#/InternalServerError'
|
||||
|
||||
splits-ticker: &splits-ticker
|
||||
get:
|
||||
summary: Get split data for specific ticker
|
||||
description: >
|
||||
Get historical and future split timeseries data for a specific ticker.
|
||||
This endpoint allows you to query past and future split data for stocks, ETFs,
|
||||
and mutual funds. Split status can be either active ("a") or cancelled ("c").
|
||||
Use startExDate and endExDate parameters to filter the date range.
|
||||
operationId: getSplitsByTicker
|
||||
tags:
|
||||
- Corporate Actions
|
||||
parameters:
|
||||
- name: ticker
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
pattern: '^[A-Z0-9]+$'
|
||||
description: The stock ticker symbol (e.g., AAPL, CVS, TSLA)
|
||||
example: 'CVS'
|
||||
- $ref: '../parameters/_index.yaml#/TokenParam'
|
||||
- name: startExDate
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
description: >
|
||||
The starting ex-date for historical split timeseries data.
|
||||
Returns splits from this date onward. Defaults to current date if not provided
|
||||
example: '2002-08-25'
|
||||
- name: endExDate
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
format: date
|
||||
description: >
|
||||
The ending ex-date for filtering splits. Returns splits up to this date
|
||||
example: '2023-12-31'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response with array of historical splits
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../schemas/splits-schemas.yaml#/SplitArray'
|
||||
examples:
|
||||
historicalSplits:
|
||||
summary: Historical splits for CVS
|
||||
value:
|
||||
- permaTicker: 'CVS'
|
||||
ticker: 'CVS'
|
||||
exDate: '2002-08-25'
|
||||
splitFrom: 1.0
|
||||
splitTo: 2.0
|
||||
splitFactor: 2.0
|
||||
splitStatus: 'a'
|
||||
- permaTicker: 'CVS'
|
||||
ticker: 'CVS'
|
||||
exDate: '2015-06-01'
|
||||
splitFrom: 1.0
|
||||
splitTo: 1.0
|
||||
splitFactor: 1.0
|
||||
splitStatus: 'c'
|
||||
'400':
|
||||
$ref: '../responses/_index.yaml#/BadRequest'
|
||||
'401':
|
||||
$ref: '../responses/_index.yaml#/Unauthorized'
|
||||
'404':
|
||||
$ref: '../responses/_index.yaml#/NotFound'
|
||||
'429':
|
||||
$ref: '../responses/_index.yaml#/TooManyRequests'
|
||||
'500':
|
||||
$ref: '../responses/_index.yaml#/InternalServerError'
|
||||
92
openapi/schemas/dividends-schemas.yaml
Normal file
92
openapi/schemas/dividends-schemas.yaml
Normal file
@@ -0,0 +1,92 @@
|
||||
# Dividend and Distribution Schemas for Tiingo Corporate Actions API
|
||||
# Reference these using: $ref: '../schemas/dividends-schemas.yaml#/SchemaName'
|
||||
|
||||
Distribution: &Distribution
|
||||
type: object
|
||||
description: Detailed dividend and distribution data for a stock, ETF, or mutual fund
|
||||
properties:
|
||||
permaTicker:
|
||||
type: string
|
||||
description: The Tiingo permaticker
|
||||
example: AAPL
|
||||
ticker:
|
||||
type: string
|
||||
description: Ticker related to the asset
|
||||
example: AAPL
|
||||
exDate:
|
||||
$ref: './common.yaml#/DateTime'
|
||||
description: The ex-date of the distribution. In the Tiingo EOD Endpoints, this is the date where "divCash" will be non-zero. This is also the date used for dividend price adjustments.
|
||||
example: '2023-08-25T00:00:00.000Z'
|
||||
paymentDate:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: The payment date of the distribution
|
||||
example: '2023-09-07T00:00:00.000Z'
|
||||
recordDate:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: The record date of the distribution
|
||||
example: '2023-08-28T00:00:00.000Z'
|
||||
declarationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: The declaration date of the distribution
|
||||
example: '2023-07-27T00:00:00.000Z'
|
||||
distribution:
|
||||
type: number
|
||||
format: float
|
||||
description: The total distribution for the given date
|
||||
example: 0.24
|
||||
distributionFreqency:
|
||||
type: string
|
||||
description: |
|
||||
The frequency associated with this distribution. Frequency codes:
|
||||
- w: Weekly
|
||||
- bm: Bimonthly
|
||||
- m: Monthly
|
||||
- tm: Trimesterly
|
||||
- q: Quarterly
|
||||
- sa: Semiannually
|
||||
- a: Annually
|
||||
- ir: Irregular
|
||||
- f: Final
|
||||
- u: Unspecified
|
||||
- c: Cancelled
|
||||
enum:
|
||||
- w
|
||||
- bm
|
||||
- m
|
||||
- tm
|
||||
- q
|
||||
- sa
|
||||
- a
|
||||
- ir
|
||||
- f
|
||||
- u
|
||||
- c
|
||||
example: q
|
||||
required:
|
||||
- permaTicker
|
||||
- ticker
|
||||
- exDate
|
||||
- distribution
|
||||
- distributionFreqency
|
||||
|
||||
DistributionYield: &DistributionYield
|
||||
type: object
|
||||
description: Historical yield metrics for a ticker's dividend distributions
|
||||
properties:
|
||||
date:
|
||||
$ref: './common.yaml#/DateTime'
|
||||
description: Date associated with the yield
|
||||
example: '2024-01-01T00:00:00.000Z'
|
||||
trailingDiv1Y:
|
||||
type: string
|
||||
description: The trailing distribution yield for the asset based on the previous 1 year of distributions
|
||||
example: '0.92'
|
||||
required:
|
||||
- date
|
||||
- trailingDiv1Y
|
||||
69
openapi/schemas/splits-schemas.yaml
Normal file
69
openapi/schemas/splits-schemas.yaml
Normal file
@@ -0,0 +1,69 @@
|
||||
# Splits API Schema Definitions
|
||||
# Reference these using: $ref: '../schemas/splits-schemas.yaml#/SchemaName'
|
||||
|
||||
Split: &Split
|
||||
type: object
|
||||
description: Split data for a stock, ETF, or mutual fund
|
||||
properties:
|
||||
permaTicker:
|
||||
type: string
|
||||
description: The Tiingo permaticker (persistent identifier)
|
||||
example: 'AAPL'
|
||||
ticker:
|
||||
$ref: './common.yaml#/Ticker'
|
||||
exDate:
|
||||
type: string
|
||||
format: date
|
||||
description: >
|
||||
The ex-date of the split. In the Tiingo EOD Endpoints, this is the date where
|
||||
"splitFactor" will not be 1.0. This is also the date used for split adjustments
|
||||
example: '2023-08-25'
|
||||
splitFrom:
|
||||
type: number
|
||||
format: float
|
||||
description: The prior split ratio
|
||||
example: 1.0
|
||||
splitTo:
|
||||
type: number
|
||||
format: float
|
||||
description: >
|
||||
The new split ratio, i.e. how many shares of "splitTo" are given for each
|
||||
share of "splitFrom"
|
||||
example: 2.0
|
||||
splitFactor:
|
||||
type: number
|
||||
format: float
|
||||
description: >
|
||||
The ratio of splitTo from splitFrom. Formula: splitFactor = splitTo/splitFrom.
|
||||
This ratio is helpful in calculating split price adjustments
|
||||
example: 2.0
|
||||
splitStatus:
|
||||
type: string
|
||||
enum:
|
||||
- 'a'
|
||||
- 'c'
|
||||
description: >
|
||||
A code representing the status of split: 'a' = Active, 'c' = Cancelled
|
||||
example: 'a'
|
||||
required:
|
||||
- permaTicker
|
||||
- ticker
|
||||
- exDate
|
||||
- splitFrom
|
||||
- splitTo
|
||||
- splitFactor
|
||||
- splitStatus
|
||||
example:
|
||||
permaTicker: 'AAPL'
|
||||
ticker: 'AAPL'
|
||||
exDate: '2023-08-25'
|
||||
splitFrom: 1.0
|
||||
splitTo: 1.04347826
|
||||
splitFactor: 1.04347826
|
||||
splitStatus: 'a'
|
||||
|
||||
SplitArray: &SplitArray
|
||||
type: array
|
||||
description: Array of split data objects
|
||||
items:
|
||||
$ref: '#/Split'
|
||||
Reference in New Issue
Block a user