Filters Reference

Escaping reserved characters

If you need to use any of the characters which function as operators in your query itself (and not as operators), then you should escape them with a leading backslash. For instance, to search for external_links:https://www.linkedin.com, you would need to write your query as external_links:https\:\/\/www.linkedin.com

The reserved characters are: + – = && || > < ! ( ) { } [ ] ^ ” ~ * ? : \ /

Failing to escape these special characters correctly could lead to a syntax error which prevents your query from running.

Content Filters

ParameterDescriptionExample
languageThe language of the article. The default is any.Find articles in French or Italian:

(language:french OR language:italian)
authorReturn articles written by a specific authorFind articles written by Admin:
author:Admin
textA textual Boolean query describing the keywords that should (or shouldn’t) appear in the article text.text:(apple OR android)
has_videoA Boolean parameter that returns results for web pages containing embedded video.has_video:true
external_linksReturns articles that link to specified URL.Search for articles that linked to LinkedIn (note that both the slashes and colons are prefixed by a backslash):

external_links:https\:\/\/www.linkedin.com*

Site Filters

ParameterDescriptionExample
siteFilter by domain source.Limit the results to articles from Yahoo or CNN:
(site:yahoo.com OR site:cnn.com)
countryCountry associated with a given source based on TLD and language. Default country for dot-com URLs in English is USA.Return articles from sites from Hong Kong:
country:HK

To get the full country code list, visit countrycode.org.
site_suffixFilter by top level domain (TLD).Return articles from sites where their top level domain (TLD) ends with .fr:

site_suffix:fr
site_fullFilter sites based on the domain and optionally by their sub-domainReturn articles from Yahoo answers:

site_full:answers.yahoo.com
external_links:https\:\/\/www.linkedin.com*
site_categoryLimit the results to articles originating from sites categorized as one (or more)Return articles from sites categorized as sports or games related:
(site_category:sports OR site_category:games)
domain_rankFilter by traffic rank (lower rank indicates higher traffic).Search for articles from the top 1,000 sites:

domain_rank:<1000

Article Filters

An article contains global information about the content of the whole page and its content.

ParameterDescriptionExample
titleA textual Boolean query describing the keywords that should (or shouldn’t) appear in the article title.Search for articles containing the word "glass" and not "metal" in their title:

title:glass -title:metal
section_titleA textual Boolean query describing the keywords that should (or shouldn’t) appear in the site’s section where the article was publishedSearch for the articles containing the word food only under sections with a title that contains the word "restaurants":

food AND section_title:restaurants
spam_scoreA score value between 0 to 1, indicating how spammy the article text is.Return articles with spam score lower or equals to 0.8:

spam_score:<=0.8

Social Filters

ParameterDescriptionExample
performance_scoreA virality score for articles. The score ranges between 0-10, where 0 means that the article didn't do well at all, i.e rarely or was never shared, to 10 which means that the article was on fire, shared thousands of times on Facebook.Search for articles with performance score higher than 8 (highly viral):

apple performance_score:>8
social.facebook.likesReturn articles filtered by the number of Facebook likes.Return articles with more than 10 Facebook likes:
social.facebook.likes:>10
social.facebook.sharesReturn articles filtered by the number of Facebook shares.Return articles with more than 10 Facebook shares:
social.facebook.shares:>10
social.facebook.commentsReturn articles filtered by the number of Facebook comments.Return articles with more than 10 Facebook comments:
social.facebook.comments:>10
social.gplus.sharesReturn articles filtered by the number of Google Plus shares.Return articles with more than 10 Google Plus shares:
social.gplus.shares:>10
social.pinterest.sharesReturn articles filtered by the number of Pinterest shares.Return articles with more than 10 Pinterest shares:
social.pinterest.shares:>10
social.stumbledupon.sharesReturn articles filtered by the number of Stumbledupon shares.Return articles with more than 10 Stumbledupon shares:
social.stumbledupon.shares:>10
social.vk.sharesReturn articles filtered by the number of VK shares.Return articles with more than 10 VK shares:
social.vk.shares:>10

Entities & Sentiment Filters

We extract entities such as Persons, Organizations and Locations from all the English articles we crawl. We detect the sentiment attached to Persons and Organizations (not Locations) from the top news outlets.

ParameterDescriptionExample
personFilter by person name (recommended only for disambiguation, otherwise you should use a simple keyword search)person:"barack obama"
organizationFilter by organization/company name (recommended only for disambiguation, otherwise you should use a simple keyword search)organization:"apple"
locationFilter by location name (recommended only for disambiguation, otherwise you should use a simple keyword search)location:"germany"
[entity].[sentiment]Find an entity with a sentiment context attached to it.person.positive:"obama"
organization.negative:"apple"
organization.neutral:"google"

