APITube News

Search news articles using APITube News API with comprehensive filtering.

IMPORTANT INSTRUCTIONS FOR QUERY CONSTRUCTION:

1. DO NOT use dots in parameter names directly in the root object. Use nested objects instead.

2. The system will automatically convert nested objects to dot notation for the API. Example: Use { language: { code: "en" } } instead of { "language.code": "en" }.

3. For multiple values in one parameter, use COMMA separation (e.g., "en,ru,fr" for multiple languages).

4. Integer filters (has_*, is_*) accept ONLY 0 or 1 (e.g., has_image=1, is_duplicate=0).

5. Date format: ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ).

6. Sentiment scores range: -1.0 (negative) to 1.0 (positive).

7. Default sorting: published_at DESC (newest first).

8. Unknown parameters are rejected with an error (-32602) instead of being silently ignored — check the spelling against the list below.

9. By default the response returns id, title, href, published_at, description and source.domain. The article body is NOT included — request it explicitly with fl (e.g. fl: "title,href,body").

AVAILABLE PARAMETERS:

Content Search

• title: Search by article title (supports up to 3 keywords with comma separation) IMPORTANT: a title search covers at most a 31-day published_at window. Omit the dates and the last 31 days are searched; pass a range wider than 31 days and the call fails with 400 ER0110. To cover a longer period, make one call per month-sized window.

• ignore: { title: "keyword" } - Exclude articles with specific titles

Languages (60+ supported)

• language: { code: "en,ru,fr" } - Filter by language codes (up to 3)

• ignore: { language: { code: "fr" } } - Exclude specific languages

Categories (IPTC taxonomy)

• category: { id: "medtop:04000000" } - Filter by category ID (up to 3)

• ignore: { category: { id: "315" } } - Exclude categories

Topics

• topic: { id: "crypto_news,climate_change" } - Filter by topic ID (up to 3)

• ignore: { topic: { id: "2" } } - Exclude topics

Industries

• industry: { id: "246771,246772" } - Filter by industry ID (up to 3)

• ignore: { industry: { id: "246772" } } - Exclude industries

Entities

• entity: { id: "1278268,1282301" } - Filter by entity ID (up to 3)

• ignore: { entity: { id: "315" } } - Exclude entities

Persons

• person: { name: "Elon Musk,Tim Cook" } - Filter by person name (up to 3)

• ignore: { person: { name: "John Doe" } } - Exclude persons

Locations

• location: { name: "Tokyo,New York" } - Filter by location (up to 3)

• ignore: { location: { name: "Paris" } } - Exclude locations

Organizations

• organization: { name: "Tesla,Apple,Google" } - Filter by organization (up to 3)

• ignore: { organization: { name: "Microsoft" } } - Exclude organizations

Disasters

• disaster: { name: "Earthquake,Tsunami" } - Filter by disaster type (up to 3)

• ignore: { disaster: { name: "Flood" } } - Exclude disasters

Diseases

• disease: { name: "COVID-19,Influenza" } - Filter by disease (up to 3)

• ignore: { disease: { name: "Flu" } } - Exclude diseases

Events

• event: { name: "Olympics,World Cup" } - Filter by event (up to 3)

• ignore: { event: { name: "Super Bowl" } } - Exclude events

Brands

• brand: { name: "Nike,Adidas" } - Filter by brand (up to 3)

• ignore: { brand: { name: "Puma" } } - Exclude brands

Authors

• author: { id: "123,456" } - Filter by author ID (up to 3)

• author: { name: "John Doe,Jane Smith" } - Filter by author name (up to 3)

• ignore: { author: { id: "789" } } - Exclude author IDs

• ignore: { author: { name: "Bob Jones" } } - Exclude author names

• has_author: 1 - Articles with attributed authors (0 for without)

Sentiment Analysis

• sentiment: { overall: { score: { min: 0.5, max: 1.0 } } } - Sentiment score range

• sentiment: { overall: { polarity: "positive" | "negative" | "neutral" } } - Sentiment polarity

• sentiment: { title: { score: { min: -1.0, max: 1.0 } } } - Title sentiment

• sentiment: { body: { score: { min: -1.0, max: 1.0 } } } - Body sentiment

• sentiment: { mixed: 1 } - Articles with mixed sentiment (title/body differ)

• sentiment: { consistent: 1 } - Articles with consistent sentiment

Media Content

• media: { images: { count: { min: 2, max: 10 } } } - Filter by image count

• media: { videos: { count: { min: 1 } } } - Filter by video count

• media: { images: { width: { min: 1200, max: 1920 } } } - Filter by image width

• media: { images: { height: { min: 800, max: 1080 } } } - Filter by image height

• has_image: 1 - Articles with at least one image

• has_video: 1 - Articles with at least one video

• has_hq_images: 1 - Articles with high-quality images (width >= 1200px)

• is_media_rich: 1 - Articles with both images and videos

Source Filtering

• source: { id: "314,315" } - Filter by source ID (up to 3)

• source: { domain: "cnn.com,bbc.com" } - Filter by domain (up to 3)

• source: { country: { code: "us,uk,de" } } - Filter by country (up to 3)

• source: { rank: { opr: { min: 0.5, max: 0.9 } } } - OpenPageRank range (0-7)

• source: { bias: "left,center,right" } - Filter by media bias (up to 3)

• ignore: { source: { id: "315" } } - Exclude source IDs

• ignore: { source: { domain: "example.com" } } - Exclude domains

