Advance Querying

How to get the most out of the q parameter

Exact Match ("double quotes")

To perform an exact match search, enclose your query in double quotes ("). For instance, if you're looking for articles that mention "Tim Cook," use the following query: q="Tim Cook"

Without double quotes, the query will be treated as a combination of the individual terms, such as q='Tim' AND 'Cook'. In this case, any article mentioning both 'tim' and 'cook' will match.

Additionally, specifying 'lang=en' will match articles with related word forms like 'cooks', 'cooking' and 'cooked'.

As a general rule of thumb, you should always put people and company names in double quotes.

Boolean Operators

AND Operator

The AND operator ensures that both keywords on either side must be present in the text. AND is the default operator, and when your query input consists of more than one word, AND is automatically added between each word. For example, these queries are equivalent:

q='Apple Microsoft Tesla'
q='Apple AND Microsoft AND Tesla'

If you want both 'Microsoft' and 'Tesla' to be present in the returned news articles, use the AND operator in the 'q' parameter like this:

q=Microsoft AND Tesla

OR Operator

The OR operator means that either the left or the right side of the OR must be satisfied. Use grouping when you want to group a set of tokens logically. For example:

q=(Apple AND Cook) OR (Microsoft AND Gates) 

NOT Operator

The NOT operator is used when you want to exclude a specific token from the search results. For example, if you're looking for articles about 'Tesla' but not about 'Elon Musk' use the 'q' parameter as follows:

q='Tesla NOT "Elon Musk"'

Wildcards (* and ?)

• Use '*' to match any string in any quantity.

• Use '?' to match any string exactly once.

For example, if you want to search for articles that mention 'Microsoft' and any C-level officers:

q='Microsoft AND C?O'

Proximity Based Searching (NEAR)

In V3, we introduced a new operation called NEAR within the query parameter. NEAR enhances the functionality of the existing AND operator by considering the proximity of keywords in your queries. The syntax for this operation is as follows:

q = 'NEAR("phrase_A", "phrase_B", distance, in_order(default False))'

With this structure, you can find articles where phrase B appears within a specified distance of words after phrase A. By default, the in_order parameter is set to False, but when set to True, it ensures that phrase B appears after phrase A.

To illustrate this, let's imagine you're searching for news about Microsoft's Edge browser. While some articles may mention Edge browser exactly as such, many others may discuss edge and browser in the same sentence but not right next to each other. To precisely match articles about Microsoft's Edge browser, you can use the following query:

q = 'NEAR("browser", "Edge", 15)'

This query refines the results to articles where browser and Edge are within 15 words of each other.

Limitations of the NEAR operator

• NEAR is designed for search phrases consisting of a maximum of four words: NEAR("A B C D", "W X Y Z", distance)

• Using NEAR, you can look for a maximum of three phrases at a time: NEAR("phrase_A", "phrase_B", "phrase_C", distance)

• The distance parameter has a maximum limit of 100 words.

TL;DR

1. Default behavior: Tokens in the 'q' parameter are combined with the AND operator, requiring each token to be present in the text at least once. For instance, 'q=Apple Microsoft' is equivalent to 'q=Apple AND Microsoft.'

2. Always use double quotes (") when searching for companies, person names, etc. For instance, when looking for articles mentioning Tim Cook, use 'q="Tim Cook"' instead of 'q=Tim Cook'

3. When making GET requests, ensure that the content passed in the 'q' parameter is URL-encoded.

4. During initial API calls, check the 'user_input' list in the JSON response to confirm that our API interpreted your keywords as intended.

5. 'NEAR(phrase_A, phrase_B, distance)' enables you to search for articles where phrase B appears within distance words of phrase A.