10 News API Filter Patterns Every Developer Should Know (2026)

News API filtering is the practice of combining query parameters — title search, dates, sources, entities, sentiment, categories — to narrow a news feed from millions of articles to the ones your app actually needs. Unlike a plain full-text search, a modern news API also classifies every article on dimensions you can filter by directly (entity, sentiment, category, source country), which means one well-crafted request replaces an entire NLP pipeline. Most vendor docs list parameters but never show what a real combined query looks like, what comes back, or where the footguns are.

This post is for developers integrating a news API who want copy-paste examples that run. Every pattern below uses APITube's /v1/news/everything endpoint, with cross-API translation lines where the syntax differs in NewsAPI.org or NewsData.io. Each pattern includes curl, a Python snippet, a trimmed JSON response, and the gotcha that wastes your first day.

Disclosure: I work at APITube. Patterns map cleanly to other major news APIs — translation lines included where syntax differs.

10 Patterns at a Glance

1. Keyword & exact-phrase title search (title, "...", ~N)
2. Excluding terms and matching by position (ignore.title, title_starts_with, title_ends_with)
3. Date-range filter (published_at.start, published_at.end)
4. Language + source-country filter (language.code, source.country.code)
5. Source domain include / exclude (source.domain, ignore.source.domain)
6. Entity filter (entity.id)
7. Sentiment polarity filter (sentiment.body.polarity)
8. Category + industry filter (category.id, industry.id)
9. Compound query (entity + sentiment + date + language + source country)
10. Pagination + sort (per_page, page, sort.by, sort.order)

All examples assume export APITUBE_KEY=... and base URL https://api.apitube.io. Authenticate with the X-API-Key header (or an api_key query parameter).

1. Keyword & Exact-Phrase Title Search

APITube searches the article title. Pass plain words for loose matching, or wrap a phrase in quotes for an exact, in-order match. Keyword search also expands synonyms and morphological forms; quoted phrases do not.

curl -sS 'https://api.apitube.io/v1/news/everything?title="apple vision pro"&per_page=10' \
  -H "X-API-Key: $APITUBE_KEY"

import requests, os
r = requests.get(
    "https://api.apitube.io/v1/news/everything",
    params={"title": '"apple vision pro"', "per_page": 10},
    headers={"X-API-Key": os.environ["APITUBE_KEY"]},
)
print(r.json()["results"][0]["title"])

JSON response (excerpt):

{
  "status": "ok",
  "results": [
    {"id": "a1b2", "title": "Apple Vision Pro sales beat estimates", "href": "https://...", "published_at": "2026-05-02T14:11:00Z", "source": {"domain": "reuters.com"}}
  ],
  "has_next_pages": true
}

Three matching modes:

• Keyword — title=bitcoin or title=AI,innovation (comma-separated terms, any order, with synonym/morphology expansion).
• Phrase — title="breaking news" (exact phrase, no expansion).
• Proximity — title="apple iphone"~5 (words within N tokens of each other, N = 0–10).

Gotcha: APITube matches against the title, not the full body — there is no body search parameter. The title is the strongest relevance signal, so this is by design, but it means a keyword buried only in the article body won't match. The full body is returned in every result, so post-filter there if you need body-level matching. Spaces inside a quoted phrase still need URL-encoding (%20 or +).

Cross-API: NewsAPI.org uses a single q field that searches title + body. APITube filters on title specifically, and exposes the classified dimensions below (entity, sentiment, category) so you rarely need raw body search.

2. Excluding Terms and Matching by Position

Narrow a title search without boolean operators: exclude terms with ignore.title, and anchor matches with title_starts_with / title_ends_with / title_pattern. APITube does not parse AND/OR/NOT inside a value — those words are treated as ordinary tokens — so exclusion is its own parameter.

curl -sS 'https://api.apitube.io/v1/news/everything?title=tesla&ignore.title=rumor&title_starts_with=Breaking' \
  -H "X-API-Key: $APITUBE_KEY"

params = {"title": "tesla", "ignore.title": "rumor", "title_starts_with": "Breaking", "per_page": 20}
r = requests.get(API, params=params, headers=HEADERS)

JSON response (excerpt):

{"results": [{"title": "Breaking: Tesla Q1 earnings beat estimates", "sentiment": {"body": {"polarity": "positive"}}}], "has_next_pages": true}

