Alerts API v1.5

Purpose

The TrendSpottr Alerts API allows developers and third party partners to access the TrendSpottr service to customize, integrate and offer a white label version of TrendSpottr Alerts. You can configure the TrendSpottr alerts service and request trending alerts data for a given alert query (including real-time sentiment and analytics). Alerts data will be delivered to your servers via a POST webhook, in JSON format, which you can then format and deliver to your clients in any way you choose.

Please contact us at api@trendspottr.com to enable your account with access to the Alerts API and discuss a custom plan that best fits your business needs.

URL

The API is called using either GET or POST requests to http://api.api.trendspottr.com/v1.5/alerts

Note that for privacy reasons a non-encrypted (http) endpoint is NOT provided. If an attempt is made to call this API via http on port 80, the call will fail with an error.

Authentication

The API requires that every request authenticate itself via the inclusion of a valid API key and any request that does not include one will fail.

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.

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 key value.

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

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., also operating as TrendSpottr.

Sample Code

Two example PHP scripts are available to demonstrate both how to use the Alerts API (alertsAPI-demo) and how to receive and parse data you will receive when an Alert is posted to your website (alertsAPI-webHookReceiver). Once downloaded

Methods

All the methods below can be invoked by either an HTTP GET or POST unless specified otherwise. They will always return http code 200, regardless of whether or not the call itself failed. If any other http codes are received they should be handled and interpreted as usual for http errors.

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 Alerts API calls will include a parameter called “key” of type apiKey. 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:

Note that since the error_code and error_msg properties are common to all methods when an error occurs, for clarity and brevity, they won’t be listed in any of them below.

To use this API, we recommend that you create a new TrendSpottr user, likely using a email alias (or nickname) in your domain (say tsalerts@domain.com). The apiKey for that user can be obtained from the “edit account” page for that user and should be used for all API requests. You can then log-in to TrendSpottr using that email address to view active alerts and take other actions via the UI. Once the webhook is configured, alerts will be delivered via POST requests to the configured endpoint. Any TrendSpottr errors that require communication back to the “alert owner” will be sent to that email address.

setWebhook

Sets the webhook endpoint and secret associated with the user identified by the given API key for the given type of webhook.

URL Parameters
key
apiKey
secret
string: up to 64 bytes of data that will be passed back when posting to the url given below
url
string: the url to which alerts will be posted
Returned json Properties
status
{OK, ERROR}

getWebhook

Gets the webhook data associated with the user identified by the given API key and type. If no webhook has been configured, the returned status will be “ERROR” and the error_code will be “TSAPI_NO_WEBHOOK”.

URL Parameters
key
apiKey
Returned json Properties
status
{OK, ERROR}
secret
string: up to 64 bytes of data that will be passed back when posting to the url given below
url
string: the url to which alerts will be posted

deleteWebhook

Deletes the webhook data associated with the user identified by the given API key

URL Parameters
key
apiKey
Returned json Properties
status
{OK, ERROR}

createAlert

Creates a new alert for the given query string and returns a unique id for it. Note that this call will fail unless the account referenced by the apiKey has a webhook configured for it.

URL Parameters
key
apiKey
query_string
string containing the query to be added. Can contain up to 10 OR clauses.
level_filter
string: (optional) one of “All”, “HighAndExtreme”, or “ExtremeOnly” indicating the threshold after which TrendSpottr will post an alert. Setting the level to Allwill generate the most posts, ExtremeOnly the fewest. Default: “All”
userid
string: (optional) up to 64 bytes of data that will be passed back as part of the post packet when an alert is delivered. If present, this value is assumed to uniquely identify a specific customer in an implementation in which multiple end-users are being multiplexed through a single TrendSpottr account. So for example, if via the API you attempt to create 2 alerts with the same “userid” and “query_string” parameters, the second call will fail with a duplicate alert error. If this parameter is omitted, we assume that no multiplexing is taking place.
Returned json Properties
status
{OK, ERROR}
alert_id
unsigned integer: the id for the newly created alert. This id must be passed in all subsequent calls that manage the alert

deleteAlert

Deletes an alert specified by an alert_id.

URL Parameters
key
apiKey
alert_id
unsigned integer: the id for the alert
Returned json Properties
status
{OK, ERROR}

