---
title: "10 News API Filter Patterns You Should Know (2026)"
description: "10 runnable news API filter patterns — keywords, boolean, dates, entities, sentiment, and compound queries — with curl, Python, and JSON examples plus the gotcha that wastes your first day."
source: https://apitube.io/blog/post/news-api-filter-patterns
---

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

**News API filtering is the practice of combining query parameters — keywords, boolean operators, dates, sources, entities, and sentiment — 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 search (`title`, `body`)
2. Boolean operators (`AND`, `OR`, `NOT`, parentheses)
3. Date-range filter (`published_at.start`, `published_at.end`)
4. Language + country filter (`language.code`, `country.code`)
5. Source domain include / exclude (`source.domain`)
6. Entity filter (`entity.id`)
7. Sentiment polarity filter (`sentiment.body.polarity`)
8. Category + industry filter (`category.id`, `industry`)
9. Compound query (entity + sentiment + date + language + source.country)
10. Pagination + sort with cost-aware tips (`per_page`, `page`, `sort`)

All examples assume `export APITUBE_KEY=...` and base URL `https://api.apitube.io`.


## 1. Keyword + Exact Phrase Search

**Search the title or body for an exact phrase by wrapping it in quotes.** Plain words are loose-matched; quoted phrases are matched as a unit, in order.

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

```python
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):

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

**Gotcha**: spaces inside a phrase need URL-encoding (`%20` or `+`). Without encoding, you silently match the first word only.

**Cross-API**: NewsAPI uses `q="apple vision pro"` (single `q` field). APITube splits `title` vs `body` so you can target where the phrase appears.


## 2. Boolean Operators

**Combine multiple terms with `AND`, `OR`, `NOT`, and group with parentheses.** Boolean logic gives you precise control without running multiple requests.

```bash
curl -sS 'https://api.apitube.io/v1/news/everything?body=(tesla%20OR%20rivian)%20AND%20earnings%20NOT%20rumor' \
  -H "X-API-Key: $APITUBE_KEY"
```

```python
params = {"body": "(tesla OR rivian) AND earnings NOT rumor", "per_page": 20}
r = requests.get(API, params=params, headers=HEADERS)
```

JSON response (excerpt):

```json
{"results": [{"title": "Rivian Q1 earnings: revenue up 23%", "sentiment": {"body": {"polarity": "positive"}}}], "total": 184}
```

**Gotcha**: precedence is left-to-right unless you use parentheses. `tesla OR rivian AND earnings` does not mean what you think it means — wrap groups explicitly.

**Cross-API**: NewsAPI supports the same `AND/OR/NOT` syntax inside `q`. NewsData.io uses comma-separated `q_or` and `q_not` 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.

```bash
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"
```

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

JSON excerpt:

```json
{"results": [{"published_at": "2026-04-15T08:42:00Z", "title": "..."}], "total": 12480}
```

**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. Naive `04/01/2026` strings silently return zero results.


## 4. Language + Country Filter

**Filter by article language and source country independently.** Language uses ISO 639-1 codes; country uses ISO 3166-1 alpha-2.

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

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

**Gotcha**: `country.code` filters by **source publisher's country**, not by where the story is *about*. A German article about Brazil still has `country.code=de`. To filter by story location, use `entity.id` for the country entity.


## 5. Source Domain Include / Exclude

**Restrict to specific outlets with `source.domain`, exclude with `NOT`.**

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

To exclude a list, use boolean negation:

```bash
curl -sS 'https://api.apitube.io/v1/news/everything?body=crypto&source.domain=NOT%20(coindesk.com%20OR%20cointelegraph.com)' \
  -H "X-API-Key: $APITUBE_KEY"
```

JSON excerpt:

```json
{"results": [{"source": {"domain": "reuters.com", "country": "us"}}]}
```

**Gotcha**: domain matching is exact. `reuters.com` does not match `uk.reuters.com`. Use `*.reuters.com` if the API supports wildcards (APITube does); test before assuming.

**Cross-API**: NewsAPI uses `domains=` (comma list) and `excludeDomains=`. APITube and NewsCatcher prefer boolean negation inside the source field.


## 6. Entity Filter

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

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

(`Q312` is the Wikidata ID for Apple Inc.)

```python
params = {"entity.id": "Q312", "language.code": "en", "per_page": 25}
```

JSON excerpt:

```json
{"results": [{"title": "Apple announces new chip", "entities": [{"id": "Q312", "name": "Apple Inc.", "type": "organization"}]}]}
```

**Gotcha**: searching by `body=apple` returns articles about the **fruit** mixed with the company. `entity.id=Q312` disambiguates because the entity recognizer has already classified mentions. This is the single biggest accuracy upgrade you can make.

**Cross-API**: NewsAPI does not support entity filtering. NewsAPI.ai (Event Registry) and APITube both support it; the ID systems differ — APITube uses Wikidata Q-IDs.


## 7. Sentiment Polarity Filter

**Filter to articles with a given sentiment polarity in the body or title.** Polarity is computed per-document at ingestion.

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

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

JSON excerpt:

```json
{"results": [{"title": "Apple faces antitrust probe", "sentiment": {"body": {"polarity": "negative", "score": -0.62}}}]}
```

**Gotcha**: sentiment is per-document, not per-claim. An article that's mostly positive about Apple but quotes one critical analyst is still labeled "positive". For claim-level sentiment, post-process with an LLM on the `body` field.


## 8. Category + Industry Filter

**Narrow by topical category (`category.id`) and industry classification (`industry`).** Both are independent taxonomies.

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

JSON excerpt:

```json
{"results": [{"category": {"id": "technology", "name": "Technology"}, "industry": "software"}]}
```

**Gotcha**: stacking `category.id=technology` AND `industry=automotive` produces a near-empty intersection — they're orthogonal axes, not a hierarchy. Use one as the primary filter and the other as a 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.

```bash
curl -sS 'https://api.apitube.io/v1/news/everything?entity.id=Q312&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=us&per_page=50' \
  -H "X-API-Key: $APITUBE_KEY"
