Search

Social Searcher API V2.0

Social Searcher API V2.0 designed in a RESTful manner and allows to fetch data from our servers for the users with premium plans. The API provides an easy way to integrate data with your own software without necessity to use interface. Premium plans limits are described on the Pricing page, for the custom solutions and extended limits feel free to contact us or email directly: info[at]social-searcher.com

Your account API details

Log in to your account

GET search

This endpoint allows to fetch recent real-time search results from the following 10 social networks in a unified output format:

- Twitter
- Google+
- Youtube
- Instagram
- Tumblr
- Reddit
- Flickr
- Dailymotion
- Vimeo
- VKontakte

Social Searcher service automatically adds information about language, sentiment and post type (status, link, video or photo) to each post.

Resource URL

https://api.social-searcher.com/v2/search

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
q keyword OR “exact keyword” -minuskeyword Keywords for searching. Exact phrase for searching should be surrounded by double quotes. Minus keywords should have preceding ”-” symbol. Several keywords can be joined with OR (all capitals) operator.
limit (optional)20 (default), 100 MaxDefines the number of posts to be returned per page.
page (optional)0 (default)Allows to skip a number of results for pagination. This parameter should be increased when you want to go deeper in the data.
requestid (optional)Mandatory in case of pagination.
network (optional)all (default), twitter, googleplus, youtube, instagram, tumblr, reddit, flickr, dailymotion, vimeo, vkontakteSocial network for which you want to get data. “all” - results from all networks (billed as 1 request/network). Several networks for searching should be comma separated, eg. “twitter,googleplus”.
lang (optional)en, fr, it … See Appendix ALanguage restriction.
type (optional)video, photo, status, linkContent type restriction. Several types for searching should be comma separated, eg. “video, photo”.
fields (optional)See Appendix BList of fields that should be added to the output JSON. All fields are used for the output by default.

Search examples

General search.

https://api.social-searcher.com/v2/search?q=Obama&key={user_key}

Exact keywords search with language restriction.

https://api.social-searcher.com/v2/search?q="Angela Merkel"&limit=50&lang=de&key={user_key}

Exact keywords search with content type restriction and predefined networks.

https://api.social-searcher.com/v2/search?q="Monthly fails"&type=video&network=youtube,dailymotion&limit=100&key={user_key}

Pagination examples

General pagination.

https://api.social-searcher.com/v2/search?requestid={requestid}&page=1&key={user_key}

Pagination for predefined network.

https://api.social-searcher.com/v2/search?requestid={requestid}&page=1&limit=100&network=youtube&key={user_key}

Pagination with content type restriction.

https://api.social-searcher.com/v2/search?requestid={requestid}&page=0&limit=50&type=photo&key={user_key}

GET searches

Returns a list of your saved searches.

Resource URL

https://api.social-searcher.com/v2/searches

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.

POST searches

Allows to create a new saved search.

Resource URL

https://api.social-searcher.com/v2/searches

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
nameSearchNoname1Name of the search.
q keyword OR “exact keyword” -minuskeyword Keywords for searching. Exact phrase for searching should be surrounded by double quotes. Minus keywords should have preceding ”-” symbol. Several keywords can be joined with OR (all capitals) operator.
network (optional)all (default), web, facebook, twitter, googleplus, youtube, instagram, tumblr, reddit, flickr, dailymotion, vimeo, vkontakteSocial network for which you want to get data. “all” - results from all networks (billed as 1 request/network). Web results are available only in case of enabled monitoring. Facebook results require facebook_pages parameter. Several networks for searching should be comma separated, eg. “twitter,googleplus”.
lang (optional)en, fr, it … See Appendix ALanguage restriction.
type (optional)video, photo, status, linkContent type restriction. Several types for searching should be comma separated, eg. “video, photo”.
alert_started (optional)N (default)Defines if email alerts are started. The number of email alerts for the Free and Premium plans can be found on the Pricing page.
alert_period (optional)everyday (default), every3days, everyweekEmail alerts period.
alert_email (optional)smith@gmail.comEmail alerts email to send notifications (mandatory when alerts are started).
monitoring_started (optional)N (default)Defines if monitoring is started. The number of Monitorings and posts limits for the Premium plans can be found on the Pricing page.
facebook_pages (optional)facebook.com/socialsearcher, facebook.com/marketingComma separated list of facebook pages names.

Saving the search examples

Saving general search.

https://api.social-searcher.com/v2/searches?q=Obama&name=Obama search&key={user_key}

Saving exact keywords search with language restriction.

https://api.social-searcher.com/v2/searches?q="Angela Merkel"&name=Merkel search&lang=de&key={user_key}

PUT searches/{searchid}

Allows to update saved search parameters.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}

Parameters

Similar to POST searches. Mandatory parameters can't be set to "empty".

Updating the search examples

Enabling email alerts.

https://api.social-searcher.com/v2/searches/{searchid}?alert_started=Y&alert_period=every3days&alert_email=smith@gmail.com&key={user_key}

Changing preffered language.

https://api.social-searcher.com/v2/searches/{searchid}?lang=fr&key={user_key}

DELETE searches/{searchid}

Allows to delete saved search.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.

GET searches/{searchid}

Returns information about saved search.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.

GET posts