Gotcha: don't try to write title=(tesla OR rivian) AND earnings NOT rumor — there is no boolean query language. OR, AND, NOT would be searched as literal words. Use comma-separated terms for OR-style breadth (title=tesla,rivian), ignore.title for exclusion, and run separate calls if you genuinely need cross-term AND logic.

Cross-API: NewsAPI.org supports AND/OR/NOT inside q. NewsData.io uses comma-separated q_or and a separate exclusion field. APITube keeps inclusion and exclusion as distinct parameters instead.

3. Date-Range Filter

Restrict articles to a published window using published_at.start and published_at.end. Both accept ISO 8601 timestamps.

curl -sS 'https://api.apitube.io/v1/news/everything?published_at.start=2026-04-01T00:00:00Z&published_at.end=2026-04-30T23:59:59Z&language.code=en' \
  -H "X-API-Key: $APITUBE_KEY"

params = {
    "published_at.start": "2026-04-01T00:00:00Z",
    "published_at.end": "2026-04-30T23:59:59Z",
    "language.code": "en",
}

JSON excerpt:

{"results": [{"published_at": "2026-04-15T08:42:00Z", "title": "..."}], "has_next_pages": true}

Gotcha: bare dates like 2026-04-01 work, but the API treats them as midnight UTC. If you need a specific timezone, append it explicitly. APITube also accepts Solr-style relative dates (NOW-7DAYS, NOW-1MONTH/DAY). Locale-formatted strings like 04/01/2026 are not valid and silently return zero results.

4. Language + Source-Country Filter

Filter by article language and source country independently. Language uses ISO 639-1 codes; country uses ISO 3166-1 alpha-2 (exactly two characters).

curl -sS 'https://api.apitube.io/v1/news/everything?language.code=de&source.country.code=de&title=KI' \
  -H "X-API-Key: $APITUBE_KEY"

params = {"language.code": "de", "source.country.code": "de", "title": "KI"}

Gotcha: the parameter is source.country.code, not country.code — and it filters by the publisher's country, not where the story is about. A German outlet writing about Brazil still has source.country.code=de. To filter by story location, use the location parameters (location.name) or an entity.id for the country.

5. Source Domain Include / Exclude

