How to install and use the Node.js SDK#

Install the official SDK with npm install @apitube/news-api, import Client, and create it with your API key. From there, client.news('everything', {...}) sends the request and hands you back parsed articles — no manual URL building or JSON wrangling. The package needs Node.js 18+, ships both ESM and CommonJS builds, and includes TypeScript types, so it works the same in a plain Node script or a typed project.

import { Client } from '@apitube/news-api';

const client = new Client({ apiKey: 'your-api-key' });

const response = await client.news('everything', {
  title: 'artificial intelligence',
  'language.code': 'en',
  per_page: 5,
});

for (const article of response.articles) {
  console.log(article.title, article.url);
}

How do you install the Node.js SDK?#

The SDK is published on npm as @apitube/news-api. Add it to any Node project:

npm install @apitube/news-api

It requires Node.js 18 or newer and depends on axios for HTTP. The package exposes both an ESM entry (import) and a CommonJS entry (require), so import { Client } from '@apitube/news-api' and const { Client } = require('@apitube/news-api') both work. TypeScript declarations are bundled — you get autocomplete and type checking without installing a separate @types package. The library is MIT-licensed.

How do you create the client and authenticate?#

Create one Client and reuse it. The only required option is apiKey; baseUrl defaults to https://api.apitube.io, so you normally leave it out:

import { Client } from '@apitube/news-api';

const client = new Client({
  apiKey: process.env.APITUBE_API_KEY, // keep the key out of source
});

Under the hood the SDK sends your key in an X-API-Key header on every request, so you never build that header yourself. Need a custom timeout or interceptor? Pass your own axios instance as httpClient:

import axios from 'axios';
import { Client } from '@apitube/news-api';

const httpClient = axios.create({ timeout: 30_000 });
const client = new Client({ apiKey: process.env.APITUBE_API_KEY, httpClient });

Grab a key from your dashboard first — see where to find and create your API key and how to authenticate your API requests for the header details.

How do you search for news articles?#

client.news(endpoint, params) is the main method. The first argument picks the endpoint — 'everything', 'top-headlines', 'story', 'article' or 'raw' — and the second is a plain object of filter parameters. Parameter names are passed exactly as the API expects them, including dotted names like language.code and sort.by:

const response = await client.news('everything', {
  title: 'climate change',
  'language.code': 'en',
  'sort.by': 'published_at',
  'sort.order': 'desc',
  per_page: 10,
});

console.log(`Page: ${response.page}`);
console.log(`Has next page: ${response.hasNextPages ? 'yes' : 'no'}`);

for (const article of response.articles) {
  console.log(article.title);
  console.log(`Source: ${article.source?.domain}`);
  console.log(`Published: ${article.publishedAt}`);
  console.log(`Sentiment: ${article.sentiment?.overall?.polarity}`);
}

The call returns an ArticleList whose articles array holds parsed article objects, plus pagination fields page, limit, hasNextPages and nextPage. The 'story' endpoint needs an id in the params (client.news('story', { id: 'story-id' })); the SDK throws if it is missing. Every method accepts an optional third argument for the API version, which defaults to 'v1'. For the full parameter list, see the official News API parameter reference.

How do you count, autocomplete and read reference data?#

Beyond search, the client wraps the helper endpoints:

• Count — await client.count({ title: 'artificial intelligence', 'language.code': 'en' }) returns a plain number of matching articles, using the same filters as everything.
• Autocomplete — await client.suggest('categories', 'spo') returns suggestion items; supported types are categories, topics, industries and entities.
• Reference lists and profiles — client.people(params), client.companies(params) and client.journalists(params) return a paginated list in .results; each has a by-ID profile method (client.person(id), client.company(id), client.journalist(id)).
• Balance — await client.balance() returns your plan and remaining points.
• Ping — await client.ping() returns true if the API is reachable, false otherwise.

How do you handle errors and rate limits?#

Failed requests throw typed exceptions you can catch by class. AuthenticationException covers a 401 (missing or wrong key), RateLimitException covers a 429 and exposes retryAfter in seconds, and ApiException is the base for any other API error, carrying statusCode and requestId:

import {
  ApiException,
  AuthenticationException,
  RateLimitException,
} from '@apitube/news-api';

try {
  const response = await client.news('everything', { title: 'node' });
} catch (e) {
  if (e instanceof AuthenticationException) {
    console.log(`Auth error: ${e.message}`);
  } else if (e instanceof RateLimitException) {
    console.log(`Rate limited. Retry after ${e.retryAfter}s`);
  } else if (e instanceof ApiException) {
    console.log(`API error (${e.statusCode}): ${e.message}, request ${e.requestId}`);
  }
}

Quote the requestId when you contact support. For what triggers a 429 and how to back off, see how to handle rate-limit (429) errors.

Common Questions#

• Which Node.js versions are supported?
• Does the SDK support TypeScript?
• Which endpoints can I call from the SDK?
• Can I use my own HTTP client?

Which Node.js versions are supported?#

The package declares engines.node >= 18, so use Node.js 18 or newer. It ships both an ESM build and a CommonJS build, so it drops into modern import-based projects and older require-based ones alike.

Does the SDK support TypeScript?#

Yes. Type declarations (.d.ts) are bundled with the package, so Client, its option and endpoint types (ClientOptions, NewsEndpoint, SuggestType), the response classes and the exception classes are all fully typed. You get autocomplete and compile-time checks with no extra @types install.

Which endpoints can I call from the SDK?#

client.news(...) covers everything, top-headlines, story, article and raw. Separate methods cover count, suggest, the people/companies/journalists lists and profiles, balance and ping. Each maps to the matching /v1/... REST endpoint.

Can I use my own HTTP client?#

Yes. Pass an axios instance as the httpClient option when constructing the Client. This lets you set a global timeout, add interceptors, or route requests through a proxy while the SDK still handles auth headers, JSON parsing and error mapping.