API Quick Reference

Base URL /api/v1, JSON only, read-only, no keys. The full schema is backend/openapi.json, also served at /api/v1/openapi.json (import it into Postman, Bruno or Insomnia).

Endpoints

Endpoint	Query	Answer
GET /markets		every market with country, timezone, weekend, session
GET /markets/{code}		one market
GET /markets/{code}/holidays	year	closures and half days with names and close times
GET /markets/{code}/holidays.csv	year	the same as CSV
GET /markets/{code}/calendar.ics	year?	iCalendar feed: this year and next, or one year
GET /markets/{code}/status	at?	open, closed or hours unknown, with the next close or open
GET /status	at?	the same for every market
GET /markets/{code}/is-trading-day	date	true or false
GET /markets/{code}/next-trading-day	date	first trading day after the date
GET /markets/{code}/previous-trading-day	date	last trading day before the date
GET /markets/{code}/trading-days	start, end	trading days in the range (at most 400 days)
GET /markets/{code}/settlement-cycle	date	cycle in force with its source, or null
GET /settlement	markets, trade_date, cycle?	settlement date on every listed market
GET /add-trading-days	markets, date, days	the date moved by n trading days on every market
GET /overlap	markets, start, end	days on which every market trades
GET /data-quality		library compared with official calendars
GET /health		MySQL and Redis status (503 when either is down)

curl "http://localhost:5000/api/v1/settlement?markets=XNYS,XLON&trade_date=2026-12-23&cycle=2"
# {"markets":["XNYS","XLON"],"trade_date":"2026-12-23","cycle":2,"settlement_date":"2026-12-29",...}

Rules

• Market codes are MICs, case-sensitive: XNYS, not NYSE (aliases get a 404).
• Dates are ISO YYYY-MM-DD. Ranges include both ends; day ranges are capped at 400 days.
• Years outside the library's data for a market are a 400, never an empty answer.
• Half days are still trading days.
• Settlement: T+n is the n-th day after the trade date on which every listed market is open. Without cycle, each market's cycle in force on the trade date is used and the longest wins.

Errors

One shape: {"error": {"code", "message", "params"}}. Codes: invalid_parameter, unknown_market, year_out_of_range, invalid_range, invalid_markets, no_default_cycle, rate_limited.

Rate limit

120 requests a minute per client, with RateLimit-Limit and RateLimit-Remaining headers and a 429 rate_limited error past it.