newsdata-node-examples

A small set of Node.js + TypeScript examples for working with the newsdata.io news API (https://newsdata.io). They cover the things you actually hit when wiring up a news API: async/await requests, cursor-based pagination, filtering by country/category/language, error handling for invalid keys and rate limits, and typed responses.

Grab a free API key at https://newsdata.io to run them.

What's here

• A small typed client (src/client.ts) around the /latest endpoint, with retries and pagination.
• TypeScript types for the response and article shapes (src/types.ts).
• Four runnable examples: latest headlines, pagination, filtering, and a sentiment view.
• Graceful handling of fields that only exist on paid plans (sentiment, ai_tag, ai_summary) — they fall back to a clearly labeled placeholder instead of breaking the output.

Requirements

• Node.js 18 or newer (uses the built-in fetch).
• A newsdata.io API key.

Setup

git clone <this repo>
cd newsdata-node-examples
npm install
export NEWSDATA_API_KEY=your_key_here

The key is read from the NEWSDATA_API_KEY environment variable. Nothing runs without it.

Running

npm run latest
npm run paginate -- --pages=3
npm run filter -- --country=us --category=technology
npm run sentiment

Flags (all optional): --q, --country, --category, --language (default en), --domain, --pages.

Example

$ npm run filter -- --country=us --category=technology
Filters: {"q":null,"country":"us","category":"technology","language":"en"}

3 result(s):

 1. Chipmaker reports quarterly results [sentiment n/a]
    Example News  2026-06-11 09:30:00
    https://example.com/article
    keywords: chips, earnings, semiconductors
    ai tags: none (paid newsdata.io field)
    A short description shown when no AI summary is available…

Exact output depends on the live headlines at the time you run it.

Free vs paid fields

The examples request data normally and read whatever the API returns. Some response fields — sentiment, sentiment_stats, ai_tag, ai_region, ai_org, ai_summary — are only populated on paid newsdata.io plans. On a free key they come back empty, and the examples render a clearly labeled placeholder (for instance, the sentiment breakdown shows a sample distribution with a caption) so the layout still makes sense.

Paid query parameters (such as sentiment=) are a different matter: sending them on a free key fails the whole request, so they are off by default. Set NEWSDATA_PAID_MODE=1 to send them; this requires a paid newsdata.io plan. If a paid request is rejected, the client retries once without those parameters so you still get free-tier results.

Project layout

src/
  client.ts     typed API client (fetch, retries, pagination)
  types.ts      response + article types
  format.ts     console rendering helpers
  examples.ts   CLI entry point for the four examples

Build

npm run typecheck   # type-check only
npm run build       # emit JS + .d.ts to dist/

Notes

• Pagination uses the nextPage cursor returned by the API, passed back as page; iteration stops when it is null.
• HTTP 429 responses are retried with backoff (honoring Retry-After); HTTP 401 raises a clear "invalid key" error.
• The default examples use only free-tier parameters against the /latest endpoint.

License

MIT