competitor-news-spy

A command-line tool that scans recent news for mentions of the competitors you list and prints a digest you can read at a glance: how many times each brand came up, which outlets covered it, and the keywords that showed up most often.

It pulls live headlines from the newsdata.io news API (https://newsdata.io) — grab a free API key to run it.

What it does

• Tracks any number of brands (passed on the command line or read from a file).
• Counts mentions per brand and breaks them down by news source.
• Builds a keyword-frequency list from the article keywords newsdata.io returns.
• Shows a sentiment breakdown and AI topic tags per brand when your plan provides them; otherwise it shows a clearly-labeled placeholder so the layout stays intact.
• Prints to the terminal and can also write a Markdown digest for sharing.

Requirements

• Python 3.8+
• The requests library (see requirements.txt)

Setup

1. Install dependencies:

   pip install -r requirements.txt
   

2. Get a free API key from newsdata.io (https://newsdata.io) and export it:

   export NEWSDATA_API_KEY=your_key_here
   

3. (Optional) List the brands you want to follow, one per line:

   cp competitors.example.txt competitors.txt
   # edit competitors.txt
   

Usage

Track one or more brands directly:

python main.py --brand "Acme Corp" --brand Globex

Or read them from a file (defaults to competitors.txt if present):

python main.py --file competitors.txt

Useful options:

--language en         Language code (default: en)
--country us          Restrict to a country code
--max-pages 2         Pages to fetch per brand (~10 articles each; default 1)
--top 10              How many sources/keywords to list
--markdown digest.md  Also write the digest as Markdown

Example

$ python main.py --brand "Acme Corp"

============================================================
COMPETITOR NEWS DIGEST
Generated: 2026-06-12 09:00 UTC
Source: newsdata.io news API (https://newsdata.io)
============================================================
Tracking 1 brand(s) — 7 matching article(s).

------------------------------------------------------------
## Acme Corp — 7 mention(s)
------------------------------------------------------------
Top sources:
    3  TechCrunch
    2  Reuters
    2  The Verge

Top keywords:
    4  acme
    3  funding
    2  hardware

Sentiment breakdown:
  sample — live sentiment requires a paid newsdata.io plan
  positive    5  ############............   (sample)
  neutral     3  #######.................   (sample)
  negative    2  #####...................   (sample)

AI tags: (none — requires a paid newsdata.io plan)

Latest headlines:
  [?] Acme Corp raises Series B to expand hardware line
      TechCrunch · 2026-06-12 06:30:00
      https://example.com/acme-series-b

How it works

For each brand the tool queries the newsdata.io latest endpoint with the brand as the search term, follows the nextPage cursor up to --max-pages, and aggregates the results. Only free-tier-safe parameters are sent on the default path, so a brand-new free key works without extra configuration.

Optional: paid response fields

Some fields — sentiment, ai_tag, ai_summary — are only populated on paid newsdata.io plans. The tool reads them straight from each article when present and falls back to a labeled placeholder when they are absent, so nothing breaks on a free key. No paid-only query parameters are sent on the default path.

License

MIT