TrendFeed API v2.0

Purpose

The TrendFeed API allows developers and partners to interact with TrendFeed programmatically.

URL

The API is called using a GET request to http://api.trendspottr.com/v2.0/trendfeed

Authentication

The API requires that every request authenticate itself via the inclusion of a valid API key, passed via a required key parameter, and any request that does not include one will fail with an http 401 status code. For brevity, this required parameter is not repeatedly documented for every API call below.

You can get your personal API key from the TrendSpottr Edit Account page. If you don't have a TrendSpottr account, you can get one by filling out the form on the TrendSpottr Registration Page and creating a TrendSpottr account.

Note that each account is only permitted one API key. If you generate a new key (via the button on the Edit Account page), it will replace your existing key any and any programs or scripts that use the previous API Key will fail until they are updated with the new value.

If you have any questions regarding the API or how to get access, please contact api@trendspottr.com for assistance.

Usage Limits

This API is available only under a contract with TrendSpottr. For details and pricing please contact us at api@trendspottr.com

Once authorized, you can track your usage via the TrendSpottr API dashboard.

API Terms of Use

By using the TrendSpottr API, you and, if applicable, the company you represent (collectively, "you"), accept and agree to be bound by the TrendSpottr API Terms of Use. It is important that you read these Terms as they form a legal agreement between you and ShawKing Data, Inc., operating as TrendSpottr.

Sample Code

A sample php script, trendfeedAPI-demo, is available that demonstrates how to call the TrendSpottr TrendFeed API via curl in PHP. Once downloaded, edit it to insert your personal API key, available from the Edit Account page, then run it with the PHP interpreter perform a search and parse the result.

Methods

This API supports the following methods:

Which can all be invoked by passing the method name, as the value of the action parameter, to the API endpoint via an HTTP GET request. For example action=searchArticles.

All string values provided to the endpoint must be encoded in UTF-8 format. All strings returned will be encoded similarly. All integers returned by the methods should be treated as 64-bit integers.

All API calls will include a string parameter called “key”. There is a unique apiKey value associated with each TrendSpottr user. Passing the apiKey allows the API key to perform the action on behalf of a specific user.

All parameters to the functions are to be sent as normal url parameters. All data returned will be json encoded and will decode into a single object. All return values will included a string property called “status” which can have one of two values:

searchArticles

The searchArticles returns an array of TrendFeed articles across all TrendFeed feeds that match the provided query string. The query string is matched against words in each article's title and description.

Parameter
Description
action
searchArticles: The action required to invoke this method.
query_string required
(Default: none) This parameter should contain a list of words, separated by spaces, that will be used to find matching articles. The string is case independent and it is not necessary that all words be present in the feed for it to be matched. The more words that do exist the higher the match will be rated. The boolean operators or and and are not supported and will simply be ignored if included. Brackets are also not supported, but quoted strings are. For example, the query string electric vehicles and "electric vehicles" will return different results.
count optional
(Default: 20) This parameter specifies the maximum number of articles you want the search to return. The value provided must be a positive integer and the maximum allowed value is 100. If more than 100 results are desired, multiple API calls will need to be made. See the documentation on the offset parameter below for details on how to implement paging of the results.
offset optional
(Default: 0) This parameter can be used to implement paging of search results when more than 100 articles are desired. If set to a non-zero value, it indicates the number of articles in the search results that should be skipped. So, if the first API call includes count=100, to get the next 100 values, include both the count=100 and offset=100 parameters in the 2nd call. The third call would set offset=200.

Note that each subsequent call to this API performs the search over again and then offset simply skips the specified number of matched articles. So, if by chance new articles that match the search query are added to the TrendFeed library between the first call and subsequent ones, it is possible that calls that use offset may return a few duplicate articles — ones that were returned by the first call.

If duplicates are unacceptable in your application, you will need to implement your own de-duplication logic. The searchArticles API won't do it for you.

A successful API call will result in an http status code of 200 and a json object containing 1 property in addition to the common status property.