setAlertState

Pauses or enables an alert specified by an alert_id. If the alert is “paused”, no further alerts will be calculated, saved or delivered. The alert can be re-enabled by a subsequent call that sets its state to “active”. All newly created alerts start in the ‘active’ state.

URL Parameters
key
apiKey
alert_id
unsigned integer: the id for the alert
state
string: one of “paused” or “active”
Returned json Properties
status
{OK, ERROR}

setAlertLevel

Changes the “level”, or threshold, at which alerts will be generated for a given alert. This changes the value set by the “level” parameter of createAlert at a later time. Setting the level to All will generate the most posts, ExtremeOnly the fewest.

URL Parameters
key
apiKey
alert_id
unsigned integer: the id for the alert
level_filter
one of “All”, “HighAndExtreme”, or “ExtremeOnly”
Returned json Properties
status
{OK, ERROR}

getAlertInfo

Returns information about an existing alert specified by alert_id.

URL Parameters
key
apiKey
alert_id
unsigned integer: the id for the alert
Returned json Properties
status
{OK, ERROR}
alert_id
unsigned integer: the id for the alert
query_string
string: the query string associated with the alert
userid
string: the data that was provided in createAlert API call.
state
either “paused” or “active”
level_filter
one of “All”, “HighAndExtreme”, or “ExtremeOnly”
last_sent_time
unsigned integer: the last Unix time an alert was sent or posted. If zero, nothing has ever been sent/posted.

getRecentAlertsForQuery

Before creating a new alert, it can be useful to know whether TrendSpottr has identified and sent any alerts for the proposed query_string. This method returns a summary of previously sent alerts for the provided query. If there are no recent alerts for the given query, this method will return with status=”OK”, and the recent_alerts property will be a zero length array.

URL Parameters
key
apiKey
query_string
string: containing the query to be added. This should NOT be urlencoded. Can contain up to 10 OR clauses.
max_records
unsigned integer: number representing the maximum number of results to be returned. Default: 5. Maximum: 50.
Returned json Properties
status
{OK, ERROR}
recent_alerts
array: each element of which contains an object with the following fields:
sent_time
unsigned integer: Unix timestamp representing date alert was sent
headline
string: the headline, or title of the alert
level
string: one of “Elevated”, “High”, or “Extreme”
url
string: the url for the alert. This is not url encoded.

getRecentAlerts

Returns an array of objects describing recent alert events that have been delivered for the specified alert.

URL Parameters
key
apiKey
alert_id
unsigned integer: the id for the alert
max_records
unsigned integer: number representing the maximum number of results to be returned. Default: 10. Maximum: 50.
Returned json Properties
status
{OK, ERROR}
recent_alerts
array: each element of which contains an object with the following fields:
sent_time
unsigned integer: Unix timestamp representing date alert was sent
headline
string: the headline, or title of the alert
level
string: one of “Elevated”, “High”, or “Extreme”
url
string: the url for the alert. This is not url encoded.

getAlertAnalytics

Returns data about a delivered alert.

URL Parameters
key
apiKey
notification_id
unsigned integer: the identifier provided in an alert notification
include_sentiment
integer: this is a boolean value either “true” or “false”, defaulting to “false”. If true, the API will attempt to compute detailed sentiment data for the content url sent by the alert. If false, the properties url_sentiment and url_emotions will not be included in the returned result. Even if set to true, these fields may not be present in the returned data if it is not possible to compute the sentiment at the time this call is made.
Returned json Properties
status
{OK, ERROR}
sent_time
unsigned integer: Unix timestamp representing the date the alert was sent
url
string: The URL sent in the alert
volume
array: the total number of tweets containing the url that were detected by the given time. These values will be monotonically increasing. Each element of the array contains an object with the following fields:
timestamp
unsigned integer: Unix timestamp
count
unsigned integer: the total number of tweets received by “time”
url_sentiment
string: (optional) if this field exists, it will contain one of “Positive”, “Neutral”, “Negative”, the overall sentiment computed by analyzing the headline and description fields from the delivered alert. Note that it is possible that this value can differ from the one delivered via the webhook when the alert was generated if the cached values have timed out and the webpage has been modified since the alert was delivered. Such an occurrence will be rare, but it is possible.
url_emotions
associative array: (optional) containsthe sentiment values for each individual emotion computed by analyzing the headline and description fields from the delivered alert. The array will contain 8 elements the keys of which will be the strings:
  • "affection_friendliness"
  • "enjoyment_elation",
  • "amusement_excitement"
  • "contentment_gratitude"
  • "sadness_grief"
  • "anger_loathing"
  • "fear_uneasiness"
  • "humiliation_shame"
