APITube Documentation

Appearance

Sign inGet started

Glossary ​

This page defines the core terms used across the APITube News API. Each definition is self-contained, so you can reference a single concept without reading the rest of the documentation.

News API ​

The APITube News API is a RESTful HTTP API that returns news articles aggregated from more than 500,000 verified sources worldwide. Every article is enriched with metadata such as language, category, topic, industry, named entities, sentiment, and source information, so you can filter and analyze coverage programmatically.

API key ​

An API key is the credential that authenticates your requests to the News API. You obtain it from your APITube account and pass it either as the api_key query parameter or in the X-API-Key request header. Every request must include a valid API key.

Bearer token ​

A Bearer token is an alternative authentication method where the API key is sent in the Authorization: Bearer YOUR_API_KEY header instead of a query parameter. It is functionally equivalent to passing the API key directly and is useful when you prefer header-based authentication.

Endpoint ​

An endpoint is a specific URL path that exposes one operation of the News API. The main endpoints are /v1/news/everything (search all articles), /v1/news/top-headlines, /v1/news/story, /v1/news/article, /v1/news/trends, /v1/news/stream, the /v1/suggest/* autocomplete endpoints, and /v1/balance.

Article ​

An article is the core object returned by the News API: a single news item with fields such as title, body, URL, publication date, author, language, source, and all enrichment data. Each article has a unique Article ID that can be used to fetch it directly or to retrieve its related story.

Story ​

A story is a cluster of articles that cover the same event from different sources. The /v1/news/story endpoint returns all articles grouped under one story by Article ID, which lets you deduplicate coverage and see how a single event is reported across publishers.

Entity ​

An entity is a named thing — a person, organization, location, brand, or product — automatically extracted from article text using named-entity recognition (NER). Entities are identified by entity.id, carry a entity.type, and are linked to a Wikidata ID, so you can filter articles by the specific real-world subjects they mention.

Sentiment ​

Sentiment is the automated assessment of the emotional tone of an article. The News API exposes both a polarity (sentiment.overall.polarity: positive, negative, or neutral) and a numeric score (sentiment.overall.score), which you can use to filter or sort articles by how favorable or unfavorable their coverage is.

Category ​

A category is a subject classification based on the IPTC Media Topics taxonomy. Categories are referenced by category.id using medtop: codes (for example medtop:04000000 for finance), which provide a standardized way to filter articles by broad subject area.

Topic ​

A topic is a thematic grouping that is narrower and more specific than a category. Topics are referenced by topic.id (for example industry.crypto_news) and let you target articles about a focused subject such as cryptocurrency, green energy, or artificial intelligence.

Industry ​

An industry is an economic-sector classification used to group articles by the business domain they relate to. Industries are referenced by industry.id and are useful for tracking coverage of a specific sector such as technology, healthcare, or energy.

Source ​

A source is the publisher or website an article was aggregated from. Sources have identifiers (source.id), a domain (source.domain), and a country (source.country.code), which you can use to include or exclude specific publishers from your results.

Source rank ​

Source rank is an authority score for a publisher based on Open Page Rank, exposed through source.rank.opr. Higher values indicate more authoritative domains; filtering with source.rank.opr.min lets you restrict results to higher-quality sources.

Trends are aggregated counts of how often a field's values appear across matching articles, returned by the /v1/news/trends endpoint. You can rank the most popular entities, categories, topics, industries, or sources, and optionally compute trending scores and historical comparisons.

Pagination ​

Pagination controls how results are split across multiple responses. The per_page parameter sets how many items are returned per request, and offset sets how many items to skip, so you can iterate through large result sets page by page.

Sort order ​

Sort order defines how results are ordered. The sort.by parameter chooses the field to sort on (for example published_at or sentiment.overall.score), and sort.order chooses the direction (asc for ascending or desc for descending).

Language code ​

A language code is the ISO 639 two-letter identifier of an article's language, used with the language.code parameter (for example en for English). The News API supports 60+ languages, and up to three codes can be combined in one request using comma-separated OR logic.

Credit and balance ​

A credit is the usage unit consumed by API requests under your subscription plan. The /v1/balance endpoint reports the remaining credits on your API key, which lets you monitor consumption and avoid hitting your plan limit.

Rate limit ​

A rate limit is the maximum number of requests your API key may make in a given window. The current state is returned in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers, so clients can throttle requests before being blocked.

SSE stream ​

Server-Sent Events (SSE) streaming delivers newly published articles in real time over a persistent HTTP connection via the /v1/news/stream endpoint. Instead of polling repeatedly, your client receives matching articles as they are aggregated.

Reference endpoints ​

Reference endpoints (/v1/people, /v1/companies, /v1/journalists) are searchable directories of the entities behind the news, rather than the articles themselves. Each profile combines descriptive metadata with a coverage block and the latest articles, letting you look up a person, company, source, or journalist and pivot to their coverage.

Coverage ​

Coverage is the aggregated view of how an entity is reported on, returned in the coverage object of a reference profile. It includes the total article count, first/last seen dates, sentiment breakdown, a monthly timeline, momentum, and top sources, topics, countries, languages and related entities.

Momentum ​

Momentum measures how attention to an entity is changing. It compares the number of mentions in the last 30 days against the previous 30 days and reports the percentage change (change_pct), making it easy to spot entities that are trending up or cooling down.

Related entities are the entities most frequently co-mentioned in the same articles as the subject (the related_entities field of a person or company profile). They reveal associations — for example, a politician's frequent co-mentions or a company's partners and competitors.

Open PageRank (OPR) ​

Open PageRank is a 0–10 authority score for a publisher's domain, exposed as source.rank.opr and in the rank.opr field of a source profile. Higher values indicate more authoritative sources; it is the basis of source rank.

Journalist normalization ​

Journalist normalization merges article bylines that share the same name into a single journalist record, collecting all of their outlets. Because matching is by name, distinct people sharing a name (and generic bylines such as admin) may be merged — finer disambiguation is planned for a future release.