Property Name
Description
matching_articles
An array of objects. Each object represents a TrendFeed article and the articles are sorted in order of most to least recent. Each article objects contains the following properties:
  • id (integer): A ID that can be used to uniquely identify this specific article and which can be used for de-duplication if desired.
  • title (string): The title of the article.
  • description (string): A snippet of text scraped from the article.
  • link (string): The url of the article.
  • pub_date (string): The date the article was added to TrendFeed in ISO 8601 date format.
  • author_name (string): The author of the article, or null if the author could not be reliably determined.
  • provider_name (string): The website that published the article.
  • provider_url (string): The base url of the provider website.
  • thumbnail_url (string): The url of the article thumbnail.
  • thumbnail_width (integer): The width of the thumbnail image.
  • thumbnail_height (integer): The height of the thumbnail image.
  • trending_level (string): One of "Elevated", "High", or "Extreme" representing the trending strength of the article, at the time it was added, relative to all other articles TrendFeed was tracking for this feed.
  • feed_id (integer): The unique feed_id for the feed in which the article was published.
  • feed_group (string): The name of the TrendFeed Group in which the article was published.
  • feed_name (string): The name of the TrendFeed Feed in which the article was published.

A sample response using the query_string Electric Vehicles and a count of 1 is shown below:

{
    "status": "OK",
    "matching_articles": [
        {
            "id": 291099,
            "title": "New MIT study claims 'range anxiety' fears about electric vehicles are overblown",
            "description": "New MIT study claims 'range anxiety' fears about electric vehicles are overblown A new study from MIT claims that range anxiety fears are overblown -- but while that may be true, it doesn't mean there aren't significant issues between EVs and widespread adoption. Read full article here",
            "author_name": "Bruce Whealton",
            "provider_name": "Future Wave Tech Info Blog",
            "provider_url": "futurewavewebdevelopment.com",
            "link": "http:\/\/futurewavewebdevelopment.com\/wp\/new-mit-study-claims-range-anxiety-fears-about-electric-vehicles-are-overblown\/",
            "thumbnail_url": "http:\/\/futurewavewebdevelopment.com\/wp\/wp-content\/uploads\/2016\/08\/Range-Anxiety-300x166.jpg",
            "thumbnail_width": 300,
            "thumbnail_height": 166,
            "pub_date": "2016-08-18T12:02:23+00:00",
            "trending_level": "High",
            "feed_id": 1706,
            "feed_group": "Automotive",
            "feed_name": "Electric Vehicles"
        }
    ]
}

getArticles

The getArticles returns an array of TrendFeed articles from a specific feed.

Parameter
Description
action
getArticles: The action required to invoke this method.
feed_id required
(Default: none) This parameter must contain the integer feed_id of a TrendFeed Feed. The feed_id can be obtained via calls to the getFeedID, getFeedList or searchFeedList API methods.
count optional
(Default: 20) This parameter specifies the maximum number of articles you want the call to return. The value provided must be a positive integer and the maximum allowed value is 100. If more than 100 results are desired, multiple API calls will need to be made. See the documentation on the paging_cursor parameter below for details on how to implement paging of the results.
paging_cursor optional
(Default: 0) This parameter can be used to implement paging of the results when more than 100 articles are desired. It should be omitted on the first call to get the most recent articles in a feed. All results from the getArticles API call will contain a paging_cursor property (see below), which can be passed on the next call to restrict the result to older articles. When used this way, no duplicate articles will ever be returned.

A successful API call will result in an http status code of 200 and a json object containing 2 properties in addition to the common status property.

Property Name
Description
articles
An array of objects, sorted in order of most recent to oldest. Each object represents a TrendFeed article and contains the following properties:
  • id (integer): A ID that can be used to uniquely identify this specific article and which can be used for de-duplication if desired.
  • title (string): The title of the article.
  • description (string): A snippet of text scraped from the article.
  • link (string): The url of the article.
  • pub_date (string): The date the article was added to TrendFeed in ISO 8601 date format.
  • author_name (string): The author of the article, or null if the author could not be reliably determined.
  • provider_name (string): The website that published the article.
  • provider_url (string): The base url of the provider website.
  • thumbnail_url (string): The url of the article thumbnail.
  • thumbnail_width (integer): The width of the thumbnail image.
  • thumbnail_height (integer): The height of the thumbnail image.
  • trending_level (string): One of "Elevated", "High", or "Extreme" representing the trending strength of the article, at the time it was added, relative to all other articles TrendFeed was tracking for this feed.
paging_cursor
An integer which will be set to the id of the last article returned by the call. If this value is passed to a subsequent getArticles call, only articles older than the last one received will be returned.

A sample response using feed_id set to the value of the Automotive/Electric Vehicles feed and a count of 1 is shown below:

