Common resources

Filters

filters should be an object passed in JSON request body. It can contain any of the following filters. Each of these filters must be satisfied (AND). When a filter have several values, any of its values should be satisfied (OR).

Author

Get only mentions whose author has one of these Synthesio ID.

{
    "filters": {
        "authors": [
            "9938-154765825",
            "22249-1545454855555"
        ]
    }
}

Filter mentions by authors.

Format

• authors: (array[string])

Author affinities

{
    "filters": {
        "author_affinities": [
            "Video games",
            "Movies"
        ]
    }
}

Filter mentions by author affinities.

Format

• author_affinities (array[string])

Author age

{
    "filters": {
        "author_ages": [
            "<18years",
            "18-29years"
        ]
    }
}

Filter mentions by author age.

Format

• author_ages (array[string])

Author bio tags

{
    "filters": {
        "author_bio_tags": [
            "synthesio"
        ]
    }
}

Filter mentions by author bio tags.

Format

• author_bio_tags (array[string])

Author cities

{
    "filters": {
        "author_cities": [
            "Paris",
            "London"
        ]
    }
}

Filter mentions by authors’ cities. Only available on twitter mentions.

All others mentions will be automatically excluded. Filtering on medias, excluding twitter and on cities will produce an empty result set.

Cities names are obtained through a geolocalization service, but normalization is still incomplete. For example for San Fransisco, value can be "San Fransisco" or "SF".

Format

• author_cities (array[string])

Author family status

{
    "filters": {
        "author_family_statuses": [
            "Children"
        ]
    }
}

Filter mentions by author family statuses.

Format

• author_family_statuses (array[string])

Author gender

{
    "filters": {
        "author_genders": [
            "unknown",
            "male"
        ]
    }
}

Filter mentions by author gender.

Format

• author_genders (array[string])

Author jobs

{
    "filters": {
        "author_jobs": [
            "Education & Academics"
        ]
    }
}

Filter mentions by author jobs.

Format

• author_jobs (array[string])

Author languages

{
    "filters": {
        "author_languages": [
            "fra",
            "eng"
        ]
    }
}

Format

• author_languages (array[string]): ISO 639-3 codes (3 letters code). See Language resource

Author marital status

{
    "filters": {
        "author_marital_statuses": [
            "Couple"
        ]
    }
}

Format

• author_marital_statuses (array[string])

Author states

{
    "filters": {
        "author_states": [
            "Ile de France",
            "Oregon"
        ]
    }
}

Filter mentions by authors’ states. Only available on twitter mentions.

All others mentions will be automatically excluded. Filtering on medias, excluding twitter and on states will produce an empty result set.

States names are obtained through a geolocalization service, but normalization is still incomplete. For example for Ile de France, value can be "Ile de France" or "IDF".

Format

• author_states (array[string])

Boolean Filter

Get only mentions that are in english AND are reviewed ; are either are from France OR whose author come from Oregon ; and aren’t authored by a teacher.

{
    "filters": {
        "boolean": {
            "must": {
                "languages": [
                    "en"
                ],
                "human_review_statuses": [
                    "reviewed"
                ]
            },
            "should": {
                "countries": [
                    "FRA"
                ],
                "author_states": [
                    "Oregon"
                ]
            },
            "must_not": {
                "author_jobs": [
                    "Education & Academics"
                ]
            }
        }
    }
}

Get only mentions that aren’t in english.

{
    "filters": {
        "boolean": {
            "must_not": {
                "languages": [
                    "en"
                ]
            }
        }
    }
}

Get only mentions that are from France, or are in french.

{
    "filters": {
        "boolean": {
            "should": {
                "languages": [
                    "fr"
                ],
                "countries": [
                    "FRA"
                ]
            }
        }
    }
}

Allow boolean operations between filters. Only match mention who :

• match ALL filters in the “must” filter set

• match AT LEAST ONE filter in the “should” filter set

• match NONE of the filter in the “must_not” filter set You can omit one or two of theses arguments, in which case they are ignored.

Format

• must (object) - Object must be a valid filter set. Optional.

• should (object) - Object must be a valid filter set. Optional.

• must_not (object) - Object must be a valid filter set. Optional.

Channels

{
    "filters": {
        "channels": [
            "owned"
        ]
    }
}

Filter mentions by owned/earned channels. Not available for all reports.

