{"openapi":"3.1.0","info":{"title":"Dividend & Valuation API","version":"1.0.0","description":"Stock dividend and valuation fundamentals as an API, computed locally and deterministically — the per-share ratios value and income investors screen on. The dividend endpoint takes a share price and an annual dividend (per share, or total dividends ÷ shares) and returns the dividend yield, and with earnings per share the payout ratio (dividend ÷ EPS), the dividend coverage (EPS ÷ dividend) and the retention ratio — a $2 dividend on a $50 share yields 4 %, and on $4 EPS is a 50 % payout covered twice. The valuation endpoint computes the price-to-earnings ratio, earnings yield, the PEG ratio against a growth rate, the price-to-book ratio and the Graham number √(22.5 · EPS · book value) — Benjamin Graham's rough fair-value ceiling. The ddm endpoint runs the Gordon Growth dividend discount model, fair value = D1 ÷ (r − g) from next year's dividend, the required return and the perpetual growth rate, and against a market price flags whether the share looks under- or over-valued and the implied cost of equity. Everything is computed locally and deterministically, so it is instant and private. Ideal for investing, brokerage, robo-advisor, dividend-screener and fintech app developers, stock-valuation and income-portfolio tools, and finance education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. These are valuation ratios from your inputs; for live quotes use a market-data API and for project DCF/NPV an investment-appraisal API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/dividend-api","description":"oanor gateway"}],"tags":[{"name":"Dividend"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/ddm":{"get":{"operationId":"get_v1_ddm","tags":["Dividend"],"summary":"Gordon Growth model","description":"","parameters":[{"name":"current_dividend","in":"query","required":false,"description":"Current dividend D0 (or next_dividend)","schema":{"type":"string"},"example":"2"},{"name":"next_dividend","in":"query","required":false,"description":"Next dividend D1","schema":{"type":"string"}},{"name":"growth_rate","in":"query","required":false,"description":"Perpetual growth %","schema":{"type":"string"},"example":"5"},{"name":"required_return","in":"query","required":true,"description":"Required return %","schema":{"type":"string"},"example":"10"},{"name":"price","in":"query","required":false,"description":"Market price (for under/over)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Gordon Growth model: fair value = D1 / (r − g), where D1 is next year's dividend, r the required return and g the perpetual growth rate (all as fractions). Requires r > g.","inputs":{"growth_rate":5,"next_dividend":2.1,"required_return":10,"current_dividend":2},"intrinsic_value":42},"meta":{"timestamp":"2026-06-05T21:48:46.105Z","request_id":"cd7f9153-d530-4778-af41-d64ea761379d"},"status":"ok","message":"Dividend discount model","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/dividend":{"get":{"operationId":"get_v1_dividend","tags":["Dividend"],"summary":"Yield, payout & coverage","description":"","parameters":[{"name":"price","in":"query","required":true,"description":"Share price","schema":{"type":"string"},"example":"50"},{"name":"annual_dividend","in":"query","required":false,"description":"Annual dividend per share","schema":{"type":"string"},"example":"2"},{"name":"total_dividends","in":"query","required":false,"description":"Total dividends (with shares)","schema":{"type":"string"}},{"name":"shares","in":"query","required":false,"description":"Shares outstanding","schema":{"type":"string"}},{"name":"eps","in":"query","required":false,"description":"Earnings per share (for payout)","schema":{"type":"string"},"example":"4"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"eps":4,"note":"Dividend yield = annual dividend / price. Payout ratio = dividend / EPS (how much of earnings is paid out); coverage = EPS / dividend (how many times earnings cover it).","inputs":{"price":50,"annual_dividend":2},"dividend_coverage":2,"payout_ratio_percent":50,"dividend_yield_percent":4,"retention_ratio_percent":50,"annual_dividend_per_share":2},"meta":{"timestamp":"2026-06-05T21:48:46.196Z","request_id":"3ab5bd22-b590-449f-a785-5ee0c80b5978"},"status":"ok","message":"Dividend metrics","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/valuation":{"get":{"operationId":"get_v1_valuation","tags":["Dividend"],"summary":"P/E, PEG, P/B, Graham","description":"","parameters":[{"name":"price","in":"query","required":true,"description":"Share price","schema":{"type":"string"},"example":"50"},{"name":"eps","in":"query","required":true,"description":"Earnings per share","schema":{"type":"string"},"example":"4"},{"name":"growth_rate","in":"query","required":false,"description":"Annual growth % (for PEG)","schema":{"type":"string"},"example":"10"},{"name":"book_value_per_share","in":"query","required":false,"description":"Book value per share","schema":{"type":"string"},"example":"20"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"P/E = price / EPS; earnings yield = EPS / price. PEG = P/E ÷ growth%; under 1 is often called cheap-for-growth. Graham number = √(22.5 · EPS · book value) — a rough fair-value ceiling.","inputs":{"eps":4,"price":50},"pb_ratio":2.5,"pe_ratio":12.5,"peg_ratio":1.25,"growth_rate":10,"graham_number":42.4264,"book_value_per_share":20,"earnings_yield_percent":8},"meta":{"timestamp":"2026-06-05T21:48:46.283Z","request_id":"92e12145-098b-4560-95de-a69f85716800"},"status":"ok","message":"Valuation ratios","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"notes":"Per-share figures in one consistent currency; rates as percentages (10 = 10%). These are valuation ratios from your inputs — for live quotes use a market-data API and for DCF/NPV an investment-appraisal API.","service":"dividend-api","endpoints":{"GET /v1/ddm":"Gordon Growth intrinsic value and implied required return.","GET /v1/meta":"This document.","GET /v1/dividend":"Dividend yield, payout ratio and coverage from price, dividend and EPS.","GET /v1/valuation":"P/E, PEG, P/B, earnings yield and Graham number."},"description":"Stock dividend & valuation fundamentals: yield/payout/coverage, P/E, PEG, P/B, earnings yield, Graham number and the Gordon Growth dividend discount model."},"meta":{"timestamp":"2026-06-05T21:48:46.376Z","request_id":"7a31eef8-4f4a-4d33-8e18-3379710b02c9"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":3850,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":720,"monthly_call_quota":40000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1880,"monthly_call_quota":191000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5550,"monthly_call_quota":1090000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/dividend-api"}