```

```python
params = {
    "entity.id": "Q312",
    "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": "us",
    "per_page": 50,
}
r = requests.get(API, params=params, headers=HEADERS)
```

JSON excerpt:

```json
{
  "results": [
    {
      "title": "Apple faces antitrust probe in US",
      "published_at": "2026-04-12T18:30:00Z",
      "source": {"domain": "wsj.com", "country": "us"},
      "entities": [{"id": "Q312", "name": "Apple Inc."}],
      "sentiment": {"body": {"polarity": "negative", "score": -0.71}}
    }
  ],
  "total": 38
}
```

**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 — handle empty `results` arrays gracefully.


## 10. Pagination + Sort with Cost-Aware Tips

**Use `per_page` (max 100) with `page` to walk through results; sort with `sort` and `sort_by`.**

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

```python
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_more"):
            return
```

**Gotcha 1**: APITube's free tier returns the **first page only** (30 req / 30 min). `page=2` returns 200 OK with empty `results` — do not retry in a loop.

**Gotcha 2**: `sort_by=relevance` without a keyword query is undefined behavior. Pair with `title=` or `body=` or stick with `sort=published_at`.

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


## 5 Anti-Patterns That Waste Your Quota

1. **Looping `per_page=100&page=N` on the free tier.** First page only. Wraps your 30 req / 30 min budget into one wasted minute.
2. **`sort_by=relevance` without a query.** Sort key is undefined; you'll get arbitrary order and an upsold "premium ranking" bill on some APIs.
3. **Naive date strings (`2026/04/01`, `April 1`).** Silently parse to nothing; you get zero results and assume the topic is dead.
4. **Stacking `category.id` + `industry` as if hierarchical.** They're orthogonal — empty intersections look like a bug but aren't.
5. **Filtering by `body=apple` for the company.** You'll match fruit news, recipes, and orchard reports. Switch to `entity.id`.


## 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 keyword (`title`, `body`), date range (`published_at.start`, `published_at.end`), language, country, source domain, entity, sentiment, and category. Combine multiple parameters in a single request to narrow results — APITube's `/v1/news/everything` accepts all of these in one call.

### What query operators does the news API support?

APITube supports `AND`, `OR`, `NOT`, parentheses for grouping, double-quoted phrases for exact matches, and `-` prefix for word exclusion. The same operators work in NewsAPI.org's `q` parameter and inside NewsCatcher's search. Always wrap multi-term groups in parentheses — operator precedence is left-to-right and burns more queries than any other syntax mistake.

### 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 uses `from` and `to` parameters; NewsData.io uses `from_date` and `to_date`. Avoid locale-formatted dates (`04/01/2026`) — they parse to nothing and return zero results silently.

### Can I filter news by sentiment or entity?

Yes — APITube exposes `sentiment.body.polarity` and `sentiment.title.polarity` (positive / negative / neutral) and `entity.id` for people, organizations, and brands. NewsAPI.org does not support either. 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 up to dozens of simultaneous filters in one call (entity + sentiment + date + language + source.country 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. The free tier gives you 30 requests per 30 minutes — enough to validate every pattern in this post. Try APITube free at apitube.io; sentiment, entities, and category classification are included on every article without separate enrichment calls.


## Resources

- **APITube** — [apitube.io](https://apitube.io) — try it free, sentiment and entities included on every article
- **Documentation** — [docs.apitube.io](https://docs.apitube.io) — endpoints, parameters, response structure, integrations
- **Pricing** — [apitube.io/pricing](https://apitube.io/pricing) — all tiers
- **New to news APIs?** — [News API Quick Start: Your First Request in 5 Minutes](/blog/post/news-api-quick-start-first-request)