{
    "status": "OK",
    "articles": [
        {
            "id": 291099,
            "title": "New MIT study claims 'range anxiety' fears about electric vehicles are overblown",
            "description": "New MIT study claims 'range anxiety' fears about electric vehicles are overblown A new study from MIT claims that range anxiety fears are overblown -- but while that may be true, it doesn't mean there aren't significant issues between EVs and widespread adoption. Read full article here",
            "author_name": "Bruce Whealton",
            "provider_name": "Future Wave Tech Info Blog",
            "provider_url": "futurewavewebdevelopment.com",
            "link": "http:\/\/futurewavewebdevelopment.com\/wp\/new-mit-study-claims-range-anxiety-fears-about-electric-vehicles-are-overblown\/",
            "thumbnail_url": "http:\/\/futurewavewebdevelopment.com\/wp\/wp-content\/uploads\/2016\/08\/Range-Anxiety-300x166.jpg",
            "thumbnail_width": 300,
            "thumbnail_height": 166,
            "pub_date": "2016-08-18T12:02:23+00:00",
            "trending_level": "High"
        }
    ],
    "paging_cursor": 291099
}

getFeedList

The getFeedList returns all the feed groups and feed names currently configured in TrendFeed.

Parameter
Description
action
getFeedList: The action required to invoke this method.

A successful API call will result in an http status code of 200 and a json object containing 2 properties in addition to the common status property.

Property Name
Description
feed_groups
An array of strings, sorted in alphabetical order, listing all the currently active TrendFeed Feed Groups.
feed_list
An array of objects, sorted alphabetically by feed_group and then feed_name. Each object will contain three properties:
  • feed_id (integer): The unique feed_id for this feed.
  • feed_group (string): The feed group that contains this feed.
  • feed_name (string): The name of the feed

searchFeedList

The searchFeedList returns a list of feeds that match the provided query string. The query string is matched against words in the feed group, the feed name, and the underlying (hidden) TrendSpottr query.

Parameter
Description
action
searchFeedList: The action required to invoke this method.
query_string required
(Default: none) This parameter should contain a list of words separated by spaces that will be used to find matching feeds. The string is case independent and it is not necessary that all words be present in the feed for it to be matched. The more words that do exist the higher the match will be rated. The boolean operators or and and are not supported and will simply be ignored if included. Brackets are also not supported, but quoted strings are. For example, the query string internet of things and "internet of things" will return different results.

A successful API call will result in an http status code of 200 and a json object containing 1 property in addition to the common status property.

Property Name
Description
matching_feeds
An array of objects, sorted best match first. Each object will contain three properties:
  • feed_id (integer): The unique feed_id for this feed.
  • feed_group (string): The feed group that contains this feed.
  • feed_name (string): The name of the feed

A sample response using the query_string internet of things is shown below:

{
    "status": "OK",
    "matching_feeds": [
        {
            "feed_id": 1670,
            "feed_group": "Tech & Telecom",
            "feed_name": "Internet of Things"
        },
        {
            "feed_id": 1576,
            "feed_group": "Healthcare",
            "feed_name": "Digital and Connected Health"
        },
        {
            "feed_id": 1671,
            "feed_group": "Tech & Telecom",
            "feed_name": "IoT Infrastructure"
        },
        {
            "feed_id": 1646,
            "feed_group": "Security",
            "feed_name": "InfoSec and Cybersecurity"
        }
    ]
}

getFeedID

The getFeedID returns the feedID for a feed identified by it's feed_group and feed_name.

Parameter
Description
action
getFeedID: The action required to invoke this method.
feed_group required
(Default: none) This string parameter contains the name of a TrendFeed Feed Group.
feed_name required
(Default: none) This string parameter contains the name of a TrendFeed Feed in the specified feed_group.

A successful API call will result in an http status code of 200 and a json object containing 1 property in addition to the common status property.

Property Name
Description
feed_id
(integer) The unique feed_id for the specified feed.

A sample response using the feed_group Automotive and feed_name Electric Vehicles is shown below:

{
    "status": "OK",
    "feed_id": 1706
}

Error Responses

In the case of an error, api calls will return a http status code greater than or equal to 400 and a json object that will contains 2 properties: status, that will always be set to the string ERROR, and error_msg, that describes the error. For example:

{
    "status": "ERROR",
    "error_msg": "Invalid count. Must be an integer between 1 and 100."
}