py-ftmarkets

Financial Times (markets.ft.com) data source for Python. Provides a high-level API and CLI to search for securities, fetch historical data, and validate prices.

Installation

uv add py-ftmarkets
# or
pip install py-ftmarkets

CLI Usage

The ftmarkets CLI is built on treaty and needs Python 3.14 and the cli extra. The library itself still supports Python 3.10 and later; on an older Python, or without the extra, ftmarkets exits 1 and says how to install it.

uv tool install --python 3.14 "py-ftmarkets[cli]"
# or, in a Python 3.14 environment
pip install "py-ftmarkets[cli]"

--format takes plain (the default on a terminal), json (the full response envelope with ok, data, error, warnings, and meta; the default when piped), jsonl, ndjson, and tsv. -v and -vv show info and debug logs on stderr. ftmarkets <command> --help lists the flags and --schema the input and output schemas.

Exit codes: 0 success, 2 invalid arguments (nothing ran), 5 security or history not found, 79 the price check failed (history --price).

Lookup a Security

Resolve an ISIN or Symbol to the Financial Times symbol format (e.g., AAPL:NSQ). Results keep FT's relevance order. --limit defaults to 1 (the best match) and --limit 0 returns every match; when more matches exist, meta.pagination.next_cursor (or the stderr hint in text formats) is the --cursor for the next page.

--asset-class takes one of equity, fixed_income, cash, commodity, real_estate, fx, crypto, derivative, alternative, or index; --security-type matches FT's own category (ETF, Fund, Equity, Index) in any case. --date is YYYY-MM-DD, YYYY/MM/DD, or YYYYMMDD.

# Basic lookup by ISIN
ftmarkets lookup --isin DE000A0S9GB0

# The three best matches, then the next three
ftmarkets lookup --isin US0378331005 --limit 3 --format json
ftmarkets lookup --isin US0378331005 --limit 3 --cursor <meta.pagination.next_cursor>

# Keep only matches that traded near a price on a date (--price needs --date)
ftmarkets lookup --isin DE000A0S9GB0 --price 117.81 --date 2025-12-12

# Lookup with filters (currency, country, FT security type, exchange)
ftmarkets lookup --isin DE000A0S9GB0 --currency EUR --country DE --security-type ETF

# Only equity listings (asset class)
ftmarkets lookup --isin US0378331005 --asset-class equity --limit 0

# Every match as a JSON envelope; the securities are in .data
ftmarkets lookup --isin DE000A0S9GB0 --limit 0 --format json

# Every match as a table
ftmarkets lookup --isin DE000A0S9GB0 --limit 0 --format tsv

Fetch History and Validate

Fetch historical data for a resolved security and optionally validate a trade price on a specific date. The result holds the resolved security, its history (candles in ascending date order), and validated (true when the price matched, null without --price).

# Fetch 1 month of history for an ISIN
ftmarkets history --isin DE000A0S9GB0

# Fetch 1 year of history and validate a price; exits 79 (PRICE_MISMATCH) when it does not match
ftmarkets history --isin DE000A0S9GB0 --period 1y --price 120.50 --date 2025-01-15 --format json

Library Usage

py-ftmarkets implements the DataSource interface from pydantic-market-data.

from ftmarkets.api import FTDataSource
from pydantic_market_data.models import SecurityCriteria

source = FTDataSource()

# Resolve a security
criteria = SecurityCriteria(isin="DE000A0S9GB0")
security = source.resolve(criteria)
print(f"Symbol: {security.symbol}")

# Fetch history
history = source.history(security.symbol, period="1mo")
df = history.to_pandas()
print(df.tail())

# Validate price
is_valid = source.validate(security.symbol, target_date="2025-01-15", target_price=120.50)
print(f"Price valid: {is_valid}")

Features

• Robust Resolution: Searches by ISIN, Symbol, or Description.
• Smart Mapping: Prioritizes results based on preferred exchanges and currency.
• Price Validation: Verifies if a security traded within a range or near a specific price on a given date.
• Pandas Integration: Historical data is easily convertible to Pandas DataFrames.
• Modern Python: Built with Pydantic v2 and async-ready architecture (though currently synchronous).