Query Syntax
This page shows how you write the q parameter of the Search endpoint and the
Top Headlines endpoint.
Besides plain keywords, q takes exact phrases, parentheses, and the AND, OR, and NOT operators. On this page, "query"
means the value of q, not the whole query string of the URL.
Rules every query follows:
- URL-encode the query.
- Separate words and operators with a single space.
- Write operators in capital letters:
andis searched as a word. - Put quotes around any word with a character other than a letter or a digit:
| Not valid | Valid |
|---|---|
| Hello! | "Hello!" |
| Left - Right | "Left - Right" |
| Question? | "Question?" |
- Close every parenthesis you open.
A query that breaks these rules returns a 400 error with a syntax error message: see Error Handling.
Exact phrase
Words in quotes match that exact sequence. "artificial intelligence" returns articles that contain these two words, in this order, at least once.
AND
Every keyword must match. A space works as AND, so AI companies is the same as AI AND companies.
OR
Either keyword can match. AI OR robotics returns articles about AI as well as articles about robotics.
OR has higher precedence than AND. AI AND chips OR robotics is read as AI AND (chips OR robotics), which returns articles about AI and chips, or about AI and robotics. To get articles about AI chips, or about robotics, add parentheses: (AI AND chips) OR robotics.
NOT
Leaves out the articles that match. Put NOT in front of each word or exact phrase to exclude: AI NOT chatbots returns articles about AI that don't mention chatbots.
Examples of valid queries
| Query |
|---|
| AI technology |
| AI OR robotics |
| AI AND NOT chatbots |
| (AI OR robotics) AND (companies OR market) |
| "artificial intelligence" AND NOT "machine learning" |
| AI AND ("data center" OR "data centers") |
| (AI AND ("data center" OR "data centers")) AND NOT crypto AND NOT "social media" |
A query only searches the articles your plan can reach: see Article Availability.