Format

• channels (array[string]). Available values:

  • earned

  • owned

Collaboration

{
    "filters": {
        "collaboration_users": [
            1,
            2
        ],
        "collaboration_statuses": [
            1,
            5
        ]
    }
}

Allow to filter on collaboration statuses and users. Collaboration features must be enabled in the report for this filter to work. If used on a report without collaboration support, result set will be empty.

Format

• collaboration_users (array[integer]): collaboration users ID.

• collaboration_statuses (array[integer]): collaboration statuses ID.

Communities

{
    "filters": {
        "communities": [
            15,
            17
        ]
    }
}

Filter mentions by communities.

Format

• communities (array[integer])

Countries

{
    "filters": {
        "countries": [
            "FRA",
            "USA"
        ]
    }
}

Format

• countries (array[string]): ISO 3166-1 alpha-3 codes. See Country resource

Crawled At

{
    "filters": {
        "crawled_at": {
            "begin": "2016-04-22T00:09:00Z"
        }
    }
}

Filter by the date at which Synthesio fetched the mention.

Format

• crawled_at (object): must have at least one of begin/end properties.

  • begin (string, ISO8601): Exclude mentions crawled before this date.

  • end (string, ISO8601): Exclude mentions crawled after this date.

  • include_bounds (boolean, optional): Default to true.

Human review status

{
    "filters": {
        "human_review_statuses": [
            "reviewed",
            "deleted"
        ]
    }
}

Filter mentions by human review status.

Format

• human_review_statuses (array[string]). Available values:

  • unreviewed

  • reviewed

  • deleted

Influence

