Search API v1.5

Purpose

URL

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

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.

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: