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
| Name | Example value | Description |
| key | | Your 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 Max | Defines 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 | web… Contact us for the list of supported networks | Social network for which you want to get data. |
| lang (optional) | en, fr, it … See Appendix A | Language restriction. |
| type (optional) | video, photo, status, link | Content type restriction. Several types for searching should be comma separated, eg. “video, photo”. |
| fields (optional) | See Appendix B | List 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}
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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| network | Contact us for the list of supported networks | Social 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| network | Contact us for the list of supported networks | Social 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| network | Contact us for the list of supported networks | Social 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| q | John Smith | Name of the user. |
| network | Contact us for the list of supported networks | Social 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| network | Contact us for the list of supported networks | Social network for which you want to get data. Only one network is possible per request. |
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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| network | Contact us for the list of supported networks | Social 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| q | keyword | Only one keyword is supported for searching trending social media posts. |
| network | Contact us for the list of supported networks | Social 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
POST searches
Allows to create a new saved search.
Resource URL
https://api.social-searcher.com/v2/searches
Parameters
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| name | SearchNoname1 | Name 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) | web... Contact us for the list of supported networks | Social network for which you want to get data. Several networks for searching should be comma separated, eg. “web,...”. |
| lang (optional) | en, fr, it … See Appendix A | Language restriction. |
| type (optional) | video, photo, status, link | Content 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, everyweek | Email alerts period. |
| alert_email (optional) | smith@gmail.com | Email 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
GET searches/{searchid}
Returns information about saved search.
Resource URL
https://api.social-searcher.com/v2/searches/{searchid}
Parameters
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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| period | 2015-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) | web... Contact us for the list of supported networks | Social network for which you want to get data. Several networks for searching should be comma separated, eg. “web,...”. |
| sentiment (optional) | positive, negative, neutral | Sentiment of the post. Several values should be comma separated, eg. “positive,neutral”. |
| type (optional) | video, photo, status, link | Content type. Several types should be comma separated, eg. “video,photo”. |
| sort (optional) | date (default), popularity | Sorting of the returned results. |
| favourites (optional) | Y, N | In 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| sentiment (optional) | positive, negative, neutral | Sentiment 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
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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| q | keywords | Keywords 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) | web... Contact us for the list of supported networks | Social network for which you want to get data. Several networks for searching should be comma separated, eg. “web,...”. |
| sentiment (optional) | positive, negative, neutral | Sentiment of the post. Several values should be comma separated, eg. “positive,neutral”. |
| type (optional) | video, photo, status, link | Content type. Several types should be comma separated, eg. “video,photo”. |
| sort (optional) | date (default), popularity | Sorting 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| period | yesterday, last3days, last7days, last30days, lastmonth, last3months, last6months | Time 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
| Name | Example value | Description |
| key | | Your unique user key, available in the account API details. |
| period | yesterday, last3days, last7days, last30days, lastmonth, last3months, last6months | Time period. |
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
GET accounts/{accountid}
Returns account information about resources usage, limits and permissions.
Resource URL
https://api.social-searcher.com/v2/accounts/{accountid}
Parameters
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
| Language | lang |
| Afrikaans | af |
| Arabic | ar |
| Bulgarian | bg |
| Bengali | bn |
| English | en |
| German | de |
| French | fr |
| Italian | it |
| Portuguese(Brazil) | pt-BR |
| Portuguese(Portugal) | pt-PT |
| Czech | cs |
| Croatian | hr |
| Danish | da |
| Dutch | nl |
| Estonian | et |
| Finnish | fi |
| Greek | el |
| Norwegian | no |
| Norwegian (Nynorsk) | nn |
| Hindi | hi |
| Hungarian | hu |
| Indonesian | id |
| Japanese | ja |
| Latvian | lv |
| Lithuanian | lt |
| Persian | fa |
| Polish | pl |
| Romanian | ro |
| Russian | ru |
| Spanish | es |
| Slovak | sk |
| Slovenian | sl |
| Swahili | sw |
| Swedish | sv |
| Tamil | ta |
| Telugu | te |
| Thai | th |
| Turkish | tr |
| Korean | ko |
| Ukrainian | uk |
| Urdu | ur |
| Vietnamese | vi |
Appendix B
| Name | Scope |
| network | field |
| posted | field |
| text | field |
| type | field |
| sentiment | field |
| lang | field |
| image | field |
| url | field |
| user | section |
| popularity | section |
| urls | section |
| tags | section |
| user_mentions | section |
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
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
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
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
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
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
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
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
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
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
POST searches
Allows to create a new saved search.
Resource URL
https://api.social-searcher.com/v2/searches
Parameters
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
GET searches/{searchid}
Returns information about saved search.
Resource URL
https://api.social-searcher.com/v2/searches/{searchid}
Parameters
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
recent, yesterday, last3days, last7days, last30days, lastmonth, last3months, last6months
{dateFrom},{dateTo}
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
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
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
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
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
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
GET accounts/{accountid}
Returns account information about resources usage, limits and permissions.
Resource URL
https://api.social-searcher.com/v2/accounts/{accountid}
Parameters
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
Appendix B