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.
The q parameter accepts a rich query syntax for building precise searches:
exact phrase matching, boolean operators, wildcards, and proximity search. This
page describes each technique and how to combine them.
To apply these techniques in a working API call, see
Build search queries.
Exact match
Wrap a phrase in double quotes to search for it as an exact sequence of words.
Without quotes, the API treats each word as a separate term and inserts AND
between them automatically.
| Query | What it matches |
|---|
"\"Tim Cook\"" | Articles containing the exact phrase "Tim Cook" |
"Tim Cook" | Same as "Tim AND Cook" — both words anywhere in the article |
Escaping quotes in JSON
When passing exact match syntax inside a JSON string, escape the inner double
quotes with a backslash:
{
"q": "presidential election",
"PER_entity_name": "\"Kamala Harris\" AND \"Donald Trump\"",
"include_nlp_data": true
}
Always escape double quotes with \ inside JSON string values to maintain
exact match syntax.
Boolean operators
Use boolean operators to combine or exclude terms. The q parameter is a
string — the table below shows the exact value you pass:
| Operator | Effect | Example |
|---|
AND | Both terms must appear. Default when terms are space-separated. | "Microsoft AND Tesla" |
OR | Either term may appear. | "(Apple AND Cook) OR (Microsoft AND Gates)" |
NOT | Excludes articles containing the term. | "Tesla NOT \"Elon Musk\"" |
"(bitcoin OR cryptocurrency) AND (investment OR trading)"
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. Wildcards
Use wildcards to match term variations:
| Wildcard | Effect | Example |
|---|
* | Matches any string of any length | "technolog*" matches technology, technological, technologies |
? | Matches any single character | "Microsoft AND C?O" matches CEO, CFO, CTO |
Wildcards cannot appear at the start of a term. "*intelligence" is not valid.
Proximity search
The NEAR operator finds articles where two terms appear within a specified
number of words of each other. Use it when terms must be discussed in the same
context, not just anywhere in the article.
Syntax:
NEAR("phrase_A", "phrase_B", distance, in_order)
| Parameter | Description |
|---|
phrase_A, phrase_B | Terms to find near each other (max 4 words each) |
distance | Maximum number of words between the phrases (max 100) |
in_order | Optional. If true, phrase_B must follow phrase_A. Defaults to false. |
- Maximum 4 words per phrase
- Maximum 3 phrases per
NEAR operation
- Maximum distance of 100 words
Combining techniques
You can combine all techniques in a single query. The following examples show
the exact value to pass in the q string:
Market research:
"\"artificial intelligence\" AND (healthcare OR \"medical research\") AND NEAR(\"market growth\", \"emerging trends\", 20)"
"(\"Apple\" OR \"Google\") AND \"smartphone market\" AND NOT (\"Samsung\" OR \"Huawei\")"
"(\"climate change\" OR \"global warming\") AND (conference* OR summit) AND NEAR(\"Paris agreement\", implementation, 15)"
Comparison of techniques
| Technique | Strengths | Limitations | Best for |
|---|
| Exact match | Precise phrase matching | May miss relevant variations | Names, titles, specific phrases |
| Boolean operators | Versatile, combines multiple concepts | Can become complex | Comprehensive searches |
| Wildcards | Broadens search to include variations | Can return irrelevant results | Exploring related terms |
Proximity search (NEAR) | Finds related terms in context | Limited to 100-word distance | Concept relationships |
Best practices
- Start broad and add filters to narrow results.
- Always quote multi-word terms to prevent automatic
AND insertion.
- Use parentheses to group terms and make operator precedence explicit.
- Use
NEAR when terms must appear in the same context, not just the same article.
- Check
user_input.q in the response to verify how the API interpreted your query.
- URL-encode the
q parameter when using GET requests to avoid issues with
special characters.
See also
