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.

Lucene query strings

When you make an API call, we use the Lucene Query Parser to read it. This introduces some important considerations.

Number of filters are limited

You may apply up to 20 filters, and each filter allows up to 150 terms. The calculation of this is based on Lucene Query String semantics. For example:

  • country_code:us counts as 1 term.
  • country_code:(us OR uk) counts as 2 terms.
  • headline: “The Right Way” counts as 3 terms.

Special characters

Special characters + - && || ! ( ) { } [ ] ^ “ ~ * ? : \ / are reserved for the Lucene Query String parser, so you’ll need to escape them with \ before the character if you need to use it.

For example, f-150 should be wrapped up as f\-150, or wrapped inside double quotes as "f-150".

Please note that "" will replace the special characters inside with empty space, so f\-150 will be counted as 1 term while "f-150" is counted as 2 terms.