Social Animal Content/News API v1.0
We, at Social Animal do the heavy lifting for you and provide you with a super-simple API for content search. Social Animal's powerful API provides a blazingly fast, simple API for popular articles with very flexible filters that let you get popular web content. Social Animal News API’s powerful query filters let you narrow down on the exact kind of content you need for your audience.
Things you need to know before you start
- The quota for a non-batched mode API call is 1.
- The quota for a batch mode API call is same as the batch size.
- For batch mode APIs, the maximum batch size is 10.
- Rate limit is 1 req/sec by default, but customizable according to the subscription plan upto 5 req/sec. See the support section in this document for more details.
Content Search
Social Animal's main content/News API is extremely simple. There is just one single RESTful API call, but you control what you get in the search results via different parameters you send it. In the following sections, we explain in detail the different filters and sorting options that will help you get the best out of the Social Animal Content/News API.
Search API
POST /api/v1/search
(non-batched mode)
Retrieve content based on given query parameters. This is the main content search API. Please refer to the query parameters below to influence returned results. Returns a maximum of 10,000 article results.
Request Object Parameters
Parameters control filtering and sorting. There is sufficient indication of whether parameters are mandatory, mutually exclusive, etc. Should you have any trouble using the Social Animal Content API, please see section below on support.
The Query
query
(Object, required) -- Query by the specified key. Possible keys aretitle
andkeywords
. Both these keys can be specified at the same time.title
(String) –- Match one or more words in the article title. Multiple title searches can be separated by comma. When a multi-word term is specified (e.g: "Internet of things" or Digital "marketing"), article titles that match the term exactly will be prioritized, however, article that have the words separated in the title will also be returned. If you need only content with article titles exactly matching the term as specified, wrap the term in double quotes.- e.g: If you search for the term "digital marketing" without the quotes, you might get articles titled "2018 Digital Marketing Trends" and "Top tips on marketing digital products" and similar. This is called loose matching.
- If you wrap the term "digital marketing" within double quotes when sending it to the API, you'll only get articles with titles matching the specified term exactly. e.g: You'll get "2018 Digital Marketing Trends", "10 mistakes to avoid in digital marketing". This is called tight matching.
- Please note that case is always ignored.
keywords
(String) –- Match one or more keywords in the article. Multiple values are separated by comma. Boolean OR is applied when multiple keywords are specified. Keywords are always tightly matched. Just as withtitle
, case is always ignored.
Loose Match Request Example
The following call fetches articles both titles like "2018 Digital Marketing Trends" and "Top tips on marketing digital products", etc.
{ "query": { "title": "digital marketing" } }
Tight Match Request Example
The following call fetches articles with titles matching the specified term exactly. e.g: You'll get "2018 Digital Marketing Trends", "10 mistakes to avoid in digital marketing", etc.
{ "query": { "title": "\"digital marketing\"" } }
Content Date Filters
You can filter content results by specifying a period (like the past 1 week or 1 month) or by explicitly providing a date range.
period
(String, optional) -- search in the given timeline, Possible values are 1_y
, 6_m
, 3_m
, 1_m
, 1_w
, 24_h
. The default is 1_y
. You should read these options with "in the past". For example, if you specify 1_w
, you are asking Social Animal to fetch content published in the past one week. If you specify this, from_date
and to_date
parameters are ignored.
* 1_y
- fetch articles published in the past 1 year
* 6_m
- fetch articles published in the past 6 months
* 3_m
- fetch articles published in the past 3 months
* 1_m
- fetch articles published in the past 1 months
* 1_w
- fetch articles published in the past 1 week
* 24_h
- fetch articles published in the past 24 hours
from_date
(Integer, optional) -- Retrieve results from this timestamp. It should be in UNIX timestamp format having UTC timezone. Ignored if period
is specified.
to_date
(Integer, optional) -- Retrieve results upto this timestamp. It should be in UNIX timestamp format having UTC timezone. Ignored if period
is specified.
There is another important point to remember about date filters. By default, they fetch articles published in the past based on actual dates specified in the article body itself. This is probably what you want most of the time. It is good to know however that there is another mode in which content can be fetched based on when it was shared on social media. Please see the section on "Advanced Content Results Filtering" and specifically search_mode
.
Fetching content published during a specific period
The following call fetches articles that were published in the past one week. You can also use from_date
and to_date
parameters to specify an exact period. The period
option lets you quickly fetch content for commonly used periods of time.
{ "query": { "title": "digital marketing" }, "period": "1_w" }
Advanced Content Results Filtering
The Social Animal Content API allows you complete control of the results through filters. You can specify multiple filters. If any filters are mutually exclusive, you’ll find it clearly indicated.
filter
(Object, optional) -- Advanced filters to further refine the query. You can set multiple keys in the filter
object depending on what filters you want to apply. Please see below for the different filter keys you can use.
By Keywords
keywords
(String) – Filter by one or more keywords. Exactly the same as query.keywords
. Same rules apply.
By Author
authors
(String) - Match one or more author names. Multiple values are separated by comma. By default, content authored by any author is returned.
By Word Count
content_word_count
(Integer) – Retrieve only those articles having a greater word count. By default, content irrespective of the word count is retrieved.
Published vs. Shared Dates
search_mode
(String) – Filter by the date on which the article was first seen by the system or was published originally. Possible values are seen
and published
. Social Animal monitors various social media for shared articles. Sometimes, older arcicles published in the past trend on social media at a later date. If you need to retrieve those, you can switch to seen
mode. If you need to search by the content’s published date, you can search using the published
date. If search_mode
is not specified, it defaults to published
.
By Top-Level Domain
tld
(String) - Filter by the top level domain of the article URL, eg: .co.uk
, co.au
. This filter helps you filter content by country.
By Domain Name
domain
(String) – Filter by the domain in which the article was published. If you want to retrieve content published by a particular domain, you should use this. See example below. It does not make sense to use this option with the domain_blacklist
option at the same time.
By URL
url
(String) – Retrieve the article published at this URL. You can use this get details of exactly one specific article.
By Article Type (Listicle, Interview, Product Review, etc.)
article_types
(String) – Filter by one or more article types. Multiple values are separated by comma. Possible values are listicle
, infographic
, how_to_guide
, case_study
, guest_post
, review
, video
, podcast
, webinar
, interview
, quote
, meme
, giveaway
and quiz
.
By Language
language
(String) – Filter by the language in which the article was written, e.g: en
, fr
, es
. Use two-letter language codes as specified in ISO-639-1.
By Content Sentiment
sentiment_filters
(Object) - Filter by the detected sentiment value. Positive value indicates positive sentiment. In future, we will be capping the acceptable range of values from -10
to +10
. The more positive the number, the more positive the sentiment. Similarly, the more negative the number, the more negative the sentiment.
gte
(Integer) - Filter by sentiment values greater than or equal to given value.
lte
(Integer) - Filter by sentiment values lower than or equal to given value.
By Image Present or Not
with_image
(Integer, optional) -- Retrieve only those articles which have an associated image. Possible values are true
or false
. Default value is false
which will return all articles with or without an image. Social Animal does not track total images count in the article or their URLs. Only the main, feature image is tracked.
Blacklisting Content from Domains
domain_blacklist
(String, optional) -- Domains to be blacklisted. Multiple values are separated by comma. Use this blacklist to exclude content from certain domains.
Filtering inappropriate content
strict_mode
(Boolean, optional) -- Social Animal filters pornographic content right at the sources with a sophisticated algorithm and does not store URLs of a pornographic nature in the system at all. However, although not porn, you might still want to restrict content which you think might be in the inappropriate or mature category though not of a pornographic nature. For this, please pass set the "strict_mode" parameter to "true". This applies additional filters which aggressively cut down on content of an adult nature. This is especially useful while dealing with automated systems where there is no human oversight of what content might be shared with your audience.
Request Example
The following call fetches articles with a positive sentiment writen by Matthew Panzarino for techcrunch.com that have at least one image. These articles are likely to be positive product reviews on the Apple Watch.
{ "query": { "title": "apple watch" }, "filter": { "authors": "Matthew Panzarino", "domain": "techcrunch.com" "sentiment_filters": {"gte": 5}, "with_image": true } }
Sorting Content Results
You can control the sorting order of the results that are returned with sort related parameters.
Sorting by Share Counts
sort_by
(String, optional) -- Field by which to sort the results. Default value is total_share_count
. Possible values are total_share_count
, twitter_share_count
, pinterest_share_count
and fb_share_count
. This option lets you surface content that is right for the kind of audience you are targeting. For example, technical content is shared more on Twitter than on Facebook.
Sort Order
sort_order
(String, optional) -- Order of sorting. Default value is DESC
. This sorts content in descending by share count on social media. So, you’ll see the most popular content first. Possible values are ASC
and DESC
.
Paginating Results
Any call to the Social Animal Content API can return up to a maximum of 10,000 results. The folling parameters let you manage how the results are returned in a paginated fashion so that they are in manageable chunks for use in your own app or script.
results_per_page
(Integer, optional) -- The number of results that will be returned per page. Default value is100
. Possible values are10
,25
,50
and100
.offset
(Integer, optional) -– The offset from which the next page of results is retrieved. To get the next page of results, you can simply passnext_page_offset
which is sent as part of the response in your next call. Please see example below.max_results
(Integer, optional) –- The maximum number of results that should be returned. Default value is10000
. Acceptable values ranges from1
to10000
inclusively. Although not very useful, this is provided for the sake of completeness.
Request Example
{ "query": { "title": "digital marketing" }, "sort_by": "twitter_share_count", "sort_order": "ASC" }
{ "query": { "keywords": "digital marketing, content marketing" }, "filter" { "content_word_count": 500, "search_mode": "seen", "article_types": "case_study,video" } }
Response Success Parameters
status
(String, required) -- Will have valuesuccess
always.results_in_page
(Integer, required) -- The number of results included in the API response.next_page_offset
(Integer, required) -- The value to passed foroffset
to retrieve the next page.total_results
(Integer, required) -- The total number of results in the result set.data
(Array, required) -- A list of article objects that match the request criteria.
Resposne Success Example
{ "status": "success", "results_in_page": 10, "next_page_offset": 10, "total_results": 2273, "data": [ { "tweet_id_str": null, "sentiment": 2, "linkedin_share_count": 0, "simple_keywords_ent": [ "Trump", "Jesus Christ", "Melania Trump", "Melania", "Great", "Art", "Trumps", "Christian" ], "created_at": "2018/03/13 02:00:10", "language": "en", "total_share_count": 1065, "title": "Melanie Trump Didn’t Know The Camera Was On, What I Saw Left Me In Tears", "gplus_share_count": 0, "keywords_status": true, "updated_at": "2018/03/13 02:00:10", "content_hash": "7030934e92d70c54e79fe2b73fd2aae8ee849e66466cda85b5647424e7985dffd0829920abfb21d4f2f85dcff8eb39da7156ffa5bdd986ba9cbdcd40b687b1df", "facebook_share_count": 1065, "is_processed": 0, "image": "http://politifeed.net/wp-content/uploads/2017/10/melcaptured.png", "article_influencers": null, "simple_keywords_nouns": [ "family", "proclaim", "believers", "scrutiny", "mainstream", "media", "point", "performance", "camera", "right", "Melania", "song", "couple", "moments", "emotion", "tears", "moment", "faith", "melanie", "trump" ], "deep_keywords": [ "camera", "tears", "melanie trump", "Melania Trump", "Trump", "Melania", "Christian" ], "reply_count": 0, "url": "http://politifeed.net/news/melanie-trump-didnt-know-the-camera-was-on-what-i-saw-left-me-in-tears", "domain": "politifeed.net", "twitter_share_count": 0, "pinterest_share_count": 0, "published_date": "2018/03/13 12:00:00", "content_word_count": 100, "authors": "Buford" }, ... ] }
Response Error Parameters
status
(String, required) -- Will have valueerror
always.message
(String, required) -- The response error message.
Response Error Codes
Code | Message |
---|---|
400 | Bad Request |
400 | Multiple Query Keys Specified |
400 | Invalid Parameter parameter_name |
401 | Unauthorized |
403 | Forbidden |
405 | Method Not Allowed |
429 | Rate Limit Exceeded |
429 | Quota Limit Exceeded |
500 | Internal Server Error |
Response Error Example
{ "status": "error", "message": "Bad Request" }
POST /api/v1/search (batch mode)
Retrieve articles based on given batch query parameters.
Request body is an array of objects, where each object in the array has the same format as the request object in the single mode of the API. Response body is also an array of objects, where each object in the array has the same format as the response object in the single mode of the API.
This means that for a given batch request, the response array contains the response object for the corresponding request object, in the exact same order.
Request Example
[ { "query": { "title": "digital marketing" }, "sort_by": "twitter_share_count", "sort_order": "ASC" }, { "query": { "keywords": "digital marketing, content marketing" }, "filter" { "content_word_count": 500, "search_mode": "seen", "article_types": "case_study,video" } } ... ]
Response Example
[ { "status": "error", "message": "Multiple Query Keys Specified" }, { "status": "success", "results_in_page": 10, "next_page_offset": 10, "total_results": 2273, "data": [ { "tweet_id_str": null, "sentiment": 2, "linkedin_share_count": 0, "simple_keywords_ent": [ "Trump", "Jesus Christ", "Melania Trump", "Melania", "Great", "Art", "Trumps", "Christian" ], "created_at": "2018/03/13 02:00:10", "language": "en", "total_share_count": 1065, "title": "Melanie Trump Didn’t Know The Camera Was On, What I Saw Left Me In Tears", "gplus_share_count": 0, "keywords_status": true, "updated_at": "2018/03/13 02:00:10", "content_hash": "7030934e92d70c54e79fe2b73fd2aae8ee849e66466cda85b5647424e7985dffd0829920abfb21d4f2f85dcff8eb39da7156ffa5bdd986ba9cbdcd40b687b1df", "facebook_share_count": 1065, "is_processed": 0, "image": "http://politifeed.net/wp-content/uploads/2017/10/melcaptured.png", "article_influencers": null, "simple_keywords_nouns": [ "family", "proclaim", "believers", "scrutiny", "mainstream", "media", "point", "performance", "camera", "right", "Melania", "song", "couple", "moments", "emotion", "tears", "moment", "faith", "melanie", "trump" ], "deep_keywords": [ "camera", "tears", "melanie trump", "Melania Trump", "Trump", "Melania", "Christian" ], "reply_count": 0, "url": "http://politifeed.net/news/melanie-trump-didnt-know-the-camera-was-on-what-i-saw-left-me-in-tears", "domain": "politifeed.net", "twitter_share_count": 0, "pinterest_share_count": 0, "published_date": "2018/03/13 12:00:00", "content_word_count": 100, "authors": "Buford" }, ... ] }, { "status": "error", "message": "Bad Request" }, ... ]
Support
Should you need any support regarding the Social Animal Content API subscription plans or developer support in general, please feel free to reach out to us at api@socialanimal.com.