Returns a list of collected posts for the saved search with enabled monitoring.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/posts

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
period2015-04-03,2015-06-20
recent, yesterday, last3days, last7days, last30days, lastmonth, last3months, last6months
Time period. Use predefined periods or a custom one. For the fixed dates the format as follows:
{dateFrom},{dateTo}
limit (optional) 100 (default) Defines the number of posts to be returned.
page (optional)0 (default)Allows to skip a number of results for pagination. This parameter should be increased when you want to go deeper in the data.
network (optional)all (default), web, facebook, twitter, googleplus, youtube, instagram, tumblr, reddit, flickr, dailymotion, vimeo, vkontakteSocial network for which you want to get data. “all” - results from all networks. Several networks for searching should be comma separated, eg. “twitter,googleplus”.
sentiment (optional)positive, negative, neutralSentiment of the post. Several values should be comma separated, eg. “positive,neutral”.
type (optional)video, photo, status, linkContent type. Several types should be comma separated, eg. “video,photo”.
sort (optional)date (default), popularitySorting of the returned results.
favourites (optional)Y, NIn case of "Y" returns only posts marked as favourite by the user.

Fetching posts history examples

Getting recent posts.

https://api.social-searcher.com/v2/searches/{searchid}/posts?period=recent&key={user_key}

Pagination for the last month Twitter mentions.

https://api.social-searcher.com/v2/searches/{searchid}/posts?period=lastmonth&network=twitter&page=3&key={user_key}

PUT posts/{postid}

Allows to change post sentiment information or mark post as favourite for the user.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/posts/{postid}

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
sentiment (optional)positive, negative, neutralSentiment of the post.
favourite (optional) Y, N (default) In case of "Y" marks post as favourite for the user

Changing post examples

Changing sentiment information.

https://api.social-searcher.com/v2/searches/{searchid}/posts/{postid}?sentiment=positive&key={user_key}

Mark post as favourite for the user.

https://api.social-searcher.com/v2/searches/{searchid}/posts/{postid}?favourite=Y&key={user_key}

DELETE posts/{postid}

Allows to delete post.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/posts/{postid}

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.

GET searches/{searchid}/search

Allows to search within collected posts for the saved search with enabled monitoring. All text fields of the posts are searchable: user, text, link, description.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/search

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
qkeywordsKeywords for searching.
limit (optional) 100 (default) Defines the number of posts to be returned.
page (optional)0 (default)Allows to skip a number of results for pagination. This parameter should be increased when you want to go deeper in the data.
network (optional)all (default), web, facebook, twitter, googleplus, youtube, instagram, tumblr, reddit, flickr, dailymotion, vimeo, vkontakteSocial network for which you want to get data. “all” - results from all networks. Several networks for searching should be comma separated, eg. “twitter,googleplus”.
sentiment (optional)positive, negative, neutralSentiment of the post. Several values should be comma separated, eg. “positive,neutral”.
type (optional)video, photo, status, linkContent type. Several types should be comma separated, eg. “video,photo”.
sort (optional)date (default), popularitySorting of the returned results.

GET searches/{searchid}/analytics

Allows to get analytics information about collected social media mentions for the saved search with enabled monitoring.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/analytics

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
periodyesterday, last3days, last7days, last30days, lastmonth, last3months, last6monthsTime period.

GET searches/{searchid}/csv

Allows to export information about collected social media mentions for the saved search with enabled monitoring in CSV format.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/csv

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
periodyesterday, last3days, last7days, last30days, lastmonth, last3months, last6monthsTime period.

GET searches/{searchid}/rss

Allows to get feed with the recently collected social media mentions for the saved search with enabled monitoring. No authorization required, can be used for embedding results on the site.

Resource URL

https://api.social-searcher.com/v2/searches/{searchid}/rss

Parameters

No parameters.

GET accounts

Returns the list of accounts with information about resources usage, limits and permissions.

Resource URL

https://api.social-searcher.com/v2/accounts

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.

GET accounts/{accountid}

Returns account information about resources usage, limits and permissions.

Resource URL

https://api.social-searcher.com/v2/accounts/{accountid}

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.

Error handling

Error cases are handled with standard HTTP status codes. API response contains "meta" section with additional information. Example:

"meta":{"http_code": "200", "query_type":"searches_list"}

- 200 OK
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 405 Method Not Allowed
- 503 Service Unavailable

Terms of use

Social Searcher provides caching service of the social networks APIs for personal use only. The data obtained from the service can't be published in form of directory, search engine or other ways that violate appropriate social network API policies. It's also prohibited to use data provided by the service for commercial and other third-party services in the form in which it was fetched directly from the service.

Appendix A

Languagelang
Afrikaansaf
Arabicar
Bulgarianbg
Bengalibn
Englishen
Germande
Frenchfr
Italianit
Portuguese(Brazil)pt-BR
Portuguese(Portugal)pt-PT
Czechcs
Croatianhr
Danishda
Dutchnl
Estonianet
Finnishfi
Greekel
Norwegianno
Norwegian (Nynorsk)nn
Hindihi
Hungarianhu
Indonesianid
Japaneseja
Latvianlv
Lithuanianlt
Persianfa
Polishpl
Romanianro
Russianru
Spanishes
Slovaksk
Sloveniansl
Swahilisw
Swedishsv
Tamilta
Telugute
Thaith
Turkishtr
Koreanko
Ukrainianuk
Urduur
Vietnamesevi

Appendix B

NameScope
networkfield
postedfield
textfield
typefield
sentimentfield
langfield
imagefield
urlfield
usersection
popularitysection
urlssection
tagssection
user_mentionssection