{
    "filters": {
        "influence": {
            "begin": 250,
            "end": 1000
        }
}

Filter mentions by influence.

Format

• (object). Must have at least on of begin / end properties.

• begin (integer): mentions’ influence value must be greater than or equal to this value.

• end (integer): mentions’ influence value must be less than or equal to this value.

Influencers

{
    "filters": {
        "influencers": {
            "authors": [
                "9938-1245554",
                "21711-57895456"
            ],
            "sources": [
                "22249-5478525236",
                "9938-548788889"
            ],
            "sites": [
                "12345",
                "56789"
            ]
        }
    }
}

Filter on favorites influencers, user-defined collection of authors, sites, and sources.

Format

• influencers: (object) - Must have at least one of the following properties.

  • authors (array[string], optional) - See Authors filter

  • sources (array[string], optional) - See Sources filter

  • sites (array[number], optional) - See sites in Medias filter

Infused at

{
    "filters": {
        "infused_at": {
            "begin": "2016-04-22T00:09:00Z"
        }
    }
}

Filter by the date at which the mentions where added to the report.

Format

• infused_at (object): must have at least one of begin/end properties.

  • begin (string, ISO8601): Exclude mentions added to the report before this date.

  • end (string, ISO8601): Exclude mentions added to the report after this date.

Languages

{
    "filters": {
        "languages": [
            "fra",
            "eng"
        ]
    }
}

Format

• languages (array[string]): ISO 639-3 codes (3 letters code). See Language resource

Medias

Get only mentions from Twitter (9938) or Forums (11).

{
    "filters": {
        "medias": {
            "sites": [
                9938
            ],
            "site_types": [
                11
            ]
        }
    }
}

Filter mentions by source media.

As Synthesio have a lot of different sites, there is two notions. Sites type and sites. Here is a list of all our site types.

List of main site types ID:

Site type	ID
National newspaper	1
Regional newspaper	2
Institution, government	3
Professional news, Industry news	4
Company	5
General news, Magazine	7
News agency	8
Blog	9
TV, radio	10
Forum	11
Twitter	13
Video and Photo Sharing	14
Consumer opinions	15
Comments	16
Social network	17
Facebook Community App	20
Hosted Community	21

List of main sites IDs:

Site type	ID
Twitter	9938
Instagram	1650630
YouTube	21711
Flickr	39138
FaceBook	22249
V Kontakte	1109681

Format

• medias (object) - Object must have at least one of the following properties.

  • sites (array[number], optional) - Site ID list. Filter by requested sites.

  • site_types (array[number], optional) - Site Type ID list. Filter by requested site categories.

Medias groups

{
    "filters": {
        "media_groups": [
            "social"
        ]
    }
}

Format

• media_groups (array[string]). Available values are:

  • social

  • mainstream

Mention ID

{
    "filters": {
        "ids": [
            "38298-55237514657"
        ]
    }
}

Format

• ids (array[string]). Values must be mention IDs.

Period

{
    "filters": {
        "period": {
            "begin": "2016-04-22T00:09:00Z"
        }
    }
}

Filter by date or date range.

Format

• period (object): must have at least one of begin/end properties.

  • begin (string, ISO8601): Exclude mentions before this date.

  • end (string, ISO8601): Exclude mentions after this date.

  • include_bounds (boolean, optional): Default to true.

Query

{
    "filters": {
        "query": "synthesio AND \"new york\""
    }
}

Filter by given query. Query format is the same as the one used in the product.

Format

• query (string)

Ratings (Normalized)

{
    "filters": {
        "ratings_normalized": {
            "begin": 1.3,
            "end": 4.5
        }
}

Filter mentions by rating on a normalized value (between 0 and 100).

Format

• rating (object). Must have at least one of begin / end properties.

  • begin (float): mentions’ normalized rating value must be greater than or equal to this value.

  • end (float): mentions’ normalized rating value must be less than or equal to this value.

Review date

{
    "filters": {
        "review_date": {
            "begin": "2016-04-22T00:09:00Z"
        }
    }
}

Filter by the date at which the mentions were manually reviewed.

Format

• reviewed_at (object): must have at least one of begin/end properties.

  • begin (string, ISO8601): Exclude mentions added to the report before this date.

  • end (string, ISO8601): Exclude mentions added to the report after this date.

  • include_bounds (boolean, optional): Default to true.

Sentiments

Get only mentions with negative and neutral sentiment value.

{
    "filters": {
        "sentiments": [
            "negative",
            "neutral"
        ]
    }
}

Format

• sentiments (array[string]). Available values:

  • negative

  • positive

  • neutral

  • undefined

Sources

Get only mentions from given Facebook page and Youtube Channel.

{
    "filters": {
        "sources": [
            "21711-4202553",
            "22249-15454554"
        ]
    }
}

Filter mentions by sources.

Format

• sources: (array[string])

Synthesio rank

{
    "filters": {
        "synthesio_rank": {
            "begin": 1.3,
            "end": 4.5
        }
}

Filter mentions by Synthesio rank.

Format

• synthesio_rank (object). Must have at least one of begin / end properties.

  • begin (float): mentions’ Syntheiso rank value must be greater than or equal to this value.

  • end (float): mentions’ Synthesio rank value must be less than or equal to this value.

Tags

Get only mentions with taga or positive tagb.

{
    "filters": {
        "tags": [
            {
                "name": "taga"
            },
            {
                "name": "tagb",
                "sentiment": "positive"
            }
        ]
    }
}

Filter mentions by tags. When several tag are provided, filter out mentions who do not have any of these.

Format

• tags (array[object])

  • name (string, required): Tag name

  • sentiment (string, optional): Sentiment value to apply to this tag.

Sentiments on a tags is a special feature that must be enabled in you reports to be available. The sentiment value for one given mention can be different in each topic.

Title

Get only mentions with this exact title.

{
    "filters": {
        "titles": [
            "Get only mentions with this exact title"
        ]
    }
}

Filter mentions by titles. This filter can be used to find after an analytics query to find top retweets.

Format

• titles (array[string])

Twitter types

{
    "filters": {
        "twitter_types": [
            "retweet",
            "quoted-retweet"
        ]
    }
}

Allow to filter on retweets.

Field has no values if it’s neither a retweet nor a quoted retweet. To exclude all retweets a boolean must_not filter should be used.

Format

• twitter_types (array[string]). Available types:

  • retweet

  • quoted-retweet

Types

{
    "filters": {
        "types": [
            "post"
        ]
    }
}

Filter mentions by type.

Format

• types (array[string]). Available types:

  • comment

  • post

Country resource

Country codes from ISO 3166-1 alpha-3 list. Country names used here is the short version from the norm, [https://www.iso.org/obp/ui/].

First codes in bold below describe Synthesio usage of the norm’s reserved codes for local purposes. Following codes are sorted alphabetically by country name.

Code	Country
AAA	Undefined
ZZZ	Not available
AFG	Afghanistan
ALB	Albania
DZA	Algeria
AND	Andorra
AGO	Angola
AIA	Anguilla
ATA	Antarctica
ATG	Antigua and Barbuda
ARG	Argentina
ARM	Armenia
ABW	Aruba
AUS	Australia
AUT	Austria
AZE	Azerbaijan
BHS	Bahamas
BHR	Bahrain
BGD	Bangladesh
BRB	Barbados
BLR	Belarus
BEL	Belgium
BLZ	Belize
BEN	Benin
BMU	Bermuda
BTN	Bhutan
BOL	Bolivia, Plurinational State of
BIH	Bosnia and Herzegovina
BWA	Botswana
BRA	Brazil
BRN	Brunei Darussalam
BGR	Bulgaria
BFA	Burkina Faso
BDI	Burundi
CPV	Cabo Verde
KHM	Cambodia
CMR	Cameroon
CAN	Canada
CYM	Cayman Islands
CAF	Central African Republic
TCD	Chad
CHL	Chile
CHN	China
COL	Colombia
COM	Comoros
COG	Congo
COD	Congo, the Democratic Republic of the
COK	Cook Island
CRI	Costa Rica
CIV	Côte d’Ivoire
HRV	Croatia
CUB	Cuba
CYP	Cyprus
CZE	Czech Republic
DNK	Denmark
DJI	Djibouti
DMA	Dominica
DOM	Dominican Republic
ECU	Ecuador
EGY	Egypt
SLV	El Salvador
GNQ	Equatorial Guinea
ERI	Eritrea
EST	Estonia
ETH	Ethiopia
FLK	Falkland Islands (Malvinas)
FRO	Faroe Islands
FJI	Fiji
FIN	Finland
FRA	France
PYF	French Polynesia
GAB	Gabon
GMB	Gambia
GEO	Georgia
DEU	Germany
GHA	Ghana
GIB	Gibraltar
GRC	Greece
GRL	Greenland
GRD	Grenada
GLP	Guadeloupe
GTM	Guatemala
GIN	Guinea
GNB	Guinea-Bissau
GUY	Guyana
HTI	Haiti
VAT	Holy See (Vatican City State)
HND	Honduras
HKG	Hong Kong
HUN	Hungary
ISL	Iceland
IND	India
IDN	Indonesia
IRN	Iran, Islamic Republic of
IRQ	Iraq
IRL	Ireland
ISR	Israel
ITA	Italy
JAM	Jamaica
JPN	Japan
JOR	Jordan
KAZ	Kazakhstan
KEN	Kenya
KIR	Kiribati
PRK	Korea, Democratic People’s Republic of
KOR	Korea, Republic of
KWT	Kuwait
KGZ	Kyrgyzstan
LAO	Lao People’s Democratic Republic
LVA	Latvia
LBN	Lebanon
LSO	Lesotho
LBR	Liberia
LBY	Libya
LIE	Liechtenstein
LTU	Lithuania
LUX	Luxembourg
MAC	Macao
MKD	Macedonia, the former Yugoslav Republic of
MDG	Madagascar
MWI	Malawi
MYS	Malaysia
MDV	Maldives
MLI	Mali
MLT	Malta
MHL	Marshall Islands
MTQ	Martinique
MRT	Mauritania
MUS	Mauritius
MEX	Mexico
FSM	Micronesia, Federated States of
MDA	Moldova, Republic of
MCO	Monaco
MNG	Mongolia
MNE	Montenegro
MSR	Montserrat
MAR	Morocco
MOZ	Mozambique
MMR	Myanmar
NAM	Namibia
NRU	Nauru
NPL	Nepal
NLD	Netherlands
ANT	Netherlands Antilles
NCL	New Caledonia
NZL	New Zealand
NIC	Nicaragua
NER	Niger
NGA	Nigeria
NOR	Norway
OMN	Oman
PAK	Pakistan
PLW	Palau
PSE	Palestine, State of
PAN	Panama
PNG	Papua New Guinea
PRY	Paraguay
PER	Peru
PHL	Philippines
PCN	Pitcairn
POL	Poland
PRT	Portugal
PRI	Puerto Rico
QAT	Qatar
REU	Réunion
ROU	Romania
RUS	Russian Federation
RWA	Rwanda
SHN	Saint Helena, Ascension and Tristan da Cunha
KNA	Saint Kitts and Nevis
LCA	Saint Lucia
MAF	Saint-Martin (French part)
VCT	Saint Vincent and the Grenadines
WSM	Samoa
SMR	San Marino
STP	Sao Tome and Principe
SAU	Saudi Arabia
SEN	Senegal
SRB	Serbia
SYC	Seychelles
SLE	Sierra Leone
SGP	Singapore
SVK	Slovakia
SVN	Slovenia
SLB	Solomon Islands
SOM	Somalia
ZAF	South Africa
ESP	Spain
LKA	Sri Lanka
SDN	Sudan
SUR	Suriname
SWZ	Swaziland
SWE	Sweden
CHE	Switzerland
SYR	Syrian Arab Republic
TWN	Taiwan, Province of China
TJK	Tajikistan
TZA	Tanzania, United Republic of
THA	Thailand
TLS	Timor-Leste
TGO	Togo
TON	Tonga
TTO	Trinidad and Tobago
TUN	Tunisia
TUR	Turkey
TKM	Turkmenistan
TCA	Turks and Caicos Islands
TUV	Tuvalu
UGA	Uganda
UKR	Ukraine
ARE	United Arab Emirates
GBR	United Kingdom
USA	United States
URY	Uruguay
UZB	Uzbekistan
VUT	Vanuatu
VEN	Venezuela, Bolivarian Republic of
VNM	Viet Nam
VGB	Virgin Islands, British
YEM	Yemen
ZMB	Zambia
ZWE	Zimbabwe

Language resource

These codes are a subset of ISO 639-3 languages codes, [http://www-01.sil.org/iso639-3/codes.asp].

First codes in bold below is Synthesio usage of the norm’s reserved codes for local purposes. Following codes are sorted alphabetically by language name.

Code	Language
qaa	Undefined
qtz	Not Available
afr	Afrikaans
sqi	Albanian
ara	Arabic
hye	Armenian
asm	Assamese
aze	Azerbaijani
eus	Basque
bel	Belarusian
ben	Bengali
bos	Bosnian
bul	Bulgarian
mya	Burmese
cat	Catalan
khm	Central Khmer
zho	Chinese
zho-Hans	Chinese (simplified characters)
zho-Hant	Chinese (traditional characters)
hrv	Croatian
ces	Czech
dan	Danish
nld	Dutch
eng	English
est	Estonian
fin	Finnish
fra	French
gla	Gaelic
glg	Galician
kat	Georgian
deu	German
guj	Gujarati
heb	Hebrew
hin	Hindi
hun	Hungarian
isl	Icelandic
ind	Indonesian
ita	Italian
jpn	Japanese
jav	Javanese
kaz	Kazakh
kin	Kinyarwanda
kir	Kirghiz
kor	Korean
kur	Kurdish
lao	Lao
lav	Latvian
lit	Lithuanian
mkd	Macedonian
mlg	Malagasy
msa	Malay (macrolanguage)
mal	Malayalam
mlt	Maltese
mar	Marathi
ell	Modern Greek
mon	Mongolian
nep	Nepali (macrolanguage)
nor	Norwegian
ori	Oriya (macrolanguage)
pan	Panjabi
fas	Persian / Farsi
pol	Polish
por	Portuguese
pus	Pushto
ron	Romanian
roh	Romansh
rus	Russian
srp	Serbian
sin	Sinhala
slk	Slovak
slv	Slovenian
som	Somali
spa	Spanish
swa	Swahili (macrolanguage)
swe	Swedish
tgl	Tagalog / Filipino
tgk	Tajik
tam	Tamil
tel	Telugu
tha	Thai
tur	Turkish
ukr	Ukrainian
urd	Urdu
vie	Vietnamese
zul	Zulu

Note

Mentions that were previously identified simply as “Chinese” (code zho) are now identified as either “Chinese with simplified characters” (zho-Hans) or “Chinese with traditional characters” (zho-Hant). When using language filter, to ensure to get all Chinese mentions from your reports, you should filter on those three languages codes: zho, zho-Hans, zho-Hant.

Sentiment resource

Sentiment is a string value, can take any of the following values.

• negative

• positive

• neutral

• unassigned

• ambivalent: this value is deprecated, but it can still appear on older mentions.

Human review status resource

Human review status is a string that can take any of the following values.

• reviewed

• unreviewed

• deleted