Source: https://eventregistry.org/documentation?tab=keyword_search_options

# Keyword search modes

When you search for content using the `keyword` parameter, you can control the provided text is matched against the articles. The behavior is set using the `keywordSearchMode` parameter, which supports three different modes: `phrase` (the default), `exact` and `simple`. Each mode is suited to a different kind of search, from strict phrase matching to full Boolean logic and to broad, relevance-based retrieval. The sections below explain when to use each mode and provide concrete examples.

The `keywordSearchMode` parameter can be combined with `keywordLoc`, which determines where the keywords are searched for — in the article `body` (default), the `title`, or `title,body`.

These modes control only how the `keyword` parameter itself is matched. To combine keywords with other conditions (concepts, categories, sources, ...) or to use the advanced JSON query language with `AND`/`OR`/`NOT` logic, see the section.

## Phrase search mode

In the `phrase` mode the value of the `keyword` parameter is matched as an **exact phrase**. All the words have to appear in the article, next to each other and in the same order as provided. Searching for `electric vehicle` will match articles containing the phrase "electric vehicle", but not articles that only mention "vehicle" and "electric" in separate, unrelated sentences.

This is the **default mode**, so it is used whenever the `keywordSearchMode` parameter is omitted. It is the right choice for the majority of searches, where you are looking for a specific term, product, company or multi-word concept and you want precise, high-quality matches.

```

            {
    "action": "getArticles",
    "keyword": "electric vehicle",
    "keywordSearchMode": "phrase",
    "apiKey": "YOUR_API_KEY"
}
```

If you want to require several phrases at once, provide a list of values in the `keyword` parameter. By default all of them have to be present (logical ); set `keywordOper` to `or` if any of them is sufficient. The example below returns articles that contain both the phrase "electric vehicle" and the phrase "charging station".

```

            {
    "action": "getArticles",
    "keyword": ["electric vehicle", "charging station"],
    "keywordOper": "and",
    "keywordSearchMode": "phrase",
    "apiKey": "YOUR_API_KEY"
}
```

## Exact search mode

The `exact` mode enables a full **Boolean query language** inside a single `keyword` value. Use it when a simple phrase is not expressive enough and you need to combine several conditions — for example requiring some terms, excluding others, or demanding that words appear close to each other. Any sequence of consecutive words that are not operators is treated as a phrase, so you can freely mix phrases and operators.

The following operators are supported:

| Operator | Meaning |
| --- | --- |
| `AND` | Both operands must be present in the article. |
| `OR` | At least one of the operands must be present. |
| `NOT` | Excludes articles that contain the operand. |
| `NEXT/X` | The words must appear in the given order, at most X words apart. |
| `NEAR/X` | The words must appear within X words of each other, in any order. |

You can group sub-expressions with parentheses, and the operator precedence (from highest to lowest) is `NEAR/x, NEXT/x` > `NOT` > `AND` > `OR`. The example below returns articles that mention a smartphone from either Apple or Samsung, while excluding any article that also mentions a lawsuit.

```

            {
    "action": "getArticles",
    "keyword": "(Apple OR Samsung) AND smartphone NOT lawsuit",
    "keywordSearchMode": "exact",
    "apiKey": "YOUR_API_KEY"
}
```

The proximity operators are useful when two terms are only relevant when mentioned together. The next example finds articles where "Siemens" appears within 15 words of a sustainability-related term. Consecutive words that are not operators, such as `renewable energy`, are automatically treated as a phrase, so there is no need to wrap them in quotes.

```

            {
    "action": "getArticles",
    "keyword": "Siemens NEAR/15 (sustainability OR ecology OR renewable energy)",
    "keywordSearchMode": "exact",
    "apiKey": "YOUR_API_KEY"
}
```

## Simple search mode

The `simple` mode provides a **Google-like, relevance-based search**. The words in the `keyword` value are treated as individual terms, and articles do have to contain all of them — articles that match more of the terms are simply considered more relevant. Use this mode when you have a longer, free-text description of a topic and you want the best matching articles rather than a strict filter.

Because not all terms are required, the ordering of the results matters a great deal. We recommend sorting the results by relevance by setting `articlesSortBy` to `rel`, so the best matches appear first.

```

            {
    "action": "getArticles",
    "keyword": "tesla self driving car number of fatal accidents",
    "keywordSearchMode": "simple",
    "articlesSortBy": "rel",
    "apiKey": "YOUR_API_KEY"
}
```

## Choosing the right search mode

| Mode | Use it when... | Matching behavior |
| --- | --- | --- |
| `phrase`(default) | You are looking for a specific term or multi-word concept and want precise results. | Matches the exact phrase — all words, adjacent and in order. |
| `exact` | You need to combine conditions with `AND`/`OR`/`NOT` or require terms to appear close together. | Full Boolean logic with proximity operators; results strictly satisfy the expression. |
| `simple` | You have a longer, free-text description and want the most relevant articles, not a strict filter. | Relevance-based; articles need not contain all terms. Best used with `articlesSortBy: "rel"`. |