• ignore: { source: { country: { code: "fr" } } } - Exclude countries

• ignore: { source: { bias: "left" } } - Exclude biases

• is_premium_source: 1 - Premium sources (OPR >= 6)

• is_verified_source: 1 - Verified sources (OPR >= 5, not duplicates)

Date/Time Filtering

• published_at: { start: "2024-01-01", end: "2024-01-31" } - Date range

• published_at: "2024-09-26" - Specific date

• Supported formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SSZ, DD-MM-YYYY, RFC3339

• Max 31 days between start and end WHEN the same call also searches titles (title, ignore.title patterns or query); a wider range returns 400 ER0110. Without a title filter the range is unlimited.

• An open-ended start ({ start: "2024-01-01" } with no end) runs to the current time, so with a title filter it exceeds the window too — always pair an archive start with an end date.

Sorting

• sort: { by: "published_at" | "created_at" | "source.rank.opr" | "read_time" | "sentiment.overall.score" | "sentiment.title.score" | "sentiment.body.score" | "media.images.count" | "media.videos.count" | "media.images.width.min" | "media.images.width.max" | "media.images.height.min" | "media.images.height.max" | "media_richness" | "relevance" | "engagement" | "quality" | "controversy" | "trust" }

• sort: { order: "asc" | "desc" }

• Advanced sorting: relevance (search ranking), engagement (viral potential), quality (editorial), controversy (polarization), trust (credibility)

Pagination

• page: 1 - Page number (default: 1)

• per_page: 10 - Results per page (default: 10). One response carries at most 25 articles, so a larger per_page is clamped to 25 — use page to walk through more.

Content Filters

• is_duplicate: 0 - Exclude duplicates (0=unique, 1=include duplicates)

• is_paywall: 0 - Exclude paywalled content (0=free, 1=paywall)

• is_breaking: 1 - Breaking news only

• read_time: { min: 1, max: 10 } - Filter by reading time (minutes)

• is_long_read: 1 - Articles with read time >= 5 minutes

• is_short_read: 1 - Articles with read time < 3 minutes

Field Selection (fl)

• Default (no fl): id, title, href, published_at, description, source.domain — body excluded

• fl: "id,title,source.name,published_at" - Return only specific fields

• fl: "title,href,body" - Ask for the full article text explicitly when you need to read it

• Supports nested fields with dot notation: source.name, sentiment.overall.score

Faceting

• facet: true - Enable faceting

• facet: { field: "source.id,language.id,sentiment.overall.polarity", limit: 20, mincount: 5 }

• Supported facet fields: source.id, source.country.id, source.bias, category.id, topic.id, industry.id, language.id, author.id, sentiment.*.polarity, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, published.year, published.month, published.day_of_week, published.hour

Range Faceting

• facet: { range: { field: "published_at", start: "2024-01-01", end: "2024-12-31", gap: "1MONTH" } }

• facet: { range: { field: "sentiment.overall.score", start: -1, end: 1, gap: 0.25 } }

• Date gaps: 1HOUR, 1DAY, 1WEEK, 1MONTH, 1YEAR

• Numeric gaps: 0.1, 0.25, 0.5, 1, 5, 10

Highlighting

• hl: true - Enable highlighting

• hl: { fl: "title,description,body", fragsize: 300, snippets: 5, tag: { pre: "", post: "" } }

• Auto-expands search terms using synonyms and morphology

QUERY BUILDING EXAMPLES:

• Basic search: {title: "Bitcoin", language: {code: "en"}}

• Sentiment analysis: {organization: {name: "Tesla"}, sentiment: {overall: {polarity: "positive"}}}

• High-quality sources: {source: {rank: {opr: {min: 0.7}}}, is_verified_source: 1}

• Date range (no title filter, so any width): {published_at: {start: "2024-01-01", end: "2024-12-31"}}

• Title search over an archive month: {title: "Bitcoin", published_at: {start: "2024-01-01", end: "2024-01-31"}}

• Multiple filters: {title: "AI", organization: {name: "Google,Microsoft"}, language: {code: "en"}, is_breaking: 1}

• With media: {has_image: 1, media: {images: {count: {min: 2}}}}

• Sorted by engagement: {sort: {by: "engagement", order: "desc"}}

• With faceting: {facet: true, facet: {field: "source.id,language.id", limit: 10}}

• With highlighting: {title: "innovation", hl: true, hl: {fl: "title,body"}}

• Breaking news: {is_breaking: 1, sort: {by: "published_at"}}

• Long-form quality: {is_long_read: 1, sort: {by: "quality", order: "desc"}}

Resolve a name or prefix to APITube taxonomy IDs so you can use them in the search_news tool's filters.

The search_news tool's most precise filters require IDs you cannot guess:

• entity.id — numeric (persons, organizations, locations, brands, events...)

• category.id — IPTC slug, e.g. "medtop:04000000"

• topic.id — slug

• industry.id — numeric

Use this tool FIRST to look those IDs up, then pass them into search_news.

USAGE:

• type: which taxonomy to autocomplete — one of "entities", "categories", "topics", "industries".

• prefix: the name (or its beginning) to search, e.g. "Tesla", "Elon", "spo".

Returns an array of matches; take the id of the best match and put it into search_news: suggest({ type: "entities", prefix: "Tesla" }) → [{ id: 12345, name: "Tesla, Inc.", ... }] search_news({ entity: { id: "12345" } })