From Raw API to Readable Financial Report

How I Turn FMP JSON into Plain-English Company Summaries

Photo by Nataliya Vaitkevich

APIs deliver raw data, and while that’s great for machines, it’s not ideal for humans. When you fetch company financials, the response usually comes in JSON — structured but not readable. Numbers alone don’t tell a story, and scrolling through endless keys and values can be overwhelming.

This article shows how to bridge that gap. We’ll use the Financial Modeling Prep (FMP) API to fetch real company data and then turn it into plain-English summaries. With Python, we’ll pull metrics like revenue, net income, and return on equity (ROE) and automatically convert them into simple sentences that anyone can understand.

Why Raw JSON Needs Interpretation

APIs are designed for developers, not end users. When you call a financial API, you don’t get a sentence that says “Nvidia’s revenue grew by 20% last year.” Instead, you get structured JSON with fields like revenuePerShare, netIncomePerShare, and roe.

Here’s a quick example of what a raw API response might look like:

[
  {
    "symbol": "NVDA",
    "date": "2024-01-31",
    "revenuePerShare": 5.31,
    "netIncomePerShare": 2.96,
    "roe": 0.91
  }
]

For machines, this format is perfect. For humans, not so much. Most readers don’t want to decode key names or cross-check numbers — they want a story. That’s why we need a layer that transforms JSON into natural language summaries.

Choosing the Right FMP Endpoint

The first step is picking the right API endpoint. Since our goal is to generate quick, plain-English summaries of a company’s financial health, we need just a handful of key metrics — revenue, net income, and return on equity (ROE).

FMP provides these in the Key Metrics API:

https://financialmodelingprep.com/api/v3/key-metrics/{ticker}?period=annual&limit=1&apikey=YOUR_API_KEY

This endpoint returns essential ratios and metrics in a single response, including revenue per share, net income per share, and ROE. Here’s a trimmed example for Nvidia:

[
  {
    "symbol": "NVDA",
    "date": "2024-01-31",
    "revenuePerShare": 5.3144,
    "netIncomePerShare": 2.9680,
    "roe": 0.9187
  }
]

With this, we have everything we need to craft a summary. Next, let’s see how to fetch this data in Python.

Fetching Data with Python

Once we know the right endpoint, pulling the data is straightforward. We’ll use Python’s requests library to call the API and pandas to organize the response.

import requests
import pandas as pd

API_KEY = "your_api_key"
ticker = "NVDA"

url = f"https://financialmodelingprep.com/api/v3/key-metrics/{ticker}?period=annual&limit=1&apikey={API_KEY}"
response = requests.get(url)

# Convert to JSON
data = response.json()

# Load into DataFrame for easy handling
df = pd.DataFrame(data)

print(df[['date', 'revenuePerShare', 'netIncomePerShare', 'roe']])

Sample Output:

         date  revenuePerShare  netIncomePerShare       roe
0   2024-01-31          5.3145             2.9680  0.918729

This confirms that the API is working correctly and gives us exactly what we need. Next, we’ll turn these numbers into readable summaries.

Turning JSON into Plain‑English Summaries

We’ll fetch metrics from the **FMP Key Metrics** endpoint and pass only the needed fields to a Groq Llama‑3 chat model. The model turns numbers into a clean, human‑readable summary — no if/else trees.

Install & setup

pip install requests pandas groq

import os, requests, pandas as pd
from groq import Groq

FMP_API_KEY = os.getenv("FMP_API_KEY") or "YOUR_FMP_KEY"
GROQ_API_KEY = os.getenv("GROQ_API_KEY") or "YOUR_GROQ_KEY"

groq_client = Groq(api_key=GROQ_API_KEY)

Groq’s Python SDK uses a Chat Completions API — simple to call and fast.

Fetch minimal FMP JSON

We’ll stick to one proven endpoint to avoid breakage. The Key Metrics API is ideal for high‑signal fields (revenue per share, net income per share, ROE).

