Keyword search modes

When you search for content using the keyword parameter, you can control how 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 Search query language 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.

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 and); 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".

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:

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.

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.

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 not 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.

Choosing the right search mode