Comment on page
How to get the most out of the q parameter
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:
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
'lang=en'will match articles with related word forms like
As a general rule of thumb, you should always put people and company names in double quotes.
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
'Tesla'to be present in the returned news articles, use the AND operator in the
'q'parameter like this:
q=Microsoft AND Tesla
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)
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"'
'*'to match any string in any quantity.
'?'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'
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
'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
'Edge'are within 15 words of each other.
- 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.
- 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
- 4.During initial API calls, check the
'user_input'list in the JSON response to confirm that our API interpreted your keywords as intended.
'NEAR(phrase_A, phrase_B, distance)'enables you to search for articles where phrase B appears within
distancewords of phrase A.