Welcome to the NewsWhip Developer Hub!

NewsWhip APIs give you raw access to the world’s largest and fastest human engagement database; real time data trends, aggregated data, statistics, and social engagement metrics for hundreds of millions of stories, tracked since January 1, 2014.

Use the power of NewsWhip data to create and customize your own solutions, perfectly suited to your company’s goals. In the hub you'll find the information you need to be successful with our API.

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"]


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\")"]

Updated 3 years ago

Filtering tips

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.