Advanced query

Query String

query_string

A query string is composed of one or more clauses separated by AND or OR keywords. A clause can be a term (a string without white spaces in it), a quoted term (a string of characters enclosed with "), or a nested query string enclosed in parentheses.

A single clause can not contain both AND and OR at the same time: add parentheses accordingly.

this is not a querystring of the url! This is a query 'string', so an attribute of the query object, which is itself an attribute of the method.

Term

A term must contain only letters and numbers (including accented letters, and letters from any script). As an exception, a term can start with @ or # character.

Examples:

NASA
Voilà
@NASA

Wildcards

If a term contains the * or ? characters, it's a wildcard term. In a wildcard term, * matches one or more term character, and ? matches exactly one term character.

Query

Match

Not Match

astro*

astronomy, astrophysics

astral, astro

201?

2010, 2011

201, 2020, 20201

Note: not all accounts have access to wildcard terms.

Quoted term

A quoted term can contain any character. The only exception is that " or \ must be preceded by \.

Examples:

"Space Station"
"Jason-3"

Quoted terms match if all the keyword are present, in order, and next to each other.

Proximity

You can allow some distance between words by using the proximity operator ~ followed by the maximum distance allowed between each them.

The distance is the difference of the second word's position, relative to the first word, in the query and in the mention. For example, in the query "Create Alert"~1, the second word is at position 1 relative to the first one; in the mention This will create an alert, the word alert is at position 2 relatively to create. So the distance is 2-1: 1. Note that this allows words to be in opposite order if the proximity constraint is 2 or more.

The proximity can not be lower than 1, or upper than 6.

Examples:

Query

Match

Not Match

"Mars Rover"~1

"Mars Rover", "Mars Exploration Rover Missiong"

"Rover on Mars"

"Mars Rover"~3

"Rover on Mars"

Punctuation in quoted terms

If you expect your quoted terms to appear with and without punctuation, specify both forms in your query for best results.

Near

It is possible to specify the maximum distance between two terms or quoted terms by using the NEAR operator:

Query

Match

Not Match

"the ISS" NEAR/3 "its orbit"

"The ISS raised its orbit today"

("the ISS" OR "international space station") NEAR/3 "its orbit"

"The international space station raised its orbit today"

The proximity can not be lower than 1, or upper than 6.

Negation

A clause can be negated by prefixing it with the - character, or the NOT operator:

"Space Station" AND -"MIR"
"Planet" AND NOT ("Pluton" OR "Moon")

Note that there must be not whitespace after a -. Other than that, - and NOT are strictly equivalent.

Punctuation

Punctuation in quoted terms is taken into account when matching mentions.

Examples:

Query

Match

Not Match

"Yahoo!"

Yahoo!, yahoo !

Yahoo.

"M&M's"

M&M's

M&Ms, MMs, M&M’s

"M&M's" OR "M&M’s" OR "M&Ms"

M&M's, M&M’s, M&Ms, M & M's

MMs

"youtube.tv"

youtube.tv

youtube tv

"Coca-Cola"

coca-cola

coca cola

"Coca Cola"

coca cola

coca-cola

"Coca Cola"~1

coca cola, coca-cola, coca/cola

Restrictions

A query string can not exceed 1700 characters (measured in unicode code points)

An OR clause can not contain a negative clause. Example: "Space Station" OR -"MIR" is not valid.

An OR clause can not contain a clause who consits only of one stop word. You can still match a stop word by associating it with other words in a AND clause, or in a quoted term. Examples: The OR Space Station is invalid. "The Space Station" or "The" AND "Space Station" are valid. Current list of stop words: a, an, and, at, but, by, com, from, http, https, if, in, is, it, its, me, my, or, rt, the, this, to, too, via, we, www, you.

A query string can not consist only of negative clauses

A term can not be longer than 128 characters (measured in unicode code points)

Languages

languages

An array of language codes. All languages that you can select as origin of the alert can be listed via the app/data request, where there is an alert language section. Currently, you are limited to 5 languages.

On alerts with query.type="advanced", the languages attribute applies only to monitored pages and reviews pages.

Countries

countries

An array of countries from which mentions should be tracked. By default, no country is "filtered out". All countries that you can select as origin of the alert can be listed via the app/data request, where there is an alert countries section. Currently, you are limited to 5 countries if you want to filter some countries out.

Sources

In case you are using monitored_facebook_page and/or monitored_twitter_account, you have to add facebook and/or twitter to sources.

Blocked sites

blocked_sites

An array of blocked sites from which you don't want mentions to be tracked.

A mention is blocked if its URL is matched by any of the blocked URLs.

A blocked URL matches a mention’s URL if the blocked URL equals the mention’s URL, or if the mention’s URL starts with the blocked URL and is followed by one of [/.?&#].

http:// in blocked URLs also match https:// and vice-versa.

The following characters are ignored, when they appear at the end of blocked URLs: /.?&#.

Noise detection

noise_detection

We have a noise detector that strive to detect mentions that might meet your criteria, but not what you are looking for. It will watch your behaviour when you put mentions in spam and trash, and will try to skip similar mentions. It is a helper to avoid you to reach quota because of spam; but it may skip mentions you would have liked to seem from time to time.

Reviews Pages

reviews_pages

For 3 reviews website, tripadvisor, yelp, and booking, we allow you to list urls of reviews page that we will monitor.

Color

color

This defines a color to be set to the alert in dashboards, reports, etc... Available colors can be found in the colors attribute in the app endpoint.

Stats

Contains statistics about the alert:

mention number by source

mention number by folder

tasks

...

Shares

Array listing who has access to the alert. When you create an alert, your account is the only item in shares; however, once the alert gets shared, all accounts it is shared with are listed in this array.

Index version

Indicates the 'search' version of the Alert. 'Search' version is a version of the search feature. For a given alert, a specific 'search' version will indicate if a specific attribute is available in the search for that Alert. In order to know which attributes are available for search for the version of your alert, check this.