Concepts
How NewsRank structures and exposes news data. Understanding these concepts will help you get the most out of the API.
How It Works
NewsRank continuously processes news from thousands of sources. Here's what happens before data reaches the API:
Sources
Thousands of outlets monitored in real-time
Articles
Full content, metadata, and summaries
Entities
People, orgs, and locations tagged
Stories
Related articles grouped by event
Enrichment
Summaries, Wikipedia links, rankings
API
Everything queryable via REST
Real-time
Live updates via WebSocket
Paid plans can also receive updates in real-time via WebSocket.
Articles vs Stories
Articles and stories are the two primary data types. An article is a single report from one source. A story is a cluster of articles about the same event.
| Articles | Stories | |
|---|---|---|
| Scope | Single report from one source | Cluster of related articles |
| Source | One outlet | Multiple outlets |
| Content | Full extracted text, original title | AI-synthesized headline & summary |
| Best for | Feed, search, source-specific views | Overview, trending, multi-source view |
| Endpoint | /v1/articles | /v1/stories |
Entity System
NewsRank automatically identifies people, organizations, and locations mentioned across articles. Entities are enriched with metadata from Wikipedia and Wikidata.
Entity Types
Person
Politicians, CEOs, public figures. Sub-categories distinguish politicians from other people.
Organization
Companies, government agencies, NGOs. Sub-categories include companies, political parties, and more.
Location
Countries, cities, regions. Geo-coded when possible for map-based visualizations.
Enrichment
Each entity includes a description from Wikipedia, a wikipedia_url, and wikidata_id for cross-referencing with other datasets. Entity article counts and mention frequency are updated in real-time.
Search Modes
NewsRank offers multiple search approaches depending on your use case.
| Mode | Endpoint | Use When |
|---|---|---|
| Article Search | /v1/search | Full-text search across articles with entity detection |
| Autocomplete | /v1/search/suggest | Building search-as-you-type UIs with instant suggestions |
| Entity Lookup | /v1/entities | Finding specific people, orgs, or locations by name or type |
Graph Endpoints
Graph endpoints expose relationship data between entities, stories, and topics. Use these for network visualizations, discovering related entities, and understanding how news events connect.
Entity Graph
Network of connections between entities that appear together in articles. Shows co-occurrence strength and shared article count.
/v1/graph/entities
Story-Entity Map
Maps which entities appear in which stories. Useful for understanding who and what is involved in each news event.
/v1/graph/story-entities
Pagination
All list endpoints support offset and limit parameters. Responses include a total field so you know how many results exist.
| Parameter | Type | Description |
|---|---|---|
| offset | integer | Number of results to skip (default: 0) |
| limit | integer | Max results to return (default: 20, max: 100) |
| total | integer | Total matching results (in response) |
// Paginate through all articles
let offset = 0;
const limit = 50;
let allArticles = [];
while (true) {
const res = await fetch(
`https://api.newsrank.ai/v1/articles?limit=${limit}&offset=${offset}`,
{ headers: { "Authorization": "Bearer nrf_your_api_key" } }
);
const data = await res.json();
allArticles.push(...data.articles);
if (offset + limit >= data.total) break;
offset += limit;
}Filtering Patterns
Most endpoints support a common set of filters. Combine them to narrow down results precisely.
| Filter | Example | Available On |
|---|---|---|
| category | politics | Articles, Stories |
| since / until | 2026-02-01T00:00:00Z | Articles, Stories, Search |
| source | reuters | Articles |
| type | person | Entities |
| q | climate change | Search, Autocomplete |
# Common filtering patterns
import requests
headers = {"Authorization": "Bearer nrf_your_api_key"}
base = "https://api.newsrank.ai/v1"
# Filter articles by category and date range
articles = requests.get(f"{base}/articles", headers=headers, params={
"category": "politics",
"since": "2026-02-01T00:00:00Z",
"until": "2026-02-24T23:59:59Z",
"limit": 20
}).json()
# Search with entity awareness
results = requests.get(f"{base}/search", headers=headers, params={
"q": "Elon Musk Tesla",
"limit": 10
}).json()
# Get entities of a specific type
politicians = requests.get(f"{base}/entities", headers=headers, params={
"type": "person",
"subcategory": "politician",
"limit": 20
}).json()Response Format
All API responses are JSON. List endpoints wrap results in a named array (e.g., "articles", "stories") alongside pagination fields. Single-resource endpoints return the object directly.
Paginated response structure:
{ "articles": [...], "total": 1842, "offset": 0, "limit": 20 }Error response structure:
{ "error": "Invalid API key", "status": 401 }