Parameters by endpoint

Title

Get articles with a specific title.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`title`	Search in article titles. Supports regular keywords, exact phrases (in quotes), and proximity search (with ~N). See examples below.	string	No	`Bitcoin` or `"breaking news"` or `"apple iphone"~5`
`ignore.title`	The title of articles to ignore.	string	No	`Ethereum`

Title Search Syntax (Apache Solr Style)

The title parameter supports three search modes:

1. Regular Keyword Search

title=bitcoin
title=AI,innovation

Searches for keywords in any order
✅ Expands with synonyms and morphology
Multiple terms with comma = OR logic

2. Exact Phrase Search (Solr Style)

title="breaking news"
title="Federal Reserve"

Searches for exact phrase in quotes
❌ No synonym/morphology expansion
Words must appear in exact order

3. Proximity Search (Solr Style)

title="apple iphone"~5
title="stock market"~3

Searches for words near each other
~N allows words to be N positions apart
Words must be in the correct order
Range: ~0 to ~10

Title Search Types Comparison

Search Type	Syntax	Synonym/Morphology Expansion	Use Case
Keyword	`title=bitcoin`	✅ Yes	General search, fuzzy matching
Phrase	`title="breaking news"`	❌ No	Exact phrases, proper names, quotes
Proximity	`title="apple iphone"~5`	❌ No	Words close together, flexible order
Prefix	`title_starts_with=...`	✅ Yes	Headlines starting with term
Suffix	`title_ends_with=...`	✅ Yes	Headlines ending with term
Pattern	`title_pattern=...`	✅ Yes	Substring matching (LIKE)

When to use phrase search ("..."):

Exact quotes or proper names (e.g., "United Nations", "Federal Reserve")
Specific event names (e.g., "Super Bowl 2024", "World Cup Final")
Company + product names (e.g., "Tesla Cybertruck")

When to use proximity search ("..."~N):

Related terms that should appear near each other
Allow some flexibility in word distance
Company mentions with context (e.g., "Apple earnings"~3)

When to use regular keyword search:

General discovery where word order doesn't matter
Want to find synonyms and variations
Broader content search

Workflow examples

Request for Positive Sentiment News:

This request retrieves news articles with "technology" in their titles.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=technology&api_key=YOUR_API_KEY"

Request for Articles with Multiple Title Keywords:

This request retrieves news articles with either "AI" or "innovation" in their titles.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=AI,innovation&api_key=YOUR_API_KEY"

Request for Articles with Titles Excluding Certain Words:

This request retrieves news articles that do not have "celebrity" in their titles.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?ignore.title=celebrity&api_key=YOUR_API_KEY"

Combined Title Filters for Specific News:

This request combines title filters to find articles about AI but not about job losses.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=AI&ignore.title=layoffs,job%20losses&api_key=YOUR_API_KEY"

Exact Phrase Search (Solr Style):

This request finds articles with the exact phrase "breaking news" in the title.

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="breaking news"&api_key=YOUR_API_KEY'

Phrase Search for Proper Names:

Search for exact organization or person names:

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="Federal Reserve"&api_key=YOUR_API_KEY'
curl -X GET 'https://api.apitube.io/v1/news/everything?title="United Nations"&api_key=YOUR_API_KEY'

Proximity Search with Slop (Solr Style):

Find articles where "Apple" and "iPhone" appear near each other:

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="Apple iPhone"~5&api_key=YOUR_API_KEY'

This matches titles like:

"Apple announces new iPhone features"
"Apple's latest iPhone release"
"iPhone innovation from Apple"

Comparison: Regular vs Phrase vs Proximity:

Regular search (finds keywords in any order, with synonyms):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=artificial%20intelligence&api_key=YOUR_API_KEY"

Matches: "Artificial Intelligence", "Intelligence in Artificial Systems", "AI", "intelligent artificial systems"

Phrase search (exact phrase only):

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="artificial intelligence"&api_key=YOUR_API_KEY'

Matches only: "Artificial Intelligence", "artificial intelligence" (exact phrase)

Proximity search (words near each other):

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="artificial intelligence"~3&api_key=YOUR_API_KEY'

Matches: "Artificial general intelligence", "Intelligence powered by artificial systems"

Company + Product Proximity Search:

Find articles mentioning company and product name near each other:

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="Tesla Cybertruck"~3&published_at.start=2024-01-01&api_key=YOUR_API_KEY'

Event Names with Exact Match:

Search for specific event names:

shell

curl -X GET 'https://api.apitube.io/v1/news/everything?title="Super Bowl 2024"&api_key=YOUR_API_KEY'
curl -X GET 'https://api.apitube.io/v1/news/everything?title="World Cup Final"&api_key=YOUR_API_KEY'

More examples can be found in the News API Examples page.

Languages

APITube has 60+ more languages available for the News API. You can specify the language of the articles you want to retrieve.

List of supported languages

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`language.code`	The language code of the articles you want to retrieve. `Supports up to 3 languages simultaneously, separated by commas (OR logic).`	string	No	`en`
`ignore.language.code`	The language code of the articles you want to exclude. `Supports up to 3 languages simultaneously, separated by commas (OR logic).`	string	No	`fr`

Workflow examples

Request to get news articles excluding those from France and in the French language:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?ignore.source.country.code=fr&ignore.language.code=fr&api_key=YOUR_API_KEY"

Request to get news articles in the English and French languages:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?language.code=en,fr&api_key=YOUR_API_KEY"

Multi-language Analysis with Source Filtering:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?language.code=en,ja,de&source.rank.opr.min=0.7&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Language-Specific Business News:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?language.code=zh,ko&category.id=medtop:04000000&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Multilingual Brand Sentiment Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?language.code=en,fr,de,ja&brand.name=Netflix&sentiment.overall.polarity=positive&published_at.start=2023-01-01&sort.by=published_at&api_key=YOUR_API_KEY"

Regional Language News Comparison:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?language.code=ar,he&category.id=medtop:11000000&published_at.start=2023-01-01&sort.by=sentiment.overall.score&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Parameter	Description	Type	Required	Example
`category.id`	The category ID of the articles. `Supports up to 3 categories simultaneously, separated by commas (OR logic).`	string	No	`314`
`ignore.category.id`	The category ID of the articles to ignore. `Supports up to 3 categories simultaneously, separated by commas (OR logic).`	string	No	`315`

Taxonomy	Description
`iptc`	IPTC

Topics

Get articles with a specific topic.

List of supported topics

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`topic.id`	The topic ID of the articles. `Supports up to 3 topics simultaneously, separated by commas (OR logic).`	integer	No	`1`
`ignore.topic.id`	The topic ID of the articles to ignore. `Supports up to 3 topics simultaneously, separated by commas (OR logic).`	integer	No	`2`

Workflow examples

Request to get news articles from a specific topic (e.g., "crypto_news"):

This request retrieves news articles that fall under the "crypto news" topic.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=crypto_news&api_key=YOUR_API_KEY"

Multi-Topic Sentiment Analysis:

This request analyzes sentiment across multiple related topics.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=climate_change,renewable_energy,carbon_emissions&sentiment.overall.polarity=positive&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Comparative Topic Analysis with Language Filtering:

This request compares coverage of different topics across specific languages.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=artificial_intelligence,machine_learning&language.code=en,de,jp&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Topic and Entity Intersection Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=cryptocurrency&entity.id=326,327&published_at.start=2023-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Topic-Based Expert Opinion Tracking:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=quantum_computing&author.name=Michio%20Kaku,Brian%20Greene&published_at.start=2020-01-01&sort.by=published_at&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Industries

Get articles with a specific industry.

List of supported industries

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`industry.id`	The industry ID of the articles. `Supports up to 3 industries simultaneously, separated by commas (OR logic).`	string	No	`246771`
`ignore.industry.id`	The industry ID of the articles to ignore. `Supports up to 3 industries simultaneously, separated by commas (OR logic).`	string	No	`246772`

Industry Sector Performance Tracking:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?industry.id=246771,246772&published_at.start=2023-01-01&published_at.end=2023-12-31&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

Cross-Industry Innovation Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?industry.id=246771,246772&title=innovation&sentiment.overall.polarity=positive&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Entities

Get articles with a specific entity.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`entity.id`	The entity ID of the articles. `Supports up to 3 entities simultaneously, separated by commas (OR logic).`	string	No	`314`
`ignore.entity.id`	The entity ID of the articles to ignore. `Supports up to 3 entities simultaneously, separated by commas (OR logic).`	string	No	`315`
`has_person`	Filter articles mentioning at least one person entity.	integer	No	`1`
`has_organization`	Filter articles mentioning at least one organization entity.	integer	No	`1`
`has_location`	Filter articles mentioning at least one location entity.	integer	No	`1`
`has_entities`	Filter articles with any entities (person/organization/location).	integer	No	`1`

Workflow examples

