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

Mentions

Mentions API is the basis for the Social Buzz functionality of the Social Searcher.

GET search

This endpoint allows to fetch recent real-time search results from the top social media sources and web in a unified output format.

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), web… Contact us for the list of supported networksSocial 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. “web,...".
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

Best practice is to search for only one keyword in one network per request for the optimised performance and accurate data, no pagination is needed.

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

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=web&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=web&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 posts/{postid}/comments

This endpoint allows to fetch comments for the specific post, which was found via GET search in a unified output format.

Resource URL

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

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

GET posts/{postid}/likes

This endpoint allows to fetch likes for the specific post, which was found via GET search in a unified output format.

Resource URL

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

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

GET posts/{postid}/reposts

This endpoint allows to fetch reposts for the specific post, which was found via GET search in a unified output format.

Resource URL

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

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

Users

Users API is the basis for the Search Users functionality of the Social Searcher.

GET users

This endpoint allows to fetch search results of the social profiles by user name or surname from the top social media sources in a unified output format.

Resource URL

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

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
qJohn SmithName of the user.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

GET users/{userid}/posts

This endpoint allows to fetch recent posts of the specific user, which was found via GET users in a unified output format.

Resource URL

https://api.social-searcher.com/v2/users/{userid}/posts

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

GET users/{userid}/comments

This endpoint allows to fetch recent comments of the specific user, which was found via GET users in a unified output format.

Resource URL

https://api.social-searcher.com/v2/users/{userid}/comments

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

Trends

Trends API is the basis for the Social Trends functionality of the Social Searcher.

GET trends

This endpoint allows to fetch trending posts from the top social media sources in a unified output format.

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/trends

Parameters

NameExample valueDescription
keyYour unique user key, available in the account API details.
qkeywordOnly one keyword is supported for searching trending social media posts.
networkContact us for the list of supported networksSocial network for which you want to get data. Only one network is possible per request.

Monitoring

Monitoring is a premium feature, which enables system to collect and save your keywords mentions into the history automatically.
Your data is stored as long as your subscription is active.
Get direct access to your social mentions history via API: pagination, sort by date or popularity, filter by social network, sentiment or content type, search within history.
CSV format export for periods and RSS feed.
Advanced Analytics for Periods: posts distribution by week day and by hour, sentiment, posts types, links, users, keywords and hashtags.

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... Contact us for the list of supported networksSocial 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. Several networks for searching should be comma separated, eg. “web,...”.
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 emails to send notifications (mandatory when alerts are started). Several emails should be comma separated, eg. “smith@gmail.com,user@outlook.com”.
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.

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... Contact us for the list of supported networksSocial network for which you want to get data. “all” - results from all networks. Several networks for searching should be comma separated, eg. “web,...”.
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 Web mentions.

https://api.social-searcher.com/v2/searches/{searchid}/posts?period=lastmonth&network=web&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... Contact us for the list of supported networksSocial network for which you want to get data. “all” - results from all networks. Several networks for searching should be comma separated, eg. “web,...”.
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.

Account

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