Skip to main content

Documentation Index

Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

News API supports a rich query syntax in the q parameter: boolean operators (AND, OR, NOT), proximity search (NEAR), wildcards, and exact phrase matching. This guide shows you how to put them together and make the API call. For the full syntax reference, see Advanced querying.

​
Before you begin

Make sure you have the following:
  • An active News API key
  • The Newscatcher SDK installed for your language, or cURL for quick testing

​
Steps

1

Build a boolean query

Use AND, OR, and NOT to combine terms. Use parentheses to control evaluation order. The q parameter is a string — examples below show the exact value you pass:
GoalQuery string
Both terms present"bitcoin AND blockchain"
Either term"bitcoin OR cryptocurrency"
Exclude a term"Tesla NOT \"Elon Musk\""
Combine groups"(bitcoin OR cryptocurrency) AND (investment OR trading)"
Exact phrase"\"electric vehicles\" NOT Tesla"
Always quote multi-word terms: "Tesla NOT \"Elon Musk\"".Without quotes, the API inserts AND between standalone words — "AI OR artificial intelligence" becomes "AI OR artificial AND intelligence", which returns a 422 (mixed operators at the same level).See Automatic AND insertion.
Pass your query in the q parameter:
curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "(bitcoin OR cryptocurrency) AND (investment OR trading)"
  }'
2

Build a proximity query

The NEAR operator finds articles where two terms appear within a specified number of words of each other. Use it when you need terms to be discussed in the same context, not just anywhere in the article.Syntax:
NEAR("phrase_A", "phrase_B", distance, in_order)
ParameterDescription
phrase_A, phrase_BTerms to find near each other (max 4 words each)
distanceMaximum words between the phrases (max 100)
in_orderOptional. If true, phrase_B must follow phrase_A (default: false)
curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "NEAR(\"climate change\", \"renewable energy\", 15)"
  }'
3

Validate your query

If you’re using the Python SDK, run validate_query() before making the API call. It catches syntax errors locally without consuming an API call:
from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")
query = 'NEAR("climate change", "renewable energy", 15)'
is_valid, error = client.validate_query(query)

if not is_valid:
    print(f"Fix before sending: {error}")
else:
    response = client.search.post(q=query)
Validation is especially useful for LLM-generated queries and user input. See Validate queries with Python SDK for bulk validation and the full rules reference.
4

Refine your results

Check total_hits and user_input in the response to understand what the API matched and how it interpreted your query:
{
  "status": "ok",
  "total_hits": 635,
  "page": 1,
  "total_pages": 7,
  "page_size": 100,
  "articles": [...],
  "user_input": {
    "q": "NEAR(\"climate change\", \"renewable energy\", 15)"
  }
}
If results are off, try the following:
  • Too broad — add AND terms or narrow with NOT, or reduce the NEAR distance
  • Too few — broaden with OR, increase the NEAR distance, or use wildcards (technolog*)
  • Wrong interpretation — check user_input.q to see how the API parsed your query

​
See also