Trendspottr :: Search API v1.5

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.php

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 and can be purchased directly from the TrendSpottr API Pricing Plans page.

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, searchdemo.txt, is available that demonstrates how to call the TrendSpottr API via curl. Once downloaded, rename the file to have a .php extension, edit it to insert your personal username and password, then run it under the php interpreter to download data from TrendSpottr and parse it.

Parameters

Parameter	State	Default	Description
key	required	none	This parameter passes to the API your personal API key. If a valid key is not provided, the request will fail. See the Authentication section above for details on how to get an API key.
q	required	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 http://twitter.com/#!/<user>/<list> the API will use the list as the source of tweets to analyze rather than using it as a search term in the twitter firehose.
w	optional	twitter	This parameter designates which source to search in. Allowed values are twitter, facebook and all.
n	optional	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 all categories returned via a single request can contain a different number of results. The maximum permitted value for n is 40.
g	optional	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 from 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	unset	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	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	false	Allowed values are: true or false True will force expansion of all shortened URL’s setting the expanded field to an oembed formatted expansion of the original URL appearing in the content. Care must be taken to ensure that proper handling of possibly missing fields such as thumbnail_url is accounted for. False will return the unexpanded values for URL’s that are found, expecting the caller to expand them after receiving the list. Note that if this parameter is set to true, TrendSpottr must pull data from every website included in the results to get the embedded data. This can dramatically increase the time necessary for the API to complete the request.
callback	optional	unset	If set, this parameter indicates the callback name to be used and generates the results will be returned in JSONP format.

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 a list of four arrays, each containing elements of the corresponding types 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.

Array	Description
Links	These are the top trending URLs that were associated with the search term provided. If the expand parameter was set to true, the result will also contain the oembed expansion of the URL
Hashtags	These are the top trending hashtags that were associated with the search term provided
Phrases	These are the top trending three word phrases that were associated with the search term provided
Sources	These are the accounts that generated the most current top trending content that was associated with the search term provided

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” : “2.1”,
            “expanded” : 
                {
                <oembed structured data>
                }
            },
            …
        ],
        “hashtags” : 
        [
            {“value” : ”#theHashtag”,
            “weight” : “4.3”},
            …
        ],
        “phrases” :
        [
            {“value” : “the phrase”,
            “weight” : “3.5”},
            …
        ],
        “sources” :
        [
            {“value” : “the source”,
            “weight” : “5.2”},
            …
        ],
    }
}

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

{"error":
    {"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 facebook, twitter, or all
TSAPI_INVALID_COUNT	Count (n parameter) must be an integer between 1 and 40
TSAPI_INVALID_GEOCODE	Geocode (g parameter) invalid format
TSAPI_INVALID_EXPAND	Expand (expand parameter) invalid value
TSAPI_MISSING_CALLBACK	Callback (callback parameter) missing value