Filters Reference

Escaping reserved characters

If you need to use any of the characters which function as operators in your query itself (and not as operators), then you should escape them with a leading backslash. For instance, to search for external_links:https://www.linkedin.com, you would need to write your query as external_links:https\:\/\/www.linkedin.com

The reserved characters are: + – = && || > < ! ( ) { } [ ] ^ ” ~ * ? : \ /

Failing to escape these special characters correctly could lead to a syntax error which prevents your query from running.

Post Content Filters

ParameterDescriptionExample
languageThe language of the article. The default is any.Find articles in French or Italian:

(language:french OR language:italian)
authorReturn articles written by a specific authorFind articles written by Admin:
author:Admin
textA textual Boolean query describing the keywords that should (or shouldn’t) appear in the article text.text:(apple OR android)
has_videoA Boolean parameter that returns results for web pages containing embedded video.has_video:true
external_linksReturns articles that link to specified URL.Search for articles that linked to LinkedIn (note that both the slashes and colons are prefixed by a backslash):

external_links:https\:\/\/www.linkedin.com*

Site Filters

ParameterDescriptionExample
siteFilter by domain source.Limit the results to articles from Yahoo or CNN:
(site:yahoo.com OR site:cnn.com)
countryCountry associated with a given source based on TLD and language. Default country for dot-com URLs in English is USA.Return articles from sites from Hong Kong:
country:HK

To get the full country code list, visit countrycode.org.
site_suffixFilter by top level domain (TLD).Return articles from sites where their top level domain (TLD) ends with .fr:

site_suffix:fr
site_fullFilter sites based on the domain and optionally by their sub-domainReturn articles from Yahoo answers:

site_full:answers.yahoo.com
external_links:https\:\/\/www.linkedin.com*
site_categoryLimit the results to articles originating from sites categorized as one (or more)Return articles from sites categorized as sports or games related:
(site_category:sports OR site_category:games)
domain_rankFilter by traffic rank (lower rank indicates higher traffic).Search for articles from the top 1,000 sites:

domain_rank:<1000

Article Filters

An article contains global information about the content of the whole page and its content.

ParameterDescriptionExample
titleA textual Boolean query describing the keywords that should (or shouldn’t) appear in the article title.Search for articles containing the word "glass" and not "metal" in their title:

title:glass -title:metal
section_titleA textual Boolean query describing the keywords that should (or shouldn’t) appear in the site’s section where the article was publishedSearch for the articles containing the word food only under sections with a title that contains the word "restaurants":

food AND section_title:restaurants
spam_scoreA score value between 0 to 1, indicating how spammy the article text is.Return articles with spam score lower or equals to 0.8:

spam_score:<=0.8

Social Filters

ParameterDescriptionExample
performance_scoreA virality score for articles. The score ranges between 0-10, where 0 means that the article didn't do well at all, i.e rarely or was never shared, to 10 which means that the article was on fire, shared thousands of times on Facebook.Search for articles with performance score higher than 8 (highly viral):

apple performance_score:>8
social.facebook.likesReturn articles filtered by the number of Facebook likes.Return articles with more than 10 Facebook likes:
social.facebook.likes:>10
social.facebook.sharesReturn articles filtered by the number of Facebook shares.Return articles with more than 10 Facebook shares:
social.facebook.shares:>10
social.facebook.commentsReturn articles filtered by the number of Facebook comments.Return articles with more than 10 Facebook comments:
social.facebook.comments:>10
social.gplus.sharesReturn articles filtered by the number of Google Plus shares.Return articles with more than 10 Google Plus shares:
social.gplus.shares:>10
social.pinterest.sharesReturn articles filtered by the number of Pinterest shares.Return articles with more than 10 Pinterest shares:
social.pinterest.shares:>10
social.stumbledupon.sharesReturn articles filtered by the number of Stumbledupon shares.Return articles with more than 10 Stumbledupon shares:
social.stumbledupon.shares:>10
social.vk.sharesReturn articles filtered by the number of VK shares.Return articles with more than 10 VK shares:
social.vk.shares:>10

Entities & Sentiment Filters

We extract entities such as Persons, Organizations and Locations from all the English articles we crawl. We detect the sentiment attached to Persons and Organizations (not Locations) from the top news outlets.

ParameterDescriptionExample
personFilter by person name (recommended only for disambiguation, otherwise you should use a simple keyword search)person:"barack obama"
organizationFilter by organization/company name (recommended only for disambiguation, otherwise you should use a simple keyword search)organization:"apple"
locationFilter by location name (recommended only for disambiguation, otherwise you should use a simple keyword search)location:"germany"
[entity].[sentiment]Find an entity with a sentiment context attached to it.person.positive:"obama"
organization.negative:"apple"
organization.neutral:"google"