news-source-ranker

A small command-line tool that ranks news sources by how much they publish, how recently, and how many topics they cover. It pulls a batch of recent articles, groups them by source, scores each source, and writes an HTML report with leaderboard charts.

Data comes from the newsdata.io news API (https://newsdata.io). You'll need a free API key to run it.

What it does

• Pulls recent headlines and follows the nextPage cursor across several pages.
• Groups articles by their source and computes three signals per source:
  • volume — how many articles the source published in the sample
  • recency — how fresh its most recent article is
  • coverage — how many distinct topics (categories + keywords) it spans
• Combines them into a 0–100 composite score (default weights 0.5 / 0.3 / 0.2).
• Prints a leaderboard to the terminal and saves an interactive HTML report (Plotly) with a score chart, a volume chart, a freshness-vs-coverage bubble chart, and a sentiment breakdown.

Setup

Requires Python 3.9+.

git clone <your-fork-url>
cd news-source-ranker
pip install -r requirements.txt

Get a free key from https://newsdata.io and export it:

export NEWSDATA_API_KEY=your_key_here

On Windows PowerShell use setx NEWSDATA_API_KEY "your_key_here" and reopen the shell.

Usage

python main.py --language en --pages 5 --top 15

Filter the sample with the same parameters the API supports:

python main.py -q "climate" --country us,gb --category environment --top 10 -o climate.html

Example

$ python main.py --language en --pages 4
Fetching articles from newsdata.io /latest ...

#    source                           score    vol   topics age(h)
--------------------------------------------------------------------
1    Example News Network             100.0     12       18      1
2    Daily Wire Report                 74.3      9       11      3
3    Regional Times                    61.0      7        9      2
...

Saved report to source_ranking.html

Open source_ranking.html in a browser for the interactive charts.

Options

Flag	Description
-q, --query	Search term (q).
--country	Comma-separated country codes, e.g. us,gb.
--language	Comma-separated language codes, e.g. en.
--category	Comma-separated categories, e.g. technology.
--pages	Number of API pages to pull (about 10 articles each). Default 5.
--top	How many sources to chart. Default 15.
-o, --output	Output HTML path. Default source_ranking.html.

Scoring

Each signal is min–max scaled to 0–100 across the sources in the current sample, then combined: score = 0.5*volume + 0.3*recency + 0.2*coverage. Because the scaling is relative to the sample, scores describe a source's standing within this run, not an absolute rating. Pull more pages for a steadier picture.

Optional paid features

The default run uses only free-tier endpoints and parameters. A couple of extras are wired up but off by default because they need a paid newsdata.io plan:

• --archive (with --from-date / --to-date) queries the historical /archive endpoint instead of /latest.
• Per-article sentiment is read straight from the response when present and shown in the sentiment chart. On a free key that field is absent, so the chart falls back to clearly labeled sample values.

If a request that uses a paid parameter is rejected, the client drops those parameters and retries once, so you still get free-tier results. The keywords field used for topic coverage is available on the free tier.

Notes

• The key is read from NEWSDATA_API_KEY; it is never written to disk.
• Empty results, invalid keys (401), and rate limits (429) are handled with a readable message instead of a stack trace.

License

MIT