> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced querying techniques

> Query syntax reference for the News API q parameter.

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](/news-api/how-to/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 |

Use exact match for names, titles, and any multi-word term you want treated as
a unit.

### Escaping quotes in JSON

When passing exact match syntax inside a JSON string, escape the inner double
quotes with a backslash:

```json theme={null}
{
  "q": "presidential election",
  "PER_entity_name": "\"Kamala Harris\" AND \"Donald Trump\"",
  "include_nlp_data": true
}
```

<Tip>
  Always escape double quotes with `\` inside JSON string values to maintain
  exact match syntax.
</Tip>

## 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\""`                   |

Use parentheses to group terms and control evaluation order:

```
"(bitcoin OR cryptocurrency) AND (investment OR trading)"
```

<Warning>
  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](/news-api/how-to/validate-queries-python-sdk#understand-automatic-and-insertion).
</Warning>

## 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                    |

<Note>
  Wildcards cannot appear at the start of a term. `"*intelligence"` is not valid.
</Note>

## 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`. |

**Limits:**

* 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)"
```

**Competitive analysis:**

```
"(\"Apple\" OR \"Google\") AND \"smartphone market\" AND NOT (\"Samsung\" OR \"Huawei\")"
```

**Event monitoring:**

```
"(\"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

* [Build search queries](/news-api/how-to/build-search-queries)
* [Validate queries with Python SDK](/news-api/how-to/validate-queries-python-sdk)
* [API reference overview](/news-api/api-reference/overview)