Request to get news articles about a specific entity (e.g., "Brad Pitt"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268&api_key=YOUR_API_KEY"

Request to get news articles about multiple entities (e.g., "Brad Pitt" and "Angelina Jolie"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268,1282301&api_key=YOUR_API_KEY"

Request to get news articles about an entity while ignoring another:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268&ignore.entity.id=315&api_key=YOUR_API_KEY"

Entity Correlation Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268,1282301&published_at.start=2023-01-01&published_at.end=2023-12-31&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Entity Mention Tracking Over Time:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268&published_at.start=2022-01-01&published_at.end=2023-12-31&per_page=100&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

Entity Co-occurrence Network Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268&entity.type=ORGANIZATION&published_at.start=2023-01-01&published_at.end=2023-12-31&sort.by=published_at&api_key=YOUR_API_KEY"

Entity Impact on Market Sentiment:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?entity.id=1278268,1282301&category.id=medtop:04000000&sentiment.overall.score.min=0.7&published_at.start=2023-01-01&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Request for articles mentioning persons:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_person=1&category.id=medtop:11000000&api_key=YOUR_API_KEY"

Request for articles mentioning organizations:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_organization=1&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Request for articles mentioning locations:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_location=1&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Request for articles with any entities:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_entities=1&is_verified_source=1&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Persons

Get articles with a specific person.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`person.name`	The person name of the articles. `Supports up to 3 persons simultaneously, separated by commas (OR logic).`	string	No	`Satoshi`
`ignore.person.name`	The person name of the articles to ignore. `Supports up to 3 persons simultaneously, separated by commas (OR logic).`	string	No	`Vitalik`

Workflow examples

Request to get news articles about a specific person (e.g., "Satoshi"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Satoshi&api_key=YOUR_API_KEY"

Request to get news articles about multiple people (e.g., "Satoshi" and "Vitalik"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Satoshi,Vitalik&api_key=YOUR_API_KEY"

Person Sentiment Analysis Across Sources:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Elon%20Musk&source.domain=cnn.com,foxnews.com,bbc.com&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Cross-reference Person with Organizations:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Tim%20Cook&organization.name=Apple&published_at.start=2023-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Public Figure Controversy Timeline:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Elon%20Musk&sentiment.overall.polarity=negative&published_at.start=2023-01-01&published_at.end=2023-12-31&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

Person Mention in Research Publications:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Stephen%20Hawking&published_at.start=2018-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Locations

Get articles from a specific location.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`location.name`	The location name of the articles. `Supports up to 3 locations simultaneously, separated by commas (OR logic).`	string	No	`Tokyo`
`ignore.location.name`	The location name of the articles to ignore. `Supports up to 3 locations simultaneously, separated by commas (OR logic).`	string	No	`New York`

Workflow examples

Request to get news articles from a specific location (e.g., "Tokyo"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=Tokyo&api_key=YOUR_API_KEY"

Request to get news articles from multiple locations (e.g., "Tokyo" and "New York"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=Tokyo,New York&api_key=YOUR_API_KEY"

Request to get news articles from a specific location and in a specific language (e.g., "Tokyo" and "Japanese") and ignore articles from "New York":

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=Tokyo&language.code=ja&ignore.location.name=New York&api_key=YOUR_API_KEY"

Geopolitical Event Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=France,Italy&category.id=medtop:11000000&published_at.start=2022-02-01&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

Multi-Location Business Impact Study:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=Silicon%20Valley,Shanghai,Bangalore&category.id=medtop:04000000&organization.name=Apple,Google,Microsoft&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Natural Disaster Coverage Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=Florida,Louisiana&title=hurricane&published_at.start=2022-06-01&published_at.end=2022-11-30&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

Tourism Sentiment Analysis by Location:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?location.name=Bali,Phuket,Maldives&sentiment.overall.polarity=positive&published_at.start=2023-01-01&sort.by=published_at&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Organizations

Get articles with a specific organization.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`organization.name`	The organization name of the articles. `Supports up to 3 organizations simultaneously, separated by commas (OR logic).`	string	No	`Google`
`ignore.organization.name`	The organization name of the articles to ignore. `Supports up to 3 organizations simultaneously, separated by commas (OR logic).`	string	No	`Apple`

Workflow examples

Request to get news articles about a specific organization (e.g., "Google"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Google&api_key=YOUR_API_KEY"

Request to get news articles about multiple organizations (e.g., "Google" and "Apple"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Google,Apple&api_key=YOUR_API_KEY"

Request to get news articles about an organization while ignoring another (e.g., "Google" and excluding "Apple"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Google&ignore.organization.name=Apple&api_key=YOUR_API_KEY"

Competitive Intelligence Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Tesla,Ford,Toyota&category.id=medtop:13000000&published_at.start=2023-01-01&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Organization Sentiment Tracking During Financial Events:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=JP%20Morgan&published_at.start=2023-04-01&published_at.end=2023-04-30&sort.by=published_at&sort.order=asc&category.id=medtop:04000000&api_key=YOUR_API_KEY"

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Microsoft,Google,Amazon&title=sustainability,ESG,green&published_at.start=2023-01-01&sentiment.overall.polarity=positive&api_key=YOUR_API_KEY"

Executive Leadership Transition Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Disney&title=CEO&published_at.start=2022-01-01&published_at.end=2023-12-31&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Netural Disasters

Get articles mentioning specific disasters.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`disaster.name`	The disaster name of the articles. `Supports up to 3 disasters simultaneously, separated by commas (OR logic).`	string	No	`Earthquake`
`ignore.disaster.name`	The disaster name of the articles to ignore. `Supports up to 3 disasters simultaneously, separated by commas (OR logic).`	string	No	`Flood`
`has_disaster`	Filter articles mentioning at least one disaster entity.	integer	No	`1`

Workflow examples

Request to get news articles about a specific disaster (e.g., "Earthquake"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disaster.name=Earthquake&api_key=YOUR_API_KEY"

Request to get news articles about multiple disasters (e.g., "Earthquake" and "Tsunami"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disaster.name=Earthquake,Tsunami&api_key=YOUR_API_KEY"

Request to get news articles about a disaster while ignoring another:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disaster.name=Hurricane&ignore.disaster.name=Tornado&api_key=YOUR_API_KEY"

Request for articles mentioning any disaster:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_disaster=1&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Disaster Impact Analysis by Region:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disaster.name=Wildfire&location.name=California&published_at.start=2023-01-01&sort.by=published_at&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Medical diseases

Get articles mentioning specific diseases.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`disease.name`	The disease name of the articles. `Supports up to 3 diseases simultaneously, separated by commas (OR logic).`	string	No	`COVID-19`
`ignore.disease.name`	The disease name of the articles to ignore. `Supports up to 3 diseases simultaneously, separated by commas (OR logic).`	string	No	`Flu`
`has_disease`	Filter articles mentioning at least one disease entity.	integer	No	`1`

Workflow examples

Request to get news articles about a specific disease (e.g., "COVID-19"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disease.name=COVID-19&api_key=YOUR_API_KEY"

Request to get news articles about multiple diseases:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disease.name=COVID-19,Influenza&api_key=YOUR_API_KEY"

Request to get news articles about a disease while ignoring another:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disease.name=Malaria&ignore.disease.name=Dengue&api_key=YOUR_API_KEY"

Request for articles mentioning any disease:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_disease=1&category.id=medtop:07000000&api_key=YOUR_API_KEY"

Disease Outbreak Tracking:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?disease.name=Measles&published_at.start=2024-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Events

Get articles mentioning specific events.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`event.name`	The event name of the articles. `Supports up to 3 events simultaneously, separated by commas (OR logic).`	string	No	`Olympics`
`ignore.event.name`	The event name of the articles to ignore. `Supports up to 3 events simultaneously, separated by commas (OR logic).`	string	No	`Super Bowl`
`has_event`	Filter articles mentioning at least one event entity.	integer	No	`1`

Workflow examples

Request to get news articles about a specific event (e.g., "Olympics"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?event.name=Olympics&api_key=YOUR_API_KEY"

Request to get news articles about multiple events:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?event.name=Olympics,World Cup&api_key=YOUR_API_KEY"

Request to get news articles about an event while ignoring another:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?event.name=Grammy Awards&ignore.event.name=Oscar&api_key=YOUR_API_KEY"

Request for articles mentioning any event:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_event=1&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Event Coverage Sentiment Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?event.name=CES&sentiment.overall.polarity=positive&published_at.start=2024-01-01&sort.by=sentiment.overall.score&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Brands

Get articles with a specific brand.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`brand.name`	The brand name of the articles. `Supports up to 3 brands simultaneously, separated by commas (OR logic).`	string	No	`Nike`
`ignore.brand.name`	The brand name of the articles to ignore. `Supports up to 3 brands simultaneously, separated by commas (OR logic).`	string	No	`Adidas`

Workflow examples

Request to get news articles about a specific brand (e.g., "Nike"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Nike&api_key=YOUR_API_KEY"

Request to get news articles about multiple brands (e.g., "Nike" and "Adidas"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Nike,Adidas&api_key=YOUR_API_KEY"

Request to get news articles about a brand while ignoring another (e.g., "Nike" and excluding "Adidas"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Nike&ignore.brand.name=Adidas&api_key=YOUR_API_KEY"

Brand Reputation Analysis Across Markets:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Samsung&source.country.code=us,kr,in&sort.by=sentiment.overall.score&sort.order=desc&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Brand Sponsorship Impact Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Rolex,Omega,Tag%20Heuer&title=sponsorship,tournament,championship&published_at.start=2023-01-01&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Brand Crisis Management Tracking:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Boeing&title=737%20MAX&sentiment.overall.polarity=negative&published_at.start=2019-03-01&published_at.end=2020-12-31&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Authors

Get articles with a specific author.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required
`author.id`	The author ID of the articles. `Supports up to 3 authors simultaneously, separated by commas (OR logic).`	string	No
`ignore.author.id`	The author ID of the articles to ignore. `Supports up to 3 authors simultaneously, separated by commas (OR logic).`	string	No
`author.name`	The author name of the articles. `Supports up to 3 authors simultaneously, separated by commas (OR logic).`	string	No
`ignore.author.name`	The author name of the articles to ignore. `Supports up to 3 authors simultaneously, separated by commas (OR logic).`	string	No
`has_author`	Filter articles with or without an attributed author. `Use 1 for articles with author, 0 for articles without author.`	integer	No

Workflow examples

Request to get news articles by a specific author (e.g., "John Doe"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=John Doe&api_key=YOUR_API_KEY"

Request to get news articles by multiple authors (e.g., "John Doe" and "Jane Doe"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=John Doe,Jane Doe&api_key=YOUR_API_KEY"

Request to get news articles by a specific author and in a specific language (e.g., "John Doe" and "English"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=John Doe&language.code=en&api_key=YOUR_API_KEY"

Author Expertise Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=Ezra%20Klein&category.id=medtop:11000000&sort.by=published_at&sort.order=desc&per_page=10&api_key=YOUR_API_KEY"

Cross-Source Author Contribution Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=Kara%20Swisher&source.domain=nytimes.com,wsj.com,vox.com&published_at.start=2020-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Author Sentiment Bias Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=George%20Stephanopoulos,Sean%20Hannity&organization.name=Biden%20Administration&published_at.start=2023-01-01&sort.by=sentiment.overall.score&api_key=YOUR_API_KEY"

Author Topic Evolution Tracking:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?author.name=Yuval%20Noah%20Harari&published_at.start=2018-01-01&published_at.end=2023-12-31&sort.by=published_at&sort.order=asc&per_page=100&api_key=YOUR_API_KEY"

Request for articles with attributed authors:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_author=1&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Request for articles without authors:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_author=0&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Sentiments

Get articles with a specific sentiment score.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

By sentiment score

You can use the sentiment.overall.score parameter to specify the overall sentiment score of the articles you want to retrieve.

Parameters

Parameter	Description	Type	Required	Example
`sentiment.overall.score`	The overall sentiment score of the articles.	float	No	`0.2`
`sentiment.overall.score.min`	The overall sentiment score of the articles.	float	No	`0.5`
`sentiment.overall.score.max`	The overall sentiment score of the articles.	float	No	`1.0`
`sentiment.overall.polarity`	The overall sentiment polarity of the articles.	string	No	`positive`

By sentiment polarity

Parameters

Parameter	Description	Type	Required
`positive`	Retrieve articles with positive sentiment.	string	No
`negative`	Retrieve articles with negative sentiment.	string	No
`neutral`	Retrieve articles with neutral sentiment.	string	No
`sentiment.mixed`	Filter articles with mixed sentiment (title/body differ).	integer	No
`sentiment.consistent`	Filter articles with consistent sentiment (title/body match).	integer	No
`is_clickbait`	Filter clickbait articles where title polarity differs from body AND title has strong sentiment (\|score\| > 0.5). Use `1` to find clickbait, `0` for consistent articles.	integer	No
`sentiment_gap.min`	Minimum sentiment gap between title and body scores. Range: 0-2.	float	No
`sentiment_gap.max`	Maximum sentiment gap between title and body scores. Range: 0-2.	float	No

Workflow examples

Request for Positive Sentiment News:

This request retrieves news articles that have been classified with a positive sentiment.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=positive&api_key=YOUR_API_KEY"

Request for Positive Sentiment News from a Specific Country:

This request fetches news articles with positive sentiment specifically from Japan

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=positive&source.country.code=jp&api_key=YOUR_API_KEY"

Request for Positive Sentiment News in the Last 24 Hours:

This request retrieves news articles with positive sentiment published in the last 24 hours.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=positive&published_at.start=2024-12-02&published_at.end=2024-12-03&api_key=YOUR_API_KEY"

Request for Articles with Positive Sentiment and a Specific Title:

This request retrieves news articles with positive sentiment that have "technology" in their titles.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=positive&title=technology&api_key=YOUR_API_KEY"

Multi-dimensional Sentiment Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.overall.score.min=0.7&category.id=medtop:04000000&organization.name=Tesla,SpaceX&published_at.start=2023-01-01&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Comparative Sentiment Analysis Across Markets:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=negative&source.country.code=us,uk,de&category.id=medtop:07000000&published_at.start=2023-01-01&published_at.end=2023-12-31&api_key=YOUR_API_KEY"

Sentiment Divergence Analysis by Source Type:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=climate_change&sentiment.overall.score.min=0.6&source.domain=scientific.journals,mainstream.news&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Product Review Sentiment Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=review&brand.name=Samsung%20Galaxy%20S23&sentiment.overall.score.min=-1.0&sentiment.overall.score.max=1.0&published_at.start=2023-01-01&sort.by=sentiment.overall.score&api_key=YOUR_API_KEY"

Request for articles with mixed sentiment:

This request finds articles where the title sentiment differs from body sentiment, useful for detecting clickbait or controversial framing.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.mixed=1&category.id=medtop:11000000&api_key=YOUR_API_KEY"

Request for articles with consistent sentiment:

This request finds articles where the title and body sentiment align, indicating more straightforward reporting.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment.consistent=1&has_author=1&api_key=YOUR_API_KEY"

Request for clickbait articles:

This request finds articles where the headline is sensationalized - title sentiment differs from body content and has strong emotional charge.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_clickbait=1&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Request for non-clickbait, trustworthy articles:

This request finds articles with consistent headline-to-content sentiment from verified sources.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_clickbait=0&is_verified_source=1&api_key=YOUR_API_KEY"

Filter by sentiment gap - find articles with significant title/body mismatch:

This request finds articles where the sentiment score differs by at least 0.5 between title and body.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment_gap.min=0.5&api_key=YOUR_API_KEY"

Filter by sentiment gap - find editorially consistent articles:

This request finds articles with minimal sentiment difference (gap < 0.2) between title and body.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sentiment_gap.max=0.2&source.rank.opr.min=5&api_key=YOUR_API_KEY"

Combined clickbait analysis for political news:

This request analyzes clickbait patterns in political coverage.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_clickbait=1&category.id=medtop:11000000&sentiment_gap.min=0.3&sort.by=sentiment.overall.score&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Media

Get articles with a specific media type and size.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`media.images.count`	The number of images in the articles.	integer	No	`2`
`media.videos.count`	The number of videos in the articles.	integer	No	`1`
`media.images.width.min`	The minimum width of the images.	integer	No	`200`
`media.images.width.max`	The maximum width of the images.	integer	No	`800`
`media.images.height.min`	The minimum height of the images.	integer	No	`200`
`media.images.height.max`	The maximum height of the images.	integer	No	`800`
`has_image`	Filter articles that have at least one image.	integer	No	`1`
`has_video`	Filter articles that have at least one video.	integer	No	`1`
`has_hq_images`	Filter articles with high-quality images (width >= 1200px).	integer	No	`1`
`is_media_rich`	Filter articles with both images and videos.	integer	No	`1`
`is_landscape_media`	Filter articles with landscape-oriented images (width > height).	integer	No	`1`
`is_portrait_media`	Filter articles with portrait-oriented images (height > width).	integer	No	`1`
`has_multiple_images`	Filter articles with 2 or more images.	integer	No	`1`
`has_fullhd_images`	Filter articles with Full HD images (width >= 1920px).	integer	No	`1`
`has_4k_images`	Filter articles with 4K images (width >= 3840px).	integer	No	`1`
`has_mobile_optimized_images`	Filter articles with mobile-optimized images (320-800px).	integer	No	`1`
`is_instagram_ready`	Filter articles with Instagram-ready images (1080px+, square/4:5 ratio).	integer	No	`1`
`is_twitter_card_ready`	Filter articles with Twitter Card ready images (800px+, landscape).	integer	No	`1`
`has_consistent_image_sizes`	Filter articles with consistent image sizes (variance < 200px).	integer	No	`1`
`has_thumbnail`	Filter articles with thumbnail images (width <= 300px).	integer	No	`1`
`has_social_share_image`	Filter articles with Open Graph compatible images (1200x630px+).	integer	No	`1`
`has_mixed_media`	Filter articles with both images and videos.	integer	No	`1`

Workflow examples

Request to get news articles with a specific number of images and videos:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.count=2&media.videos.count=1&api_key=YOUR_API_KEY"

Request to get news articles with images of a specific size:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.width.min=200&media.images.width.max=800&media.images.height.min=200&media.images.height.max=800&api_key=YOUR_API_KEY"

Rich Media Content Curation:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.count=3&media.videos.count=1&category.id=medtop:13000000&published_at.start=2023-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

High-Quality Visual News Aggregation:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.width.min=1200&media.images.height.min=800&media.images.count=2&sentiment.overall.polarity=positive&category.id=medtop:13000000&source.rank.opr.min=0.7&api_key=YOUR_API_KEY"

Video Content Analysis for Educational Topics:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.videos.count=2&title=education,learning,tutorial&published_at.start=2023-01-01&sort.by=media.videos.count&sort.order=desc&api_key=YOUR_API_KEY"

Interactive Media Content Curation:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.count=3&media.videos.count=1&media.interactive.count=1&category.id=medtop:13000000&published_at.start=2023-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

##### Request for media-rich articles:

```shell
curl -X GET "https://api.apitube.io/v1/news/everything?is_media_rich=1&category.id=medtop:13000000&api_key=YOUR_API_KEY"


##### Request for articles with high-quality images:

```shell
curl -X GET "https://api.apitube.io/v1/news/everything?has_hq_images=1&api_key=YOUR_API_KEY"

Request for multimedia-rich content:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_image=1&has_video=1&api_key=YOUR_API_KEY"

Request for landscape-oriented images (ideal for headers/banners):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_landscape_media=1&has_fullhd_images=1&api_key=YOUR_API_KEY"

Request for portrait-oriented images (ideal for mobile):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_portrait_media=1&has_mobile_optimized_images=1&api_key=YOUR_API_KEY"

Request for Instagram-ready content:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_instagram_ready=1&category.id=medtop:20000859&api_key=YOUR_API_KEY"

Request for Twitter Card optimized content:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_twitter_card_ready=1&has_social_share_image=1&api_key=YOUR_API_KEY"

Request for 4K image galleries:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_4k_images=1&has_multiple_images=1&category.id=medtop:01000000&api_key=YOUR_API_KEY"

Request for consistent visual content (curated galleries):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_consistent_image_sizes=1&has_multiple_images=1&api_key=YOUR_API_KEY"

Request for mixed media articles (images + videos):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_mixed_media=1&sort.by=media.images.count&sort.order=desc&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Source

Get articles with a specific source or sources.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`source.id`	The source ID of the articles. `Supports up to 3 domains simultaneously, separated by commas (OR logic).`	int	No	`314`
`ignore.source.id`	The source ID of the articles to ignore. `Supports up to 3 domains simultaneously, separated by commas (OR logic).`	int	No	`315`
`source.domain`	The source domain of the articles. `Supports up to 3 domains simultaneously, separated by commas (OR logic).`	string	No	`cnn.com`
`ignore.source.domain`	Ignore the source domain of the articles. `Supports up to 3 domains simultaneously, separated by commas (OR logic).`	string	No	`techcrunch.com`
`source.country.code`	The country code of the articles you want to retrieve. `Supports up to 3 country codes simultaneously, separated by commas (OR logic).`	string	No	`us`
`ignore.source.country.code`	The country code of the articles you want to exclude. `Supports up to 3 country codes simultaneously, separated by commas (OR logic).`	string	No	`fr`
`source.rank.opr.min`	The minimum Open Page Rank source rank. `Value from 0 to 7.`	string	No	`0.5`
`source.rank.opr.max`	The maximum Open Page Rank source rank. `Value from 0 to 7.`	string	No	`0.9`
`source.bias`	The media bias of the source. `Supports up to 3 biases simultaneously, separated by commas (OR logic).`	string	No	`left,center,right`
`ignore.source.bias`	The media bias of the source to ignore. `Supports up to 3 biases simultaneously, separated by commas (OR logic).`	string	No	`left,center,right`
`is_premium_source`	Filter premium sources with OPR >= 6.	integer	No	`1`
`is_verified_source`	Filter verified sources with OPR >= 5 and not duplicates.	integer	No	`1`

Workflow examples

Request to get news articles from a specific source (e.g., "cnn.com"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?source.domain=cnn.com&api_key=YOUR_API_KEY"

Request to get news articles from multiple sources (e.g., "cnn.com" and "bbc.com"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?source.domain=cnn.com,bbc.com&api_key=YOUR_API_KEY"

Request to get news articles from a specific source and in a specific language (e.g., "cnn.com" and "English"):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?source.domain=cnn.com&language.code=en&api_key=YOUR_API_KEY"

Request to get news articles with rank between 0.5 and 0.9:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?source.rank.opr.min=0.5&source.rank.opr.max=0.9&api_key=YOUR_API_KEY"

Cross-Regional Media Bias Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=climate_change&source.country.code=us,ru,cn&sort.by=sentiment.overall.score&published_at.start=2023-01-01&published_at.end=2023-12-31&api_key=YOUR_API_KEY"

High-Credibility Financial News Aggregation:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:04000000&source.rank.opr.min=0.8&source.domain=wsj.com,ft.com,bloomberg.com,reuters.com&published_at.start=2023-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Request for premium source articles:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_premium_source=1&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Request for verified source articles:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_verified_source=1&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Datetime

With the News API, you can specify the date range of the articles you want to retrieve. You can use the published_at.start and published_at.end parameters to specify the date range. The date range is inclusive, meaning that the articles published on the start date and the end date are included in the result.

All datetime math functions using AQL format.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`published_at.start`	The start date of the date range.	string	No	`2022-03-14`
`published_at.end`	The end date of the date range.	string	No	`2025-12-16`
`published_at`	The date of the articles you want to retrieve.	string	No	`2025-09-26`

Date Formats

You can use the following date formats to specify the date range:

Example	Description
`2025-01-02T15:04:05Z`	The date and time in the `YYYY-MM-DDTHH:MM:SSZ` format.
`2025-01-02`	The date in the `YYYY-MM-DD` format.
`02-01-2006`	The date in the `DD-MM-YYYY` format.
`2006-01-02T15:04:05-07:00`	The date and time in the `YYYY-MM-DDTHH:MM:SSZ` format.
`2006-01-02T15:04:05.000Z`	The date and time in the `YYYY-MM-DDTHH:MM:SS.MMMZ` format.
`Mon, 02 Jan 2006 15:04:05 MST`	The date and time in the `D, DD MMM YYYY HH:MM:SS Z` format.
`2006-01-02T15:04:05-07:00`	The date and time in the `YYYY-MM-DDTHH:MM:SSZ` format.
`2006-01-02T15:04:05Z07:00`	The date and time in the `YYYY-MM-DDTHH:MM:SSZ07:00` format. RFC3339 without the `T` separator.
`Mon, 02 Jan 2006 15:04:05 -0700`	The date and time in the `D, DD MMM YYYY HH:MM:SS Z` format. For example, `Mon, 02 Jan 2006 15:04:05 -0700`.

Workflow examples

Request to get news articles within a specific date range:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?published_at.start=2022-01-01&published_at.end=2022-01-31&api_key=YOUR_API_KEY"

Request to get news using a relative time range:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?published_at.start=2025-01-02&published_at.end=2006-01-04&api_key=YOUR_API_KEY"

Complex Date-Range Analysis with Precise Timestamps:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Federal%20Reserve&published_at.start=2023-03-21T14:00:00Z&published_at.end=2023-03-22T14:00:00Z&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Sorting

With the News API, you can sort the articles by the following parameters:

sort.by
sort.order

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters for sorting articles (sort.by)

By default, the articles are sorted by the published date in descending order. You can use the sort.by parameter to specify the sorting criteria.

Basic Sorting Parameters

Parameter	Description	Type	Required
`published_at`	Sort by the published date.	string	No
`created_at`	Sort by the creation date in the system.	string	No
`source.rank.opr`	Sort by the Open Page Rank source rank.	string	No
`read_time`	Sort by the article read time in minutes.	string	No
`sentences_count`	Sort by the number of sentences.	string	No
`paragraphs_count`	Sort by the number of paragraphs.	string	No
`characters_count`	Sort by the number of characters.	string	No

Sentiment Sorting Parameters

Parameter	Description	Type	Required
`sentiment.overall.score`	Sort by the overall sentiment score.	string	No
`sentiment.title.score`	Sort by the title sentiment score.	string	No
`sentiment.body.score`	Sort by the body sentiment score.	string	No

Media Sorting Parameters

Parameter	Description	Type	Required
`media.images.count`	Sort by the number of images.	string	No
`media.videos.count`	Sort by the number of videos.	string	No
`media.images.width.min`	Sort by the minimum image width.	string	No
`media.images.width.max`	Sort by the maximum image width.	string	No
`media.images.height.min`	Sort by the minimum image height.	string	No
`media.images.height.max`	Sort by the maximum image height.	string	No

Advanced Composite Sorting Parameters

These parameters use multi-factor algorithms to calculate sophisticated scores for different use cases:

Parameter	Description	Use Case	Max Score
`relevance`	Smart search ranking with query matching and quality signals	Search engines, query-based discovery	Variable
`engagement`	Viral potential predictor for social media	Social feeds, trending sections, viral detection	~139 pts
`quality`	Content quality evaluator for editorial curation	Premium content, editorial picks, quality filters	~80 pts
`controversy`	Polarization detector for debate-worthy topics	Discussion forums, hot topics, political analysis	~115 pts
`trust`	Credibility scorer for fact-checking and research	Academic research, fact-checking, news verification	~95 pts

Comparison Table

Metric	relevance	engagement	quality	controversy	trust
Best for	Search	Social	Editorial	Debates	Facts
Considers sentiment	Slight boost	Positive only	Positive only	Intensity	Neutral only
Source rank weight	Medium	Low	Medium	None	Very High
Timeliness weight	High	Very High	None	Medium	None
Media importance	Low	High	Medium	Videos only	None

Parameters for sorting order (sort.order)

By default, the articles are sorted in descending order. You can use the asc and desc parameters to specify the sorting order.

Parameter	Description	Type	Required
`asc`	Sort in ascending order.	string	No
`desc`	Sort in descending order.	string	No

Workflow examples

Request to get news articles sorted by the published date in ascending order:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

Request to get news articles sorted by the overall sentiment magnitude in descending order:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

Request to get the most viral/engaging articles:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=engagement&sort.order=desc&api_key=YOUR_API_KEY"

Request to get engaging breaking news with media:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_breaking=1&media.images.count.min=2&sort.by=engagement&sort.order=desc&api_key=YOUR_API_KEY"

Request to get articles from high-ranking sources sorted by source rank:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?source.rank.opr.min=5&sort.by=source.rank.opr&sort.order=desc&api_key=YOUR_API_KEY"

Request to get quick-read articles sorted by read time:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?read_time.max=5&sort.by=read_time&sort.order=asc&api_key=YOUR_API_KEY"

Request to get high-quality visual content sorted by image dimensions:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.count.min=3&sort.by=media.images.width.max&sort.order=desc&api_key=YOUR_API_KEY"

Multi-dimensional Content Ranking:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:13000000&source.rank.opr.min=0.7&sort.by=sentiment.overall.score&sort.order=desc&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Media-Rich Content Prioritization:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?media.images.count=2&media.videos.count=1&sort.by=media.images.count&sort.order=desc&category.id=medtop:13000000&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

In-Depth Analysis Articles:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:04000000&sort.by=paragraphs_count&sort.order=desc&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Sentiment-Based Content Discovery:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=artificial_intelligence&sort.by=sentiment.title.score&sort.order=desc&api_key=YOUR_API_KEY"

High-Quality Long-Form Content:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=quality&sort.order=desc&words_count.min=1000&api_key=YOUR_API_KEY"

Controversial/Polarizing Topics:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=controversy&sort.order=desc&category.id=medtop:11000000&api_key=YOUR_API_KEY"

Most Trustworthy News Sources:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=trust&sort.order=desc&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Combining Quality with Editorial Filters:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=quality&source.rank.opr.min=5&is_duplicate=0&api_key=YOUR_API_KEY"

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=engagement&published_at.start=2024-01-01&media.images.count.min=1&api_key=YOUR_API_KEY"

Credible Sources for Research:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?sort.by=trust&source.rank.opr.min=6&sentiment.overall.polarity=neutral&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Field Selection

Select specific fields to return in API responses, reducing payload size and improving performance.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required
`fl`	Comma-separated list of fields to return. Supports nested fields with dot notation (e.g., `source.name`).	string	No

Field Notation

Simple fields: id, title, body
Nested fields: Use dot notation to access nested properties
- source.name - returns only the source name
- source.domain - returns only the source domain
- sentiment.overall.score - returns only the overall sentiment score
- media.images.count - returns only the image count

Workflow examples

Request to get only ID and title:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title&api_key=YOUR_API_KEY"

Request to get article with specific source fields:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,source.name,source.domain,source.rank.opr&api_key=YOUR_API_KEY"

Request to get sentiment analysis data only:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,sentiment.overall.score,sentiment.title.score,sentiment.body.score&api_key=YOUR_API_KEY"

Request to get media information:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,media.images.count,media.videos.count&api_key=YOUR_API_KEY"

Minimal response for feed aggregation:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,published_at,source.name,source.domain&category.id=medtop:04000000&per_page=100&api_key=YOUR_API_KEY"

Sentiment monitoring with minimal data:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,sentiment.overall.score,sentiment.overall.polarity,published_at&organization.name=Tesla&api_key=YOUR_API_KEY"

Lightweight news ticker:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,source.name,published_at&is_breaking=1&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Performance optimization for large datasets:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?fl=id,title,source.domain&per_page=100&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Faceting

Faceting allows you to get aggregated counts of articles grouped by specific fields. This is useful for building filtered navigation, analytics dashboards, and understanding the distribution of your search results.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Default	Required
`facet`	Enable faceting. Set to `true` or `1` to enable.	boolean	false	No
`facet.field`	Comma-separated list of fields to facet on. Max 5 fields.	string	-	Yes (when facet=true)
`facet.limit`	Maximum number of facet values to return per field.	integer	10	No
`facet.mincount`	Minimum count for a facet value to be included.	integer	1	No

Source & Location Fields

Field	Description
`source.id`	Group by source media ID
`source.country.id`	Group by source country ID
`source.bias`	Group by source media bias (-3 to 3 scale)
`source.rank.opr`	Group by source OpenPageRank rating (1-10)

Content Classification Fields

Field	Description
`category.id`	Group by category ID
`topic.id`	Group by topic ID
`industry.id`	Group by industry ID

Language & Author Fields

Field	Description
`language.id`	Group by language ID
`author.id`	Group by author ID

Sentiment Analysis Fields

Field	Description
`sentiment.overall.polarity`	Group by overall sentiment polarity (-1=negative, 0=neutral, 1=positive)
`sentiment.title.polarity`	Group by title sentiment polarity (-1=negative, 0=neutral, 1=positive)
`sentiment.body.polarity`	Group by body sentiment polarity (-1=negative, 0=neutral, 1=positive)

Article Attributes Fields

Field	Description
`is_duplicate`	Group by duplicate status (0=unique, 1=duplicate)
`is_free`	Group by paywall status (0=behind paywall, 1=free access)
`is_important`	Group by importance/breaking news status (0=regular, 1=breaking/important)

Media Content Fields

Field	Description
`media.images.count`	Group by number of images in article (0, 1, 2, 3+)
`media.videos.count`	Group by number of videos in article (0, 1, 2+)

Reading Time Fields

Field	Description
`read_time`	Group by estimated reading time in minutes

Temporal Analysis Fields

Field	Description
`published.year`	Group by publication year (e.g., 2024, 2025)
`published.month`	Group by publication year-month (e.g., 202401, 202402)
`published.day_of_week`	Group by day of week (1=Monday, 7=Sunday)
`published.hour`	Group by hour of day (0-23)
`published.weekday`	Group by weekday vs weekend (`weekday`, `weekend`)
`published.time_of_day`	Group by time of day (`morning`, `afternoon`, `evening`, `night`)

Content Analysis Fields

Field	Description
`content.length`	Group by content length (`short` <3min, `medium` 3-8min, `long` >8min read time)
`sentiment.strength`	Group by sentiment intensity (`strong` >0.7, `moderate` 0.3-0.7, `neutral` <0.3)

Entity Fields

Field	Description
`entity.id`	Group by entity ID - useful for finding most mentioned entities

Response Format

When faceting is enabled, the response includes a facets object:

json

{
  "status": "ok",
  "results": [...],
  "facets": {
    "source.id": [
      {"value": 12345, "count": 150},
      {"value": 12346, "count": 120},
      {"value": 12347, "count": 95}
    ],
    "language.id": [
      {"value": 1, "count": 450},
      {"value": 2, "count": 120}
    ]
  }
}

Workflow examples

Basic faceting by source:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=source.id&api_key=YOUR_API_KEY"

Faceting with multiple fields:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=source.id,language.id,sentiment.overall.polarity&api_key=YOUR_API_KEY"

Faceting with custom limit:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=source.id&facet.limit=20&api_key=YOUR_API_KEY"

Faceting with minimum count filter:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=category.id&facet.mincount=10&api_key=YOUR_API_KEY"

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=bitcoin&facet=true&facet.field=source.id,sentiment.overall.polarity&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Faceting for language distribution analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Tesla&facet=true&facet.field=language.id,source.country.id&facet.limit=15&api_key=YOUR_API_KEY"

Faceting for sentiment analysis by source:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:04000000&facet=true&facet.field=source.id,sentiment.overall.polarity&facet.limit=10&api_key=YOUR_API_KEY"

Faceting for media bias distribution:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=climate_change&facet=true&facet.field=source.bias,source.country.id&api_key=YOUR_API_KEY"

Faceting for category distribution in top headlines:

shell

curl -X GET "https://api.apitube.io/v1/news/top-headlines?facet=true&facet.field=category.id,language.id&api_key=YOUR_API_KEY"

This example shows how to use facets to build a filter sidebar for your news application:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=AI&facet=true&facet.field=source.id,category.id,language.id,sentiment.overall.polarity&facet.limit=10&api_key=YOUR_API_KEY"

Temporal analysis - articles by hour of day:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=published.hour&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Temporal analysis - articles by day of week:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=published.day_of_week&category.id=medtop:15000000&api_key=YOUR_API_KEY"

Media richness analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=media.images.count,media.videos.count&category.id=medtop:13000000&api_key=YOUR_API_KEY"

Source quality distribution:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=source.rank.opr,is_duplicate&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Breaking news distribution by hour:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_important=1&facet=true&facet.field=published.hour,category.id&api_key=YOUR_API_KEY"

Content length analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=read_time&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Multi-sentiment analysis across content parts:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Tesla&facet=true&facet.field=sentiment.overall.polarity,sentiment.title.polarity,sentiment.body.polarity&api_key=YOUR_API_KEY"

Yearly trend analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=artificial_intelligence&facet=true&facet.field=published.year,published.month&published_at.start=2020-01-01&api_key=YOUR_API_KEY"

Content length distribution:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=content.length&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Weekday vs weekend publishing patterns:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?facet=true&facet.field=published.weekday,published.time_of_day&api_key=YOUR_API_KEY"

Sentiment strength analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Tesla&facet=true&facet.field=sentiment.strength,sentiment.overall.polarity&api_key=YOUR_API_KEY"

Most mentioned entities:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_entities=1&facet=true&facet.field=entity.id&facet.limit=20&api_key=YOUR_API_KEY"

Time of day publishing analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_breaking=1&facet=true&facet.field=published.time_of_day,published.weekday&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Range Faceting

Range faceting allows you to create histogram-style bucketed counts for numeric and date fields. This is perfect for building timelines, distribution charts, and analytics dashboards.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Default	Required
`facet.range`	Enable range faceting. Set to `true` or `1` to enable.	boolean	false	No
`facet.range.field`	Field to create ranges on.	string	-	Yes (when facet.range=true)
`facet.range.start`	Start value for the range (date or number).	string	-	Yes (when facet.range=true)
`facet.range.end`	End value for the range (date or number).	string	-	Yes (when facet.range=true)
`facet.range.gap`	Gap/interval between ranges. For dates: `1HOUR`, `1DAY`, `1WEEK`, `1MONTH`, `1YEAR`. For numbers: numeric value (e.g., `0.1`, `5`).	string	`1DAY`	No

Date Fields

Field	Description	Gap Examples
`published_at`	Article publication date	`1HOUR`, `1DAY`, `1WEEK`, `1MONTH`

Numeric Fields

Field	Description	Typical Range	Gap Examples
`sentiment.overall.score`	Overall sentiment score	-1 to 1	`0.1`, `0.25`, `0.5`
`sentiment.title.score`	Title sentiment score	-1 to 1	`0.1`, `0.25`, `0.5`
`sentiment.body.score`	Body sentiment score	-1 to 1	`0.1`, `0.25`, `0.5`
`read_time`	Reading time in minutes	0 to 60	`1`, `5`, `10`
`source.rank.opr`	Source OpenPageRank	0 to 10	`1`, `0.5`
`media.images.count`	Number of images	0 to 50	`1`, `5`
`media.videos.count`	Number of videos	0 to 20	`1`, `5`

Response Format

When range faceting is enabled, the response includes range buckets in the facets object:

json

{
  "status": "ok",
  "results": [...],
  "facets": {
    "published_at_ranges": [
      {"range_start": "2024-01-01", "range_end": "2024-01-08", "count": 1250},
      {"range_start": "2024-01-08", "range_end": "2024-01-15", "count": 1180},
      {"range_start": "2024-01-15", "range_end": "2024-01-22", "count": 1340}
    ]
  }
}

For numeric ranges:

json

{
  "status": "ok",
  "results": [...],
  "facets": {
    "sentiment.overall.score_ranges": [
      {"range_start": -1.0, "range_end": -0.5, "count": 450},
      {"range_start": -0.5, "range_end": 0.0, "count": 820},
      {"range_start": 0.0, "range_end": 0.5, "count": 1250},
      {"range_start": 0.5, "range_end": 1.0, "count": 680}
    ]
  }
}

Workflow examples

Date range faceting - articles per week:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=bitcoin&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-03-01&facet.range.gap=1WEEK&api_key=YOUR_API_KEY"

Date range faceting - articles per day:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Tesla&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-01-31&facet.range.gap=1DAY&api_key=YOUR_API_KEY"

Date range faceting - hourly distribution:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_breaking=1&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-15&facet.range.end=2024-01-16&facet.range.gap=1HOUR&api_key=YOUR_API_KEY"

Sentiment distribution analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Apple&facet.range=true&facet.range.field=sentiment.overall.score&facet.range.start=-1&facet.range.end=1&facet.range.gap=0.25&api_key=YOUR_API_KEY"

Reading time distribution:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:04000000&facet.range=true&facet.range.field=read_time&facet.range.start=0&facet.range.end=30&facet.range.gap=5&api_key=YOUR_API_KEY"

Source quality distribution:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?topic.id=artificial_intelligence&facet.range=true&facet.range.field=source.rank.opr&facet.range.start=0&facet.range.end=10&facet.range.gap=1&api_key=YOUR_API_KEY"

Combined regular and range faceting:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=climate&facet=true&facet.field=source.country.id,language.id&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-06-01&facet.range.gap=1MONTH&api_key=YOUR_API_KEY"

Media richness timeline:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?has_image=1&facet.range=true&facet.range.field=media.images.count&facet.range.start=1&facet.range.end=20&facet.range.gap=2&api_key=YOUR_API_KEY"

Building a sentiment timeline dashboard:

This example shows how to track sentiment changes over time for brand monitoring:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?brand.name=Nike&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-12-31&facet.range.gap=1MONTH&sentiment.overall.polarity=positive&api_key=YOUR_API_KEY"

Comparative time series analysis:

Run multiple queries to compare different entities over the same time period:

shell

# Tesla coverage timeline
curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Tesla&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-06-01&facet.range.gap=1WEEK&api_key=YOUR_API_KEY"

# Ford coverage timeline
curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Ford&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-06-01&facet.range.gap=1WEEK&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Pagination

With the News API, you can paginate the articles you want to retrieve.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Pagination with limit and offset

You can use the per_page and page parameters to specify the number of articles you want to retrieve and the starting point of the articles.

Parameters

Parameter	Description	Type	Required
`per_page`	The number of articles you want to retrieve.	integer	No
`page`	The starting point of the articles.	integer	No

Workflow examples

Request to get news articles with pagination:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?per_page=10&page=1&api_key=YOUR_API_KEY"

Efficient Large Dataset Retrieval:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:13000000&published_at.start=2023-01-01&published_at.end=2023-12-31&per_page=100&page=1&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Paginated Multi-criteria Search:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Amazon&sentiment.overall.polarity=positive&per_page=25&page=3&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Other filters

Other powerful filters are available to help you find the articles you need.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

0 is for false and 1 is for true.

Parameter	Description	Type	Required	Example
`is_duplicate`	Filter articles that are duplicates.	integer	No	`0`
`is_paywall`	Filter articles that are behind a paywall	integer	No	`0`
`is_breaking`	Filter articles that are breaking news.	integer	No	`1`
`read_time`	Filter articles by read time in minutes.	integer	No	`3`
`read_time.min`	Filter articles by minimum read time in minutes.	integer	No	`1`
`read_time.max`	Filter articles by maximum read time in minutes.	integer	No	`4`
`is_long_read`	Filter articles with read time >= 5 minutes.	integer	No	`1`
`is_short_read`	Filter articles with read time < 3 minutes.	integer	No	`1`

Readability Filters

Filter articles by reading difficulty, complexity, and target audience. These filters help you find content suitable for specific reader groups.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/entity

Parameters

Flesch-Kincaid Grade Level

The Flesch-Kincaid Grade Level indicates the US school grade level required to understand the text. Lower values indicate easier content.

Parameter	Description	Type	Required	Example
`readability.fk_grade`	Filter by exact Flesch-Kincaid grade level (0-30).	float	No	`8.5`
`readability.fk_grade.min`	Filter by minimum grade level.	float	No	`6`
`readability.fk_grade.max`	Filter by maximum grade level.	float	No	`12`

Flesch Reading Ease Score

The Flesch Reading Ease score ranges from 0-100, where higher scores indicate easier-to-read content.

Score Range	Difficulty	Audience
90-100	Very Easy	5th grade
80-89	Easy	6th grade
70-79	Fairly Easy	7th grade
60-69	Standard	8th-9th grade
50-59	Fairly Difficult	10th-12th grade
30-49	Difficult	College
0-29	Very Difficult	College graduate

Parameter	Description	Type	Required	Example
`readability.ease`	Filter by exact Flesch Reading Ease score (0-100).	float	No	`65`
`readability.ease.min`	Filter by minimum ease score (higher = easier).	float	No	`60`
`readability.ease.max`	Filter by maximum ease score.	float	No	`80`

Automated Readability Index (ARI)

The ARI produces a score that approximates the grade level needed to comprehend the text.

Parameter	Description	Type	Required	Example
`readability.ari`	Filter by exact ARI score (0-30).	float	No	`7.5`
`readability.ari.min`	Filter by minimum ARI score.	float	No	`5`
`readability.ari.max`	Filter by maximum ARI score.	float	No	`10`

Difficulty Level

Filter by categorical difficulty level.

Parameter	Description	Type	Required	Values
`readability.difficulty`	Filter by difficulty level.	string	No	`beginner`, `intermediate`, `advanced`, `expert`

Difficulty Level	Grade Range	Description
`beginner`	< 6	Easy to read, suitable for general audience
`intermediate`	6-10	Standard difficulty, high school level
`advanced`	10-14	Complex content, college level
`expert`	14+	Highly complex, professional/academic level

Target Audience

Filter by the intended target audience based on content complexity.

Parameter	Description	Type	Required	Values
`readability.audience`	Filter by target audience.	string	No	`children`, `general`, `professional`, `academic`

Audience	Description
`children`	Content suitable for children (grade < 6)
`general`	Content for general public (grade 6-10)
`professional`	Professional/business content (grade 10-14)
`academic`	Academic/scholarly content (grade 14+)

Reading Age

Filter by recommended reader age (calculated as grade level + 5).

Parameter	Description	Type	Required	Example
`readability.age`	Filter by exact reading age (6-22).	integer	No	`14`
`readability.age.min`	Filter by minimum reading age.	integer	No	`12`
`readability.age.max`	Filter by maximum reading age.	integer	No	`16`

Convenience Filters

Parameter	Description	Type	Required	Example
`is_easy_read`	Filter easy-to-read articles (Flesch Reading Ease ≥ 60).	integer	No	`1`
`is_difficult_read`	Filter difficult articles (Flesch Reading Ease < 40).	integer	No	`1`

Examples

Get easy-to-read articles for general audience:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_easy_read=1&readability.audience=general&api_key=YOUR_API_KEY"

Get beginner-level content about technology:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&topic.id=technology&api_key=YOUR_API_KEY"

Get articles suitable for teenagers (age 12-16):

shell

curl -X GET "https://api.apitube.io/v1/news/everything?readability.age.min=12&readability.age.max=16&api_key=YOUR_API_KEY"

Get professional-level business news:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?readability.audience=professional&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Get highly readable content (FRE 70-90) for content curation:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?readability.ease.min=70&readability.ease.max=90&is_duplicate=0&api_key=YOUR_API_KEY"

Get academic-level articles about science:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?readability.difficulty=expert&readability.audience=academic&category.id=medtop:13000000&api_key=YOUR_API_KEY"

Combine with grade level for educational content:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?readability.fk_grade.min=8&readability.fk_grade.max=12&category.id=medtop:13000000&api_key=YOUR_API_KEY"

Other Filters

High-Quality Content Filtering:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_duplicate=0&is_paywall=0&source.rank.opr.min=0.7&category.id=medtop:04000000&published_at.start=2023-01-01&api_key=YOUR_API_KEY"

Premium Content Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_paywall=1&source.domain=wsj.com,ft.com,economist.com&category.id=medtop:04000000&published_at.start=2023-01-01&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

Request for long-read articles:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_long_read=1&category.id=medtop:04000000&api_key=YOUR_API_KEY"

Request for quick-read articles:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_short_read=1&api_key=YOUR_API_KEY"

Only Breaking News Monitoring:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?is_breaking=1&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Export articles

With the News API, you can export the articles in formats such as JSON, XML, XLSX, CSV and TSV.

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/article

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Required	Example
`export`	The format in which you want to export.	string	No	`json`

Formats

Format	Description
`json`	JSON
`xml`	XML
`xlsx`	XLSX
`csv`	CSV
`tsv`	TSV

Data Export for Financial Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:04000000&published_at.start=2023-01-01&published_at.end=2023-12-31&export=xlsx&api_key=YOUR_API_KEY" -o financial_news_2023.xlsx

CSV Export for Sentiment Analysis:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Amazon,Microsoft,Google&published_at.start=2023-01-01&published_at.end=2023-12-31&sort.by=sentiment.overall.score&sort.order=desc&export=csv&api_key=YOUR_API_KEY" -o tech_sentiment_2023.csv

More examples can be found in the News API Examples page.

Get single article

Get a single article by its ID.

Endpoints

/v1/news/article

Parameters

Parameter	Description	Type	Required	Example
`id`	The ID of the article you want to retrieve. `Supports up to 100 articles simultaneously, separated by commas (OR logic).`	string	Yes	`314`

Workflow examples

Request to get a single article by its ID:

shell

curl -X GET "https://api.apitube.io/v1/news/article?id=314&api_key=YOUR_API_KEY"

Detailed Article Export in Multiple Formats:

shell

curl -X GET "https://api.apitube.io/v1/news/article?id=314&export=json&api_key=YOUR_API_KEY" -o article_314.json
curl -X GET "https://api.apitube.io/v1/news/article?id=314&export=xml&api_key=YOUR_API_KEY" -o article_314.xml

More examples can be found in the News API Examples page.

API Usage

Check your API key balance and usage information.

Endpoints

/v1/balance

Parameters

The endpoint accepts the API key in one of three ways:

Method	Description	Example
Authorization header	Bearer token in Authorization header	`Authorization: Bearer YOUR_KEY`
X-API-Key header	Custom header with API key	`X-API-Key: YOUR_KEY`
Query parameter	API key as query string parameter	`?api_key=YOUR_KEY`

Response

Field	Description	Type	Example
`api_key`	Your API key	string	`abc123`
`points`	Remaining credits/points on your account	integer	`1500`
`plan`	Your current subscription plan	string	`basic`

Rate Limiting

This endpoint is rate-limited to 5 requests per minute per API key to prevent abuse.

If you exceed the rate limit, you will receive a 429 Too Many Requests response with the following headers:

Header	Description
x-ratelimit-limit	Maximum number of requests allowed (30)
x-ratelimit-remaining	Number of requests remaining in the current time window
x-ratelimit-reset	Seconds until the rate limit resets
retry-after	Seconds to wait before making another request

Workflow examples

Check API key balance using query parameter:

shell

curl -X GET "https://api.apitube.io/v1/balance?api_key=YOUR_API_KEY"

Check API key balance using Authorization header:

shell

curl -X GET "https://api.apitube.io/v1/balance" -H "Authorization: Bearer YOUR_API_KEY"

Check API key balance using X-API-Key header:

shell

curl -X GET "https://api.apitube.io/v1/balance" -H "X-API-Key: YOUR_API_KEY"

Example response:

json

{
  "api_key": "YOUR_API_KEY",
  "points": 1500,
  "plan": "basic"
}

Example rate limit error response:

json

{
  "statusCode": 429,
  "errors": [
    {
      "code": "ER0203",
      "message": "Rate limit exceeded. You can make 30 requests per minute. Try again in 1 minute."
    }
  ]
}

Highlighting

Highlighting allows you to get text snippets with matching search terms highlighted. This is useful for displaying search results with context and making it easy for users to see why each result matched.

Advanced Features:

Automatically expands search terms using synonyms and morphology from the dictionary
Highlights variations of your search terms (e.g., searching for "run" will also highlight "running", "runner", "ran")
Supports multilingual highlighting with language-specific dictionaries

Endpoints

/v1/news/everything

/v1/news/top-headlines

/v1/news/story

/v1/news/category

/v1/news/topic

/v1/news/industry

/v1/news/entity

Parameters

Parameter	Description	Type	Default	Required
`hl`	Enable highlighting. Set to `true` or `1` to enable.	boolean	false	No
`hl.fl`	Comma-separated list of fields to highlight. Max 5 fields.	string	`title,description`	No
`hl.fragsize`	Maximum size of each highlighted snippet in characters (50-500).	integer	150	No
`hl.snippets`	Maximum number of snippets to return per field (1-10).	integer	3	No
`hl.tag.pre`	Opening tag for highlighted terms.	string	`<em>`	No
`hl.tag.post`	Closing tag for highlighted terms.	string	`</em>`	No

Supported Highlight Fields

Field	Description
`title`	Article title
`description`	Article description/summary
`body`	Full article body text

Response Format

When highlighting is enabled and matches are found, the response includes a highlighting object:

json

{
  "status": "ok",
  "results": [...],
  "highlighting": {
    "12345": {
      "title": [
        "Breaking: <em>Bitcoin</em> reaches new all-time high"
      ],
      "description": [
        "...The price of <em>Bitcoin</em> surged past $100,000 today, marking a historic milestone for the <em>cryptocurrency</em>..."
      ]
    },
    "12346": {
      "title": [
        "<em>Bitcoin</em> ETF approval drives market rally"
      ]
    }
  }
}

The highlighting object is keyed by article ID, and each article contains arrays of highlighted snippets for the requested fields.

Workflow examples

Basic highlighting for search results:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=bitcoin&hl=true&api_key=YOUR_API_KEY"

Highlighting with custom fields:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=artificial%20intelligence&hl=true&hl.fl=title,description,body&api_key=YOUR_API_KEY"

Highlighting with larger snippets:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=climate%20change&hl=true&hl.fragsize=300&hl.snippets=5&api_key=YOUR_API_KEY"

Custom highlight tags for HTML:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=Tesla&hl=true&hl.tag.pre=<mark>&hl.tag.post=</mark>&api_key=YOUR_API_KEY"

Custom highlight tags for Markdown:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=SpaceX&hl=true&hl.tag.pre=**&hl.tag.post=**&api_key=YOUR_API_KEY"

Combined with other filters:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=Apple&organization.name=Apple&hl=true&hl.fl=title,description&sentiment.overall.polarity=positive&published_at.start=2024-01-01&api_key=YOUR_API_KEY"

Highlighting for entity search:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?person.name=Elon%20Musk&hl=true&hl.fl=title,body&hl.snippets=5&api_key=YOUR_API_KEY"

Automatic term expansion with dictionary:

This example demonstrates how highlighting automatically expands search terms using synonyms and morphology. Searching for "innovation" will also highlight related terms like "innovative", "innovate", "innovator", etc.

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=innovation&hl=true&hl.fl=title,description&api_key=YOUR_API_KEY"

Response will highlight all morphological variations:

"...driving innovation in technology..."
"...most innovative companies..."
"...continues to innovate..."

Building a search results page:

This example shows how to use highlighting with field selection for a search interface:

shell

curl -X GET "https://api.apitube.io/v1/news/everything?title=AI&fl=id,title,description,published_at,source.name&hl=true&hl.fl=title,description&per_page=20&api_key=YOUR_API_KEY"

More examples can be found in the News API Examples page.

Error Codes

For a complete reference of all API error codes, see the API Error Codes page.

Parameters by endpoint ​

Title ​

Endpoints ​

Parameters ​

Title Search Syntax (Apache Solr Style) ​

1. Regular Keyword Search ​

2. Exact Phrase Search (Solr Style) ​

3. Proximity Search (Solr Style) ​

Title Search Types Comparison ​

Workflow examples ​

Request for Positive Sentiment News: ​

Request for Articles with Multiple Title Keywords: ​

Request for Articles with Titles Excluding Certain Words: ​

Combined Title Filters for Specific News: ​

Exact Phrase Search (Solr Style): ​

Phrase Search for Proper Names: ​

Proximity Search with Slop (Solr Style): ​

Comparison: Regular vs Phrase vs Proximity: ​

Company + Product Proximity Search: ​

Event Names with Exact Match: ​

Languages ​

Endpoints ​

Parameters ​

Workflow examples ​

Request to get news articles excluding those from France and in the French language: ​

Request to get news articles in the English and French languages: ​

Multi-language Analysis with Source Filtering: ​

Language-Specific Business News: ​

Multilingual Brand Sentiment Analysis: ​

Regional Language News Comparison: ​

Categories ​

Endpoints ​

Parameters ​

List of supported categories taxonomy ​

Workflow examples ​

Request to get news articles from a specific category (e.g., "Sport"): ​

Request for Articles in Multiple Categories: ​

Request for Articles in a Category and Filtered by Language: ​

Category Time-Series Analysis: ​

Category-Based Media Analysis: ​

Cross-Category Sentiment Comparison: ​

Topics ​

Endpoints ​

Parameters ​

Workflow examples ​

Request to get news articles from a specific topic (e.g., "crypto_news"): ​

Multi-Topic Sentiment Analysis: ​

Comparative Topic Analysis with Language Filtering: ​

Topic and Entity Intersection Analysis: ​

Topic-Based Expert Opinion Tracking: ​

Industries ​

Endpoints ​

Parameters ​

Industry Sector Performance Tracking: ​

Cross-Industry Innovation Analysis: ​

Entities ​

Endpoints ​

Parameters ​

Workflow examples ​

Request to get news articles about a specific entity (e.g., "Brad Pitt"): ​

Request to get news articles about multiple entities (e.g., "Brad Pitt" and "Angelina Jolie"): ​

Request to get news articles about an entity while ignoring another: ​

Entity Correlation Analysis: ​

Entity Mention Tracking Over Time: ​

Entity Co-occurrence Network Analysis: ​

Entity Impact on Market Sentiment: ​

Request for articles mentioning persons: ​

Request for articles mentioning organizations: ​

Request for articles mentioning locations: ​

Request for articles with any entities: ​

Persons ​

Endpoints ​

Parameters ​

Workflow examples ​

Request to get news articles about a specific person (e.g., "Satoshi"): ​

Request to get news articles about multiple people (e.g., "Satoshi" and "Vitalik"): ​

Person Sentiment Analysis Across Sources: ​

Cross-reference Person with Organizations: ​

Public Figure Controversy Timeline: ​

Person Mention in Research Publications: ​

Parameters by endpoint

Title

Endpoints

Parameters

Title Search Syntax (Apache Solr Style)

1. Regular Keyword Search

2. Exact Phrase Search (Solr Style)

3. Proximity Search (Solr Style)

Title Search Types Comparison

Workflow examples

Request for Positive Sentiment News:

Request for Articles with Multiple Title Keywords:

Request for Articles with Titles Excluding Certain Words:

Combined Title Filters for Specific News:

Exact Phrase Search (Solr Style):

Phrase Search for Proper Names:

Proximity Search with Slop (Solr Style):

Comparison: Regular vs Phrase vs Proximity:

Company + Product Proximity Search:

Event Names with Exact Match:

Languages

Endpoints

Parameters

Workflow examples

Request to get news articles excluding those from France and in the French language:

Request to get news articles in the English and French languages:

Multi-language Analysis with Source Filtering:

Language-Specific Business News:

Multilingual Brand Sentiment Analysis:

Regional Language News Comparison:

Categories

Endpoints

Parameters

List of supported categories taxonomy

Workflow examples

Request to get news articles from a specific category (e.g., "Sport"):

Request for Articles in Multiple Categories:

Request for Articles in a Category and Filtered by Language:

Category Time-Series Analysis:

Category-Based Media Analysis:

Cross-Category Sentiment Comparison:

Topics

Endpoints

Parameters

Workflow examples

Request to get news articles from a specific topic (e.g., "crypto_news"):

Multi-Topic Sentiment Analysis:

Comparative Topic Analysis with Language Filtering:

Topic and Entity Intersection Analysis:

Topic-Based Expert Opinion Tracking:

Industries

Endpoints

Parameters

Industry Sector Performance Tracking:

Cross-Industry Innovation Analysis:

Entities

Endpoints

Parameters

Workflow examples

Request to get news articles about a specific entity (e.g., "Brad Pitt"):

Request to get news articles about multiple entities (e.g., "Brad Pitt" and "Angelina Jolie"):

Request to get news articles about an entity while ignoring another:

Entity Correlation Analysis:

Entity Mention Tracking Over Time:

Entity Co-occurrence Network Analysis:

Entity Impact on Market Sentiment:

Request for articles mentioning persons:

Request for articles mentioning organizations:

Request for articles mentioning locations:

Request for articles with any entities:

Persons

Endpoints

Parameters

Workflow examples

Request to get news articles about a specific person (e.g., "Satoshi"):

Request to get news articles about multiple people (e.g., "Satoshi" and "Vitalik"):

Person Sentiment Analysis Across Sources:

Cross-reference Person with Organizations:

Public Figure Controversy Timeline:

Person Mention in Research Publications: