Build a Classroom Stock Screener: Using Financial Ratio APIs for Student Projects

This step-by-step project plan teaches students how to pull live company ratios via free financial APIs, build simple filters (P/E, ROE, gross margin), and present concise investment-case pitches. It’s ideal for finance clubs, business classes, or any data literacy lesson focused on real-world financial analytics.

Why this project? Data literacy meets hands-on finance

Students learn three complementary skills at once: working with live data via financial APIs, interpreting core financial ratios, and communicating an investment case. The combination supports data-driven learning and strengthens numeracy, critical thinking, and presentation skills — essential for modern business education.

Key learning objectives

• Understand common financial ratios: price-to-earnings (P/E), return on equity (ROE), and gross margin.
• Fetch and parse live financial ratios using a free API (example: FMP API).
• Build a simple stock screener with filters and ranking.
• Critically evaluate results and present a three-minute investment pitch backed by data.

Materials & APIs

Minimum materials: a computer with internet, a spreadsheet (Google Sheets or Excel), or a basic web editor. For live ratios, the Financial Modeling Prep (FMP) API is a good free starting point for classrooms; it offers standardized KPI and financial ratio endpoints useful for teaching.

Practical notes before you start:

• Sign up for an API key where required and store it securely; never publish keys in public repos.
• Free tiers often have rate limits — cache results and use representative samples for class activities.
• Inspect the API response structure before parsing; field names can vary across services.

Project timeline (4-week plan)

1. Week 1 — Foundations:
   • Introduce P/E, ROE, margins and why investors care.
   • Show sample API responses and how to request data.

Step-by-step: Pulling live ratios (practical)

Below is a compact JavaScript example using fetch. Replace the URL and fields with those your API returns. Always test with a small symbol list first.

const API_KEY = 'YOUR_KEY';
const symbols = ['AAPL','MSFT','TSLA'];

async function getRatios(symbol) {
  const url = `https://financialmodelingprep.com/api/v3/ratios-ttm/${symbol}?apikey=${API_KEY}`;
  const res = await fetch(url);
  const data = await res.json();
  // Inspect data[0] to find the fields you need
  return data[0];
}

async function fetchAll() {
  const results = [];
  for (const s of symbols) {
    try {
      const r = await getRatios(s);
      results.push({
        symbol: s,
        pe: r.peRatio || r.priceEarningsRatio || null,
        roe: r.returnOnEquity || r.roe || null,
        grossMargin: r.grossProfitMargin || r.grossMargin || null
      });
    } catch (e) {
      console.error('Error:', s, e);
    }
  }
  console.table(results);
}

fetchAll();

Notes:

• Field names vary; inspect the JSON payload and adapt the mapping (e.g., peRatio vs priceEarningsRatio).
• If using Google Sheets, you can call an Apps Script function that fetches and writes results directly to the sheet.
• Respect rate limits by adding small delays or fetching in batches.

Building filters and the screener

Start with three simple filters that students can reason about:

• P/E ratio: filters out stocks with extreme valuations. Example rule: P/E < 25.
• ROE: measures profitability vs equity. Example rule: ROE > 12%.
• Gross margin: reflects business economics. Example rule: gross margin > 25%.

Example filtering pseudocode (language-agnostic):

candidates = allCompanies.filter(c =>
  c.pe < 25 && c.roe > 0.12 && c.grossMargin > 0.25)

ranked = candidates.map(c => ({
  symbol: c.symbol,
  score: normalizePe(c.pe) + normalizeRoe(c.roe) + normalizeMargin(c.grossMargin)
})).sort(by score desc)

Normalization converts each metric to a comparable scale (e.g., 0–1). Early iterations can simply rank by each metric and combine ordinal ranks.

User interface ideas (fast builds)

• Google Sheets: Use Apps Script to fetch ratios and standard Sheets formulas to filter and rank. Easy for low-code classrooms.
• Simple web page: Build a table and controls (sliders and checkboxes) to set filters. Students learn DOM manipulation and event handling.
• Notebooks: Jupyter or Observable notebooks work well for data science classes where students want charts and commentary.

Evaluating and presenting investment pitches

Each team picks 1–2 screened companies and prepares a short pitch (3–5 minutes). A useful structure:

1. Headline: one-sentence thesis (e.g., "Company X is an efficient, high-ROE business with attractive margins at a fair price").
2. Data: show the ratios pulled live and how the company passed the filters.
3. Qualitative context: industry trends, recent news, or risks.
4. Conclusion: buy/hold/sell stance and one data-backed justification.

Rubric suggestions (out of 20):

• Data accuracy & sourcing — 6
• Clarity of thesis and reasoning — 6
• Use of ratios and interpretation — 4
• Presentation & engagement — 4

Assessment & extra credit

Advanced assignments:

• Backtest filter performance on historical data (if API provides historical ratios).
• Create a composite scoring system and simulate a virtual portfolio.
• Compare results across two different API providers to discuss data consistency.

Limitations, ethics & classroom safety

Important teaching moments:

• APIs may return delayed data or use slightly different definitions — always verify documentation.
• Free API tiers can have incomplete coverage and rate limits; design the lesson to work with small lists.
• This is a learning exercise, not investment advice. Emphasize risk, diversification, and the limits of ratio-only analysis.
• Remind students about copyright and terms of service when using API data and presenting slides publicly.

Classroom variations

Adapt to skill levels:

• Beginner: Use Google Sheets with a teacher-provided script and focus on interpretation and presentation.
• Intermediate: Have students build a basic web UI (HTML/CSS/JS) to fetch and filter data live.
• Advanced: Require normalization, weighting, backtesting, and debate on model construction.

Cross-curricular ideas

Connect to other subjects: student perspectives on learning tools, or a module on verification such as how to verify resources. Consider pairing with a lesson on AI and student-centric models (AI & student-centric learning) to discuss automation in financial analysis.

Extensions and next steps for teachers

• Invite a guest speaker (analyst or portfolio manager) to critique student pitches.
• Publish a class leaderboard that refreshes weekly to show screener performance.
• Encourage students to keep a learning journal documenting how their filter thresholds evolved.

Final checklist for running the project

1. Create or obtain an API key and review the provider's documentation.
2. Prepare starter code and a short demo pulling ratios for 3–5 symbols.
3. Decide deliverables: spreadsheet, screener UI, and a 3–5 minute pitch.
4. Set clear evaluation criteria and a timeline to manage API rate limits.
5. Build reflection time into presentations to discuss limitations and ethics.

Running this project helps students move from abstract ratio definitions to concrete data-driven judgment. By combining financial APIs, simple programming or spreadsheet skills, and persuasive storytelling, learners build practical competencies that map directly to careers in finance, data analytics, and business.

Ready to try it? Begin by exploring a small set of companies and a free FMP API key, then iterate. If you'd like a teacher-ready worksheet or starter code tailored to your class level, ask for a downloadable template.