Corporate actions

stocks publishes the corporate actions of the listings it carries: forward and reverse splits, cash dividends with their ex, record and payment dates, symbol changes, mergers, spin-offs and the rest, from 2016 on. New actions are added with the nightly bars.

The bars themselves are never rewritten: they are stored as traded. An adjusted series is computed from the actions only when a bars query asks for one with adjust=.

Query

curl -sD - "https://getmarkethistory.com/query/v1/corporate-actions?symbol=AAPL&start=2020-08-01&end=2020-09-30" \
  -H "Authorization: Bearer $MARKET_HISTORY_KEY"

from markethistory import Client

mh = Client()  # reads MARKET_HISTORY_KEY

actions = mh.corporate_actions("AAPL", start="2020-08-01", end="2020-09-30")
[(a["type"], a["ex_date"], a["rate"]) for a in actions]

import json
import os

import requests

url = "https://getmarkethistory.com/query/v1/corporate-actions"
params = {"symbol": "AAPL", "start": "2020-08-01", "end": "2020-09-30"}
headers = {"Authorization": f"Bearer {os.environ['MARKET_HISTORY_KEY']}"}

rows = []
while True:
    r = requests.get(url, params=params, headers=headers, timeout=60)
    r.raise_for_status()  # see /docs/errors for what each status means
    rows += [json.loads(line) for line in r.text.splitlines() if line]
    print(r.headers["X-Row-Count"], "rows,", r.headers["X-Bars-Charged"], "bars")
    if "X-Next-Cursor" not in r.headers:
        break
    params["cursor"] = r.headers["X-Next-Cursor"]

HTTP/2 200
content-type: application/x-ndjson
x-row-count: 2
x-bars-charged: 0

{"cusip":"037833100","due_bill_redemption_date":null,"ex_date":"2020-08-07","extra":null,"foreign":false,"id":"5f2c…","new_rate":null,"old_rate":null,"payable_date":"2020-08-13","process_date":"2020-08-07","rate":0.82,"record_date":"2020-08-10","special":false,"symbol":"AAPL","type":"cash_dividends"}
{"cusip":"037833100","due_bill_redemption_date":null,"ex_date":"2020-08-31","extra":null,"foreign":null,"id":"5f4d…","new_rate":4.0,"old_rate":1.0,"payable_date":"2020-08-28","process_date":"2020-08-31","rate":4.0,"record_date":"2020-08-24","special":null,"symbol":"AAPL","type":"forward_splits"}

Shape and headers as served; the values are illustrative, not copied from a response.

Parameter	Meaning
`symbol`	One or more tickers, comma-separated (at most 50). Required.
`source`	Optional: `stocks`, the only source with corporate actions.
`start`, `end`	Date range, inclusive, on `ex_date` (or `process_date` when the action has no ex-date). Default: all of it.
`format`	`jsonl` (default), `csv`, `json`, `parquet` or `arrow`. `mbt1` is bars only.

Rows come by symbol in the order asked, then by date. There is no paging: a ticker has tens of rows. A ticker with no actions returns no rows.

Columns

Column	Type	Meaning
`type`	string	what happened; see below
`symbol`	string	the ticker whose bars the action affects
`id`	string	a stable identifier of the action
`ex_date`	date	the first session that trades without the dividend, or on the new share count
`record_date`	date	holders of record on this date receive it
`payable_date`	date	the payment date
`process_date`	date	when the action was processed; the only date of most symbol changes and mergers
`due_bill_redemption_date`	date	when due bills on a split or large dividend settle
`cusip`	string	the security’s CUSIP
`rate`	float	a cash dividend’s amount per share, in the price’s currency; for a split, `new_rate / old_rate`
`old_rate`, `new_rate`	float	the two legs of a split: AAPL’s 4-for-1 is `old_rate` 1, `new_rate` 4; a 1-for-10 reverse split is 10 and 1
`special`, `foreign`	bool	a special (non-recurring) dividend; a dividend from a foreign issuer
`extra`	string	a JSON object with the action’s other fields, such as the other ticker of a pair

On some older split rows rate is empty: use new_rate / old_rate, as adjust= does. A dividend amount is the one declared for its ex-date, in the shares of that date: it is not restated for later splits.

type is one of forward_splits, reverse_splits, cash_dividends, stock_dividends, unit_splits, spin_offs, name_changes, cash_mergers, stock_mergers, stock_and_cash_mergers, rights_distributions, capital_gains_distributions, reorganizations, partial_calls, redemptions or worthless_removals; new types may appear. A symbol change, merger, spin-off or unit split names two tickers. Its row is filed under the one that already has bars (the old ticker, the company acquired, the parent) and the other one is in extra (new_symbol, acquirer_symbol, …).

Adjusted bars

Add adjust= to a bars query on stocks:

curl -s "https://getmarkethistory.com/query/v1/bars/stocks/AAPL/1d?start=2020-08-24&end=2020-09-04&adjust=splits" \
  -H "Authorization: Bearer $MH_KEY"

`adjust`	Prices
`raw`	as traded. The default.
`splits`	adjusted for forward and reverse splits.
`all`	adjusted for splits and cash dividends (total-return view).

Other sources answer 400 to adjust=splits or all, and so does the free sample. The rules are exact:

Which actions. splits applies forward_splits and reverse_splits; all also applies cash_dividends. Spin-offs, stock dividends and mergers are never applied. An action whose ex_date is after today (New York) is announced, not effective, and is ignored.
Which bars. An action applies to every bar that opens before its ex-date begins: 00:00 America/New_York on the ex-date for minute and hour bars, so the previous session’s after-hours is before it and the ex-date’s pre-market is not. Coarser bars built from minutes, such as 1d, are adjusted minute by minute and then aggregated.
Split factor. S is the product of new_rate / old_rate over the splits that apply to the bar: 4 before AAPL’s 4-for-1, 0.1 before a 1-for-10 reverse split, 1 when none apply.
Dividend factor (all only). D is the product of 1 − d / C over the cash dividends that apply to the bar, where d is the dividend per share and C is the raw close of the last bar before the ex-date begins (for minute data, the last minute traded, after-hours included). This is the standard multiplicative back-adjustment: a return computed from adjusted closes includes the dividend. A dividend with no bar in the 30 days before its ex-date, or one at least as large as C, is skipped. D is 1 under splits.
Prices. open, high, low, close and vwap become price / S × D.
Volume. volume becomes volume × S: the same turnover in today’s shares. Dividends never change it. After a reverse split it can be fractional.
Everything else, trade_count included, is unchanged. Bars after the newest applied action equal the raw ones. Adjusted prices are not rounded.

Examples: AAPL closed at 499.23 on 2020-08-28, the session before its 4-for-1; with adjust=splits that close is 124.8075 and its volume is four times the raw one. NVDA’s 10-for-1 took effect on 2024-06-10: a 1,200.00 trade on 2024-06-07 reads 120.00. A stock that closed at 80.00 before a 0.50 dividend gets D = 1 − 0.50 / 80.00 = 0.99375, so every earlier price is 0.625% lower.

An adjusted history changes whenever a new split or dividend lands, and raw never does: to reproduce a backtest exactly, keep the raw bars and the actions you used.

Price

Free with any API key, whatever the balance: no bars are charged (X-Bars-Charged: 0). adjust= does not change what a bars page costs. Requests still count toward the account’s limits: 2 in flight and 300 a minute.