and the values will be non-negative floating point numbers in the range of 0-10.0 representing the strength of that emotion.

Webhook

When TrendSpottr detects activity for a url based on the query string provided that exceeds the threshold for the alert’s level, and a webhook has been set for the user associated with the alert, TrendSpottr will make an post call to the configured webhook url.

If the receiver of the post call receives it successfully, it must return http status code 200. If any other code is received, TrendSpottr will try 4 more times, at roughly 15 minute intervals, to redeliver the event. If all of those result in a non-200 status code as well, then (roughly an hour after the first attempt was made) the delivery will marked as having “failed” and no further retries will be performed.

The post will contain a json encoded string that decodes into an object with the following properties:

event_id
unsigned integer: unique id for this event
secret
the value provided in the setWebhook call when the webhook was registered.
type
string: “alert”
status
string: “pending” if the alert has not yet been delivered, “succeeded” it has been delivered, “failed” if the maximum number of retries has been exceeded and no more attempts will be made. Will always be “pending” when received by the webhook.
attempts
unsigned integer: number of “previous” attempts made to deliver this event. Will be 0 on the first attempt.
created
unix timestamp: time the event was created
post_time
unix timestamp: the time of the last post attempt
data
object:
type
string: “alert”
alert_id
unsigned integer: the id for the alert
query_string
string: the query string associated with the alert
userid
string: the data that was provided in createAlert API call.
notification_id
unsigned integer: an unique identifier for this delivered alert. It must be passed back to methods such as the “getAnalytics” method to identify the specific delivered alert for which data is needed.
headline
string: the headline, or title of the alert
description
string: the first partof the body text from the url – an snippet of the url contents. The length of this can vary, but will usually be just over 250 characters and almost always less than 512.
level
string: one of “Elevated”, “High”, or “Extreme”
url
string: the url of the alert. This is not url encoded.
sentiment
string: (optional) if this field exists, it will contain one of “Positive”, “Neutral”, “Negative”.
thumbnail_url
string: (optional). If this field exists then it is a url for the thumbnail image associated with the url. If, and only if, it exists, the next two fields will exist also.
thumbnail_width
unsigned integer: (optional) width of the thumbnail image.
thumbnail_height
unsigned integer: (optional) height of the thumbnail height.
related_hashtags
array: An ordered list of up to 5 hashtags. Related hashtags are those hashtags that we predict will have the highest level of usage and engagement for the alert query over the next several hours. This data provides additional context to the alert and is very useful for optimizing content marketing and social engagement.
Returned json Properties
Http codes returned by the webhook

A sample json string for an event containing an alert is:

{
    "event_id": 38,
    "secret": "topsecret!!",
    "type": "alert",
    "status": "pending",
    "attempts": 0,
    "created": 1366808682,
    "post_time": 1366808682,
    "data": {
        "type": "alert",
        "alert_id": 1013,
        "query_string": "Technology",
        "userid": "user7",
        "notification_id": 60479,
        "level": "Elevated",
        "url": "http:\/\/www.bbc.co.uk\/news\/technology-22278955",
        "headline": "Nokia phone gets Whatsapp button",
        "description": "Nokia has released a mobile phone with a dedicated WhatsApp physical button. The feature triggers the cross-platform messaging app which offers a free alternative to SMS texts. HTC and Nokia have previously released handsets with Facebook-devoted buttons, but this marks a first for WhatsApp.",
        "sentiment": "Positive",
        "thumbnail_url": "http:\/\/news.bbcimg.co.uk\/media\/images\/67210000\/jpg\/_67210392_nokia2.jpg",
        "thumbnail_width": 144,
        "thumbnail_height": 81,
        "related_hashtags": [
            "#technology",
            "#tech",
            "#edtech",
            "#news",
            "#geek"
        ]
    }
}