Query Syntax

The q parameter accepts more than a list of words: you can search for exact phrases and combine keywords with the logical operators AND, OR and NOT. This page applies to both the Search endpoint and the Top Headlines endpoint.

Things to know before you start:

1. On this page, the word query refers to the value of the q parameter and not to the HTTP request.
2. The query must be URL-encoded.
3. It is not possible to use special characters without putting quotes around them.

Example:

Not Valid	Valid
Hello!	"Hello!"
Left - Right	"Left - Right"
Question?	"Question?"

A query that does not respect this syntax is rejected with a 400 - Bad Request, see Error Handling.

Phrase Search Operator

This operator allows you to make an exact search. Keywords surrounded by quotation marks are used to search for articles with the exact same keyword sequence. For example the query: "Apple iPhone" will return articles matching at least once this sequence of keywords.

Logical AND Operator

This operator allows you to make sure that several keywords are all used in the article search. By default the space character acts as an AND operator, it is possible to replace the space character by AND to obtain the same result. For example the query: Apple Microsoft is equivalent to Apple AND Microsoft

Logical OR Operator

This operator allows you to retrieve articles matching the keyword a or the keyword b. It is important to note that this operator has a higher precedence than the AND operator. For example the query: Apple OR Microsoft will return all articles matching the keyword Apple as well as all articles matching the keyword Microsoft

Due to the higher precedence of the operator OR the following query will not work as expected: Apple AND iPhone OR Microsoft. Normally, articles matching the keywords Apple and iPhone are returned first and then articles matching the keyword Microsoft are returned. Because of the precedence of the OR operator, in practice the query will return articles matching Apple AND iPhone or Apple AND Microsoft. To have a normal behavior, it is necessary to add brackets. The query Apple AND iPhone OR Microsoft will behave normally when it is in this form: (Apple AND iPhone) OR Microsoft

Logical NOT Operator

This operator allows you to remove from the results the articles corresponding to the specified keywords. To use it, you need to add NOT in front of each word or phrase surrounded by quotes. For example the query: Apple NOT iPhone will return all articles matching the keyword Apple but not the keyword iPhone

Examples of Valid Queries

Query
Microsoft Windows 11
Apple OR Microsoft
Apple AND NOT iPhone
(Windows 10) AND (Windows 11)
"Apple iPhone 17" AND NOT "Apple iPhone 16"
NASA AND ("Artemis program" OR "James Webb")
(NASA AND ("Artemis program" OR "Moon landing")) AND NOT SpaceX AND NOT "Blue Origin"

Keep in mind that a query only searches the articles your plan can reach, see Article Availability.