OFFICIAL SDKs · v0.1

TypeScript and Python SDKs

Typed clients that handle authentication, retries, paging and polling for you. Both are MIT-licensed.

Publishing soon

The packages aren't on npm and PyPI yet. Until they are, call the REST API directly: every example in the quickstart and API reference works without an SDK.

Install

TypeScript needs Node 18+ (or Deno, Bun or an edge runtime) and has no runtime dependencies. Python needs 3.9+ and uses httpx and Pydantic v2.

npm install @newssearchapi/sdk

pip install newssearchapi

First request

Read the key from an environment variable, never from source code.

import { NewsSearchAPI } from "@newssearchapi/sdk";

const news = new NewsSearchAPI({ apiKey: process.env.NEWSSEARCHAPI_API_KEY! });

const { data, meta } = await news.articles.search({ q: "climate summit", page_size: 10 });
for (const article of data.articles) console.log(article.title);
console.log("Requests left this period:", meta.quota.remaining);

const { data: one } = await news.articles.get(data.articles[0].id);

import os
from newssearchapi import NewsSearchAPI

with NewsSearchAPI(api_key=os.environ["NEWSSEARCHAPI_API_KEY"]) as news:
    result = news.articles.search({"q": "climate summit", "page_size": 10})
    for article in result.data.articles:
        print(article.title)
    print("Requests left this period:", result.meta.quota_remaining)

    one = news.articles.get(result.data.articles[0].id).data.article

Article content is plain text. Every plan returns metadata, a safe excerpt of about 200 characters with contentTruncated: true, and a link to the original article.

You can set baseUrl, timeoutMs, maxRetries or a custom fetch in the TypeScript constructor. Python also has AsyncNewsSearchAPI with the same methods as awaitables.

Errors and retries

Failed requests raise NewsSearchAPIError with the HTTP status, API error code, message and request ID. Network errors, 429 and 5xx responses are retried automatically with exponential backoff and jitter, honouring Retry-After. Other 4xx errors are never retried.

import { NewsSearchAPI, NewsSearchAPIError } from "@newssearchapi/sdk";

try {
  await news.articles.search({ q: "elections", page_size: 500 });
} catch (error) {
  if (error instanceof NewsSearchAPIError) {
    console.error(error.status, error.code, error.message, error.requestId);
  } else throw error;
}

from newssearchapi import NewsSearchAPIError

try:
    news.articles.search({"q": "elections", "page_size": 500})
except NewsSearchAPIError as error:
    print(error.status, error.code, error.message, error.request_id)

Paging

iterate walks every page for you, up to the API's 10,000-result window.

for await (const article of news.articles.iterate({ q: "semiconductors", page_size: 50 })) {
  console.log(article.publishedAt, article.title);
}

for article in news.articles.iterate({"q": "semiconductors", "page_size": 50}):
    print(article.publishedAt, article.title)

Polling for new articles

The poller uses indexed_from with sort=indexed_desc and yields each article as it's indexed. indexedAt is the time that article version was last indexed; persist the latest value and restart from it with a small overlap. See Keep a RAG index fresh.

const stop = new AbortController();
for await (const article of news.articles.pollIndexed({ since: lastIndexedAt, q: "climate", intervalMs: 60_000, signal: stop.signal })) {
  await vectorStore.upsert(article.id, article.content, { indexedAt: article.indexedAt });
}

for article in news.articles.poll_indexed(since=last_indexed_at, q="climate", interval_seconds=60):
    vector_store.upsert(article.id, article.content, indexed_at=article.indexedAt)

AI tool helpers

Ready-made tool definitions for OpenAI (Chat Completions and Responses) and Anthropic, plus a dispatcher that runs the model's tool calls against the API. Python also offers optional LangChain and LlamaIndex wrappers (pip install "newssearchapi[langchain]").

import { openAITools, anthropicTools, handleToolCall } from "@newssearchapi/sdk/tools";

// Pass openAITools / anthropicTools to your model, then execute its tool calls:
const result = await handleToolCall(call.name, call.arguments, news);

from newssearchapi.tools import openai_tools, anthropic_tools, handle_tool_call

# Pass openai_tools / anthropic_tools to your model, then execute its tool calls:
result = handle_tool_call(call.name, call.arguments, news)

Stuck or found a mistake?Email developer support