Restrict to specific outlets with source.domain; exclude outlets with ignore.source.domain. Both take exact domain names (resolved against APITube's source directory) and accept up to three comma-separated values.

curl -sS 'https://api.apitube.io/v1/news/everything?source.domain=reuters.com&title=fed' \
  -H "X-API-Key: $APITUBE_KEY"

To exclude outlets, use the dedicated ignore parameter:

curl -sS 'https://api.apitube.io/v1/news/everything?title=crypto&ignore.source.domain=coindesk.com,cointelegraph.com' \
  -H "X-API-Key: $APITUBE_KEY"

JSON excerpt:

{"results": [{"source": {"domain": "reuters.com", "location": {"country_code": "us"}}}]}

Gotcha: domain matching is exact and there are no wildcards — reuters.com does not match uk.reuters.com, and *.reuters.com is not supported. There is also no boolean negation inside source.domain; exclusion lives in the separate ignore.source.domain parameter. Each side caps at three domains per request.

Cross-API: NewsAPI.org uses domains= and excludeDomains= (comma lists). APITube splits include/exclude into source.domain and ignore.source.domain.

6. Entity Filter

Filter by a specific person, organization, or brand using entity.id. Entity IDs are stable numeric identifiers; entity names are not.

curl -sS 'https://api.apitube.io/v1/news/everything?entity.id=1278268&language.code=en' \
  -H "X-API-Key: $APITUBE_KEY"

params = {"entity.id": "1278268", "language.code": "en", "per_page": 25}

JSON excerpt:

{"results": [{"title": "...", "entities": [{"id": 1278268, "name": "...", "type": "person", "links": {"wikidata": "https://www.wikidata.org/wiki/..."}}]}]}

Gotcha: entity.id is APITube's numeric entity identifier (e.g. 1278268), not a Wikidata Q-ID — passing Q312 returns a validation error. Look the ID up from the entities[] array of any result, or via the /v1/news/entity endpoint; each result also carries a links.wikidata URL if you need to cross-reference. You can pass up to three IDs comma-separated (OR logic). Filtering by entity disambiguates "Apple" the company from the fruit, because the recognizer already classified each mention — the single biggest accuracy upgrade over keyword search.

Cross-API: NewsAPI.org has no entity filtering. NewsAPI.ai (Event Registry) and APITube both support it; APITube uses its own numeric IDs and links out to Wikidata in the response.

7. Sentiment Polarity Filter

Filter to articles with a given sentiment polarity in the body, title, or overall. Polarity is computed per-document at ingestion; valid values are positive, negative, and neutral.

curl -sS 'https://api.apitube.io/v1/news/everything?entity.id=1278268&sentiment.body.polarity=negative&per_page=20' \
  -H "X-API-Key: $APITUBE_KEY"

params = {
    "entity.id": "1278268",
    "sentiment.body.polarity": "negative",
    "published_at.start": "2026-05-01",
}

JSON excerpt:

{"results": [{"title": "...", "sentiment": {"body": {"polarity": "negative", "score": -0.62}}}]}

Gotcha: sentiment is per-document, not per-claim. An article that's mostly positive but quotes one critical analyst is still labeled positive. There are three independent axes — sentiment.title.polarity, sentiment.body.polarity, sentiment.overall.polarity — plus score ranges (sentiment.body.score.min / .max). For claim-level sentiment, post-process the returned body with an LLM.

8. Category + Industry Filter

Narrow by topical category (category.id) and industry classification (industry.id). Both are independent taxonomies, and both take their own identifiers — not free-text slugs.

curl -sS 'https://api.apitube.io/v1/news/everything?category.id=medtop:15000000&industry.id=400&language.code=en' \
  -H "X-API-Key: $APITUBE_KEY"

JSON excerpt:

{"results": [{"categories": [{"id": "medtop:15000000", "name": "Sport", "taxonomy": "iptc"}], "industries": [{"id": 400, "name": "..."}]}]}

Gotcha: category.id is an IPTC media-topic code (e.g. medtop:15000000), and industry.id is a numeric ID (e.g. 400) — neither accepts a plain word like technology or software, which returns a "not found" error. Pull the valid codes from the list-of-categories reference or the /v1/news/category and /v1/news/industry endpoints. Category and industry are orthogonal axes, not a hierarchy, so stacking a narrow pair can produce a near-empty intersection — use one as primary, the other as refinement.

9. Compound Query — Stack 4+ Dimensions in One Call

The pattern most vendor docs never show: combine entity + sentiment + date-range + language + source country in a single request.

curl -sS 'https://api.apitube.io/v1/news/everything?entity.id=1278268&sentiment.body.polarity=negative&published_at.start=2026-04-01T00:00:00Z&published_at.end=2026-05-01T00:00:00Z&language.code=en&source.country.code=us&per_page=50' \
  -H "X-API-Key: $APITUBE_KEY"

params = {
    "entity.id": "1278268",
    "sentiment.body.polarity": "negative",
    "published_at.start": "2026-04-01T00:00:00Z",
    "published_at.end": "2026-05-01T00:00:00Z",
    "language.code": "en",
    "source.country.code": "us",
    "per_page": 50,
}
r = requests.get(API, params=params, headers=HEADERS)

JSON excerpt:

{
  "status": "ok",
  "results": [
    {
      "title": "...",
      "published_at": "2026-04-12T18:30:00Z",
      "source": {"domain": "wsj.com", "location": {"country_code": "us"}},
      "entities": [{"id": 1278268, "name": "...", "type": "organization"}],
      "sentiment": {"body": {"polarity": "negative", "score": -0.71}}
    }
  ],
  "has_next_pages": false
}

This is the query you actually want for: brand monitoring, alerting on negative coverage in a specific market, training a sentiment model. Running it as five separate calls and intersecting client-side burns 5x your quota for the same answer.

Gotcha: every additional filter narrows the result set multiplicatively. A 5-dimension query may return zero rows in slow news weeks — check has_next_pages and handle empty results arrays gracefully.

10. Pagination + Sort

Use per_page with page to walk through results; sort with sort.by and sort.order.per_page defaults to 100 and caps at 250.

curl -sS 'https://api.apitube.io/v1/news/everything?title=ai&per_page=100&page=1&sort.by=published_at&sort.order=desc' \
  -H "X-API-Key: $APITUBE_KEY"

def paginate(params, max_pages=5):
    for page in range(1, max_pages + 1):
        r = requests.get(API, params={**params, "page": page, "per_page": 100}, headers=HEADERS)
        data = r.json()
        for item in data["results"]:
            yield item
        if not data.get("has_next_pages"):
            return

Gotcha 1: the sort parameters are sort.by and sort.order (dot notation) — not sort or sort_by. sort.by accepts published_at (default), created_at, id, read_time, source.rank.opr, the sentiment.*.score fields, and more; sort.order is asc or desc (default desc).

Gotcha 2: stop paginating when has_next_pages is false — the response also hands you a ready-built next_page URL, so you can follow that instead of incrementing page yourself. There is no top-level total count; use has_next_pages / next_page to drive your loop.

Cross-API: NewsAPI.org uses pageSize (max 100) and page. NewsData.io uses cursor-based pagination via a page token, not numeric page numbers — don't assume.

5 Anti-Patterns That Waste Your Time

1. Reaching for a body search parameter. It doesn't exist — APITube filters on title. Search the title, then post-filter the returned body if you need body-level matching.
2. Writing boolean queries ((a OR b) AND c NOT d). There's no boolean parser. Use comma-separated terms for OR, ignore.title for exclusion, separate calls for AND.
3. Passing human-readable IDs (category.id=technology, entity.id=Q312, industry=software). Categories are IPTC codes, entities and industries are numeric IDs. Look them up from the response or the reference endpoints.
4. Using country.code / sort_by / total. The real names are source.country.code, sort.by + sort.order, and pagination is driven by has_next_pages / next_page — there is no total field.
5. Naive date strings (2026/04/01, April 1). Only ISO 8601 (or Solr-style NOW-7DAYS) parses; locale formats return zero results silently.

Frequently Asked Questions

How do I filter news API results?

You filter news API results by passing query parameters to the search endpoint. Common filters include title search (title), date range (published_at.start, published_at.end), language (language.code), source country (source.country.code), source domain (source.domain), entity (entity.id), sentiment (sentiment.body.polarity), and category (category.id). Combine multiple parameters in a single request to narrow results — APITube's /v1/news/everything accepts all of these in one call, joined with logical AND.

What search operators does the news API support?

APITube's title parameter supports three modes: keyword search (comma-separated terms with synonym and morphology expansion), exact phrases in double quotes (title="Federal Reserve"), and proximity search (title="apple iphone"~5). It does not support boolean AND/OR/NOT operators or parentheses inside a value — those words are treated as ordinary tokens. Use comma-separated terms for OR-style breadth and the separate ignore.title parameter for exclusion.

How do you search news by date range?

Pass published_at.start and published_at.end with ISO 8601 timestamps, e.g. 2026-04-01T00:00:00Z. Bare dates like 2026-04-01 are accepted and treated as midnight UTC. NewsAPI.org uses from and to; NewsData.io uses from_date and to_date. Avoid locale-formatted dates (04/01/2026) — they aren't valid ISO 8601 and return zero results silently.

Can I filter news by sentiment or entity?

Yes — APITube exposes sentiment.body.polarity, sentiment.title.polarity, and sentiment.overall.polarity (positive / negative / neutral), plus entity.id for people, organizations, and brands. entity.id is a numeric identifier (look it up from any result's entities[] array), not a Wikidata Q-ID. NewsAPI.org supports neither; NewsAPI.ai (Event Registry) supports both. Filtering by entity.id is the single biggest accuracy improvement over keyword search because it disambiguates names like "Apple" or "Amazon" from their non-corporate meanings.

How do I combine multiple filters in one news API request?

Pass all parameters in a single GET request — the API joins them with logical AND. APITube accepts dozens of simultaneous filters in one call (entity + sentiment + date + language + source.country.code shown in Pattern 9). Running five separate filtered calls and intersecting client-side burns five times the quota for the same result. Build the compound query, then narrow further only if the result set is too large.

Try APITube Free

All 10 patterns run against APITube's /v1/news/everything endpoint. Sentiment, entities, and category classification are included on every article without separate enrichment calls. See apitube.io/pricing for current tiers and request limits.

Resources

• APITube — apitube.io — try it free, sentiment and entities included on every article
• Documentation — docs.apitube.io — endpoints, parameters, response structure, integrations
• Pricing — apitube.io/pricing — all tiers
• New to news APIs? — News API Quick Start: Your First Request in 5 Minutes