Filtering tips

Here are a few tips for getting the most out of using the filters parameter in our POST endpoints.

It's required, but can be empty

You always need to include the filters field, but it can be empty. If you don't need to filter, just leave it blank:

"filters": []

Keep your filters together

A common mistake is to comma separate multiple filters within quotes, assuming that this means that the values will be joined using an AND operator. This is not the case.

The below filter would be interpreted as "filter for content that is from the US OR has Rihanna in the headline".

"filters": ["country_code:us", "headline:rihanna"]

If you need to join filters with an AND operator, use something like this instead:

"filters": ["country_code:us AND headline:rihanna"]

Operators

You can use the following operators in filters.

• AND to specify two or more things that must be true.
• OR to specify two things that could be true, but are not dependent on one another.
• - or NOT to specify that something should be excluded.

For example, the following would be interpreted as "filter for content that is from the US and is not published on Youtube, and where Rihanna is in the headline".

"filters": ["country_code:us AND -publisher:youtube.com AND headline:rihanna"]

Using multiple strings

If you have multiple strings you'd like to use in your filter with an operator, group them together in parentheses and surround your strings with quotation marks. For example:

"filters": ["headline:(\"rihanna\" AND \"britney\")"]