Skip to content

Social Animal Content 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.

Common Request Headers

  • X-User-Id (String, required) -- Email ID used for the registered account.
  • X-Auth-Key (String, required) -- API key generated from the developer console.

Common Response Headers

  • X-Quota-Used (Integer, required) -- Number of API calls made out of the available quota.
  • X-Quota-Remaining (Integer, required) -- Number of API calls remaining out of the available quota.

Content Search

Social Animal's main content search 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 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 are title and keywords. 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 with title, 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 is 100. Possible values are 10, 25, 50 and 100.
  • offset (Integer, optional) -– The offset from which the next page of results is retrieved. To get the next page of results, you can simply pass next_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 is 10000. Acceptable values ranges from 1 to 10000 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 value success always.
  • results_in_page (Integer, required) -- The number of results included in the API response.
  • next_page_offset (Integer, required) -- The value to passed for offset 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 value error 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.