Search API v1.5

Purpose

The TrendSpottr Search API allows you to query the TrendSpottr service, request top trending information for a given search parameter or twitter list specification, and retrieve the results in JSON or JSONP format.

URL

The API is called using a GET request to http://api.trendspottr.com/v1.5/search

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.

Usage Limits

The free version of the TrendSpottr API is subject to a usage limit of 100 API calls per month. Premium versions of the API are available that feature tiered usage plans. Please contact us for information about our premium pricing plans.

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

Sample Code

A sample php script, searchAPI-demo, is available that demonstrates how to call the TrendSpottr API via curl. Once downloaded, edit it to insert your personal API key, available from the Edit Account page, then run it under the PHP interpreterto download data from TrendSpottr and parse it.

Parameters

Parameter
Description
key required
(Default: none) This parameter must contains your personal API key. If a valid key is not provided, the API request will fail. See the Authentication section above for details on how to get an API key.
q required
(Default: none) This parameter specifies the search terms to be used for the queries. The value passed must be urlencoded. In particular, if you pass a search term that contains a hashtag without encoding it, the text after the hashtag will be interpreted as a url fragment and the search won't behave as expected.

If the query matches a twitter list URL of the form https://twitter.com/username/lists/list_name the API will use the list as the source of tweets to analyze rather than using it as a twitter search term.
w optional
(Default: twitter) This parameter designates which source to search in. Allowed values are twitter and all.

This API used to support searching Facebook by specifying the source as facebook, but Facebook has deprecated their Post Search API and consequently TrendSpottr Facebook search has also been deprecated. If the w value is set to facebook it will return the error TSAPI_INVALID_SOURCE.
n optional
(Default: 20) This positive integer parameter sets the maximum number of results to return for each category (phrases, links, hashtags, and sources). Note that the number of results returned for each category can be less than n and each of the categories returned in a single request can contain different numbers of results. The maximum permitted value for n is 20.
g optional
(Default: unset) This parameter takes three comma separated arguments: latitude, longitude and radius. Latitude and Longitude must be specified in decimal format (degrees, minutes and seconds format is not permitted) and the radius parameter needs to have a unit specifier appended, either "mi" for miles or "km" for kilometers. (i.e. '37.779195,-122.426491,100km' specifies a 100 kilometer radius around the San Francisco Airport).

Note that this parameter only affects the results when the data source (w parameter) is twitter. For other data sources, no errors will be returned, but the value of this parameter will have no effect on the results .
lang optional
(Default: en) If provided, an attempt (on a best effort basis) is made to restrict all the data analyzed to tweets in the specified language. For example, lang=fr restricts the analysis to tweets in French. The value of this parameter must be a valid ISO 2-letter language code. If an illegal, or unknown, value is provided, the results are indeterminate. Note that this parameter only affects the results when the data source (w parameter) is twitter. For other data sources, no errors will be returned, but the value of this parameter will have no effect on the results .
resolve_urls optional
(Default: false) Allowed values are: true or false

If provided and set to true, all shortened urls found in the source data will be resolved all the way to the final url before any analysis is done on the data. (i.e. all redirects are followed) This can significantly improve the quality of the results, by eliminating all aliasing effects that can occur when multiple shortened urls refer to the same final url, but can add up to 90 seconds of delay before a response is provided.

Note that this parameter only affects the results when the data source (w parameter) is twitter. For other data sources, no errors will be returned, but the value of this parameter will have no effect on the results .
expand optional
(Default: false) Allowed values are: true or false

If provided, and set to true, all urls returned in links will be scraped and an expanded property will be included in each element of the links array that contains an oembed formatted data structure containing details about that url. See the example below. It is not guaranteed that all possible oembed fields will be included in each returned data structure, so care must be taken to ensure that proper handling of possibly missing fields such as thumbnail_url.

