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/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/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/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'