screen_stocks

io.github.aatharva16/dalalos · Verify this server

Screen the Indian security universe by user-supplied mechanical criteria. All `filters` keys are optional and AND-combined. `sort_by`/`order` order the result set; `limit` (1..100) caps it. Returns matching securities with the screened metrics — data only, no recommendations. An unknown filter key returns a `bad_request` error that lists every accepted key verbatim, so a rejected call is always self-correcting. RANGE filters (take a `_min` and/or `_max` suffix, e.g. `pe_min: 10, pe_max: 20`): market_cap, price, pe, pb, deliv_pct, week52_high, week52_low, turnover, num_trades (quote-level) — deliv_pct is a PERCENTAGE (50 = 50%); week52_high/week52_low are rupee price levels comparable to `price`; turnover is a rupee traded-value, num_trades a count. promoter_pct, pledged_pct — PERCENTAGES (pass 50 for "50%"), from shareholding data. roe, roa, roce, net_margin, dividend_yield, earnings_yield, fcf_yield, ebitda_margin, operating_margin, quarterly_net_margin_delta_yoy — FRACTIONS (pass 0.15 for "15%"). interest_coverage, ev, ev_to_ebitda, ev_to_ebit, price_to_cash_flow, price_to_fcf, debt_to_equity, price_to_sales, piotroski_f_score (0-9) — plain multiples/scores, no unit conversion needed. revenue_growth, net_income_growth, quarterly_revenue_growth_yoy, quarterly_net_income_growth_yoy, return_1d/1w/1m/3m/6m/1y — FRACTIONS (0.20 = 20% growth or return); unlike the margin/yield group above, these may legitimately exceed 1.0 (>100%) for high-growth or multi-bagger names. pct_off_52w_low — derived, FRACTION: (price - week52_low) / week52_low, e.g. `pct_off_52w_low_max=0.05` for "within 5% of its 52-week low". num_shareholders (a count) and promoter/fii/dii/public_holding_change_qoq — PERCENTAGE POINTS between the latest two shareholding filings (50% -> 55% is 5, not 0.10) — plus num_shareholders_change_qoq, a plain count difference. A security with only one filed period is EXCLUDED, never matched as a zero change. revenue_cagr_3y/5y, net_income_cagr_3y/5y — 3Y/5Y sales and profit CAGR, FRACTIONS. roe_weighted_avg_3y/5y, roce_weighted_avg_3y/5y — multi-year return on equity / capital employed, FRACTIONS, computed as sum(numerators)/sum(denominators) over the window (denominator-WEIGHTED, not the average of the yearly ratios). All eight are null unless that many annual periods are cached; the 5Y horizons are null for most names today. sales_growth_ttm, profit_growth_ttm — TTM vs the preceding TTM, FRACTIONS, and like the other growth rates they may legitimately exceed 1.0. roa_last_year — last ANNUAL profit over average assets (roa's trailing-twelve-month sibling), a FRACTION. opm_ex_other_income — operating margin on the Schedule-III Sales-minus-Expenses subtotal, so it EXCLUDES other income, a FRACTION; operating_margin keeps its EBIT basis. roce_ex_exceptional — roce with the pre-tax exceptional item removed, a FRACTION. pe_ex_exceptional — market cap over TTM profit with the after-tax exceptional item removed, a multiple; the headline pe keeps its own basis. price_to_fcf_3y_avg — market cap over 3-year-average free cash flow, a multiple. inventory_days_material_cost, payable_days_material_cost — DAYS, on a material-cost denominator rather than full COGS. working_capital_ex_st_borrowings — RUPEES, with short-term borrowings netted out. Each of these stands BESIDE the DalalOS metric of the same family rather than replacing it, so both bases are screenable. EXACT-MATCH filters (single value, no `_min`/`_max`): sector, industry, igroup, isubgroup, company_type (e.g. "bank", "nbfc", "insurer", "general"), index (e.g. "NIFTY 50" — membership in that index's constituent list). BOOLEAN filter (a bare true/false, no `_min`/`_max`): is_sme — listed on an SME platform (NSE Emerge). THREE-VALUED: a security whose listing segment is unverified matches neither is_sme=true nor is_sme=false, because no official machine-readable BSE SME membership list exists. Some derived metrics are general-only (null for bank/nbfc/insurer): roce, interest_coverage, ev*, earnings_yield, ebitda_margin, operating_margin, piotroski_f_score, roce_weighted_avg_3y/5y, opm_ex_other_income, roce_ex_exceptional, inventory_days_material_cost, payable_days_material_cost.