def fetch_metrics(ticker: str):
    url = f"https://financialmodelingprep.com/api/v3/key-metrics/{ticker}"
    params = {"period": "annual", "limit": 1, "apikey": FMP_API_KEY}
    r = requests.get(url, params=params, timeout=20)
    r.raise_for_status()
    data = r.json()
    if not data:
        return None
    row = data[0]
    return {
        "symbol": row.get("symbol", ticker.upper()),
        "date": row.get("date"),
        "revenuePerShare": row.get("revenuePerShare"),
        "netIncomePerShare": row.get("netIncomePerShare"),
        "roe": row.get("roe")  # return on equity (decimal, e.g., 0.12)
    }

Prompt the LLM (no templates, no rules)

We instruct the model to only use provided values and keep it crisp in plain English.

def llm_summary_from_metrics(metrics: dict) -> str:
    if not metrics:
        return "No data available to summarize."

    system_msg = (
        "You turn raw financial metrics into a short, plain‑English summary. "
        "Only use the values provided. Do not invent numbers."
    )
    user_msg = {
        "role": "user",
        "content": (
            "Create a 2–3 sentence summary from this JSON. "
            "Mention the ticker, date, revenue per share, net income per share, and ROE as a percentage. "
            "Keep tone factual, clear, and concise.\n\n"
            f"{metrics}"
        )
    }

    resp = groq_client.chat.completions.create(
        model="llama3-8b-8192",  # fast, fluent Llama‑3 on Groq
        messages=[{"role": "system", "content": system_msg}, user_msg],
        temperature=0.3,
        max_tokens=180
    )
    return resp.choices[0].message.content.strip()

Models and usage per Groq docs; replace with your preferred Groq model if needed.

def summarize_company(ticker: str) -> str:
    m = fetch_metrics(ticker)
    return llm_summary_from_metrics(m)

# Example:
print(summarize_company("NVDA"))

This gives you a fluent, human‑friendly paragraph powered by your real FMP data and an LLM, with no brittle rule‑sets. If you prefer the freshest values, you can swap to key‑metrics‑ttm with the same pattern.

Automating Company Summaries at Scale

One company summary is useful. But the real value comes when you can generate plain-English reports for dozens of tickers at once. By combining the FMP API with Groq, you can loop over a list of tickers, fetch their key metrics, and feed them into the LLM in one go.

Here’s a batch version that handles multiple companies and saves the results:

tickers = ["NVDA", "AAPL", "AMD", "MSFT"]

summaries = []
for t in tickers:
    try:
        summary = summarize_company(t)
        summaries.append({"ticker": t, "summary": summary})
    except Exception as e:
        summaries.append({"ticker": t, "summary": f"Error: {e}"})

# Convert to DataFrame for export
df_summaries = pd.DataFrame(summaries)

# Save to CSV or Markdown
df_summaries.to_csv("company_summaries.csv", index=False)
print(df_summaries)

Output (CSV):

ticker,summary
NVDA,"Nvidia reported revenue per share of 5.31 and net income per share of 2.96 for 2024-01-31, with an impressive ROE of 91.9%."
AAPL,"Apple’s revenue per share was 6.02 with net income per share of 1.89. Its ROE stood at 28%, highlighting strong shareholder returns."
AMD,"AMD posted revenue per share of 4.41 and net income per share of 0.97, yielding a modest 12% ROE."
...

Now you’ve got a scalable pipeline:

• Data Source: FMP Key Metrics API (trusted, structured JSON).
• Narrative Layer: Groq LLM (fluid, human-like summaries).
• Automation: Python loop + CSV export.

This means you can drop a list of any 50 tickers and instantly produce a readable financial snapshot for each.

[embed]Free Stock Market API and Financial Statements API... Access the most reliable free stock market APIs and financial data APIs for real-time stock prices, financial…site.financialmodelingprep.com

Conclusion

Turning raw JSON into readable insights no longer needs manual effort or rigid templates. By combining the accuracy of the FMP API with the fluency of Groq’s LLMs, we built a pipeline that transforms structured numbers into plain-English reports. Whether for one company or an entire portfolio, this approach makes financial data instantly accessible and easy to share. It’s a practical way to bridge machine data and human understanding — scalable, fast, and ready for real-world use.