If missing, or set to false, all urls returned in links will be unexpanded, and possibly shortened. Note that if this parameter is set to true, TrendSpottr must scrap data from every url included in the links array to get the embedded data. This can dramatically increase the time necessary to complete the request.
callback optional
(Default: unset) If set, the results will be returned in JSONP format and the value of this parameter specifies the name of the JSONP callback that will be used.

Note that if any parameters other than those listed above are passed via the query, they will be silently ignored.

Returned Values

The API returns the stream_weight for the query and four arrays, each of which contains elements of the corresponding type along with their associated weight

Weight is a calculated metric that represents the viral potential of a given topic or search term. The weight is linear and higher values indicate stronger viral potential. For example, a term with a weight of 100 is predicted to generate 5 times more traffic than a term with a weight of 20. We normalize these weights into the range of 0-100, using the largest weight value as the target for "100". There will likely be slight variations between the trending score displayed in the TrendSpottr UI and what is returned by an API call since the weight varies over time and is updated as new data is analyzed.

Property Name
Description
stream_weight
Stream_weight is the sum of the weights for all URLs considered while processing a query. It is a raw weight that gives an indication of the viral potential and overall velocity for a given query/stream. This value can be used to compare the relative trending strength of different queries/streams.
links
An array of objects containing the top trending URLs, that were associated with the search term, sorted in order of decreasing weight. If the expand parameter was set to true, the result will also contain the oembed expansion of the URL.
hashtags
An array of objects containing the top trending hashtags, that were associated with the search term, sorted in order of decreasing weight.
sources
An array of objects containing the top trending sources (i.e. Twitter screen names) that were associated with the search term sorted in order of decreasing weight. These users are the influencers that are currently having the largest impact on the stream.
phrases
An array of objects containing the top trending three word phrases, that were associated with the search term, sorted in order of decreasing weight.

Response Format

The response returned will always be in JSON format (except when using a callback, in which case JSONP will be returned). The result will be in one of two forms. Successful results are returned in the following format:

{
    "results": {
        "links": [
            {
                "value": "http:\/\/the.short.url\/",
                "weight": 100,
                "expanded": {
                    "url": "http:\/\/site.domain.name\/the-fully-resolved-url.html",
                    "title": "Web page title",
                    "description": "Web page description",
                    "type": "link",
                    "thumbnail_url": "http:\/\/\/site.domain.name\/thumbnail.jpg",
                    "thumbnail_width": 800,
                    "thumbnail_height": 600,
                    "provider_url": "site.domain.name",
                    "provider_name": "Site name"
                }
            }
        ],
        "hashtags": [
            {
                "value": "#theHashtag",
                "weight": 100
            }
        ],
        "sources": [
            {
                "value": "@userName",
                "weight": 100
            }
        ],
        "phrases": [
            {
                "value": "the phrase",
                "weight": 100
            }
        ]
    }
}

In the case of an error, the response will be in the following format:

{
    "code": "TSAPI_MISSING_QUERY",
    "errstring": "Query missing the required search term (q parameter)"
}

Error Codes

The current list of error codes is:

Code
ErrString
TSAPI_MISSING_APIKEY
Must provide an API key (key parameter)
TSAPI_INVALID_APIKEY
Must provide a valid API key (key parameter))
TSAPI_USER_INACTIVE
API key does not belong to a confirmed and unblocked user (key parameter)
TSAPI_QUOTA_EXCEEDED
Monthly Quota of free API calls exceeded
TSAPI_MISSING_QUERY
Query missing the required search term (q parameter)
TSAPI_INVALID_SOURCE
Source (w parameter) must be one of twitter or all
TSAPI_INVALID_COUNT
Count (n parameter) must be an integer between 1 and 20
TSAPI_INVALID_GEOCODE
Geocode (g parameter) invalid format
TSAPI_INVALID_EXPAND
Expand (expand parameter) invalid value
TSAPI_MISSING_CALLBACK
Callback (callback parameter) missing value