API

We provide a RESTful API for getting information about recent trends. We'd love to hear about any cool mashups you've built with What the Trend Join our WTT API Google Group, or contact us on

Request API Key

The API can be used for commercial or non-commercial services. An API key is required. Please generate a different key per deployment platform. By generating a key, you agree to our terms of service.

URL *
URL of website making requests, or download link to product. Temporary URLs okay. (Start with http://)
Product Name *
The name of the product. Code name okay if product is unreleased.
Platform *
The deployment platform for the application.
Contact Email *
In the event we need to contact you with questions.
API Key:
Generate Key

API Usage

The What the Trend API is free for commercial or non-commercial use, but is rate limited according to the schedule below. We will waive rate limit requirements if your application provides a mechanism for users to submit a definition back. See restrictions below. If update functionality does not fit the idea of your application, please let us know as there may be alternate options.

Free feed

  • Limits: 1000 calls/24 hours*
  • Latest non-verified definitions
  • No trend history

Pro feed

  • Included with WTT Pro subscription.
  • Limits: 10,000 calls/hour*
  • Latest verified definitions
  • Trend history

Premium feed

  • Pricing available upon inquiry
  • Unlimited calls*
  • Latest verified definitions
  • Trend history
  • White-label service optional

*Data may not be cached at an intermediary point for later distribution, as it generally inhibits the user experience. If caching is necessary for size or scale, please contact us to work out details.

Waiving Rate Limits

Our goal is to enable as many people to use our API as possible, but the data is most interesting when everyone is able to contribute. Thus, we want to encourage developers to add the feature for a user to edit a definition. In order to qualify for rate limit removal, your application must do the following:

  • Display the latest definition from What the Trend with no more than a 60-second delay.
  • Allow a user to edit a definition, select a category for the trend, and indicate who started it (if known). See the update method for details.

Querying the API

  • Construct a URL. All URLs begin with http://api.whatthetrend.com/api/
  • You must provide attribution for the data coming from What the Trend servers. We've provided three easy ways to do so, using a text or image link: 

    <a href="http://api.whatthetrend.com/">
<img src="http://api.whatthetrend.com/images/wtt_api_badge_120.png" border="0">
</a>
    There is also a wtt_api_badge_120_white.png and wtt_api_badge_120_border.png for alternate looks.

    Data by What the Trend 
    <!-- Begin What the Trend HTML Attribution Snippet -->
<a href="http://api.whatthetrend.com/">Data by What the Trend</a>
<!-- End What the Trend HTML Attribution Snippet -->
    If you are unable to provide a text link in a client application, please use the following attribution: 
    Definition by whatthetrend.com
    These attributions should be placed as near as possible to any trend explanations within the user interface. If neither of these options work within the confines of your application, please contact us and we'll be happy to find an alternate solution.

    Some example alternates:

    API Methods

  • Various response formats are available. Currently: rss, xml, json. The rss feeds contain less information, the xml and json feeds contain more information (and are equivalent). The format is the last element of the URL, and is required.

Methods (V2)

Note that some methods are part of a V2 API. This will feature a different return or calling format to make the response simpler to work with. V1 will not be deprecated, but will not recieve new additional features, only bug fixes. Eventually there will be a V2 version of all V1 APIs. If you need a V2 version sooner, please let us know.

Trends

Locations

Voting

trends.format

Description

The current trending terms on Twitter, with descriptions.

Available formats

json

Parameters

  1. api_key: Required
  2. woeid: Optional Yahoo WOEID for current trends based on location
  3. callback: Optional JSONP callback parameter

Examples

Response

JSON: 
{
	"api_version" : "2.0",
	"as_of" : "2009-10-15 19:57:01",
	"trends" : [
		{ "description" : { "created_at" : "2009-10-15 19:54:32",
			"text" : "A 6 year old was believed to be stuck in a homemade hot air balloon in Denver, Colorado. The balloon landed with no boy found inside. The boy is still missing.",
			"score" : "0"
			},
		"first_trended_at" : "2009-10-15 19:00:01",
		"last_trended_at" : "2009-10-15 19:55:01",
		"name" : "Colorado",
		"newly_trending" : "0",
		"query" : "Colorado",
		"trend_index" : "1",
		"url" : "http://search.twitter.com/search?q=Colorado",
		"related_url" : "http://www.wikipedia.com/Colorado",
		"category_id" : "11",
		"category_name" : "News",
		"locked" : false
		},
		{ "description" : { "created_at" : "2009-10-15 19:54:10",
			"text" : "A 6 year old was believed to be stuck in a homemade hot air balloon in Denver, Colorado. The balloon landed with no boy found inside. The boy is still missing.",
			"score" : "0"
			},
		"first_trended_at" : "2009-10-15 19:30:01",
		"last_trended_at" : "2009-10-15 19:55:01",
		"name" : "#saveballoonboy",
		"newly_trending" : "0",
		"query" : "#saveballoonboy",
		"trend_index" : "2",
		"url" : "http://search.twitter.com/search?q=%23saveballoonboy",
		"category_id" : "11",
		"category_name" : "News",
		"locked" : false
		}, ...
	]
}

trends/active.format

Description

The currently most-edited trends on What the Trend in the last 24 hours.

Available formats

json

Parameters

  1. api_key: Required
  2. callback: Optional JSONP callback parameter

Examples

Response

JSON: 
{
	"api_version" : "2.0",
	"as_of" : "2009-10-15 19:59:00",
	"trends" : [
		 { "description" : { "created_at" : "2009-10-15 03:22:40",
			"text" : "Pero que chuuuuuuuuuuuuuchaaaaaaaaa y Chile ??",
			"score" : "0"
			},
		"edit_count" : "21",
		"first_trended_at" : "2009-10-15 03:20:02",
		"last_trended_at" : "2009-10-15 06:40:02",
		"name" : "#98b351",
		"query" : "#98b351",
		"url" : "http://search.twitter.com/search?q=%2398b351",
		"category_id" : "11",
		"category_name" : "News",
		"locked" : false
		},
		{ "description" : { "created_at" : "2009-10-15 17:38:00",
			"text" : "It's trending cuzz it's true",
			"score" : "0"
			},
		"edit_count" : "8",
		"first_trended_at" : "2009-10-15 17:30:02",
		"last_trended_at" : "2009-10-15 19:55:01",
		"name" : "#Twitterrules",
		"query" : "#Twitterrules",
		"url" : "http://search.twitter.com/search?q=%23Twitterrules",
		"category_id" : "11",
		"category_name" : "News",
		"locked" : false
		}, ...
	]
}

trends/spam

Description

A list of the trends most recently identified as SPAM or spam targets.

Available formats

json

Parameters

  1. api_key: Required
  2. count: Optional Number of trends to return. The default is 10.
  3. callback: Optional JSONP callback parameter.

Examples

Response

JSON: 
{
	"api_version" : "2.0",
	"as_of" : "2009-10-15 19:57:01",
	"trends" : [ { "description" : { "created_at" : "2009-10-15 19:54:32",
			"text" : "A 6 year old was believed to be stuck in a homemade hot air balloon in Denver, Colorado. The balloon landed with no boy found inside. The boy is still missing.",
			"score" : "0"
			},
		"first_trended_at" : "2009-10-15 19:00:01",
		"last_trended_at" : "2009-10-15 19:55:01",
		"name" : "Colorado",
		"newly_trending" : "0",
		"query" : "Colorado",
		"trend_index" : "1",
		"url" : "http://search.twitter.com/search?q=Colorado",
		"category_id" : "11",
		"category_name" : "News",
		"locked" : false
		},
		{ "description" : { "created_at" : "2009-10-15 19:54:10",
			"text" : "A 6 year old was believed to be stuck in a homemade hot air balloon in Denver, Colorado. The balloon landed with no boy found inside. The boy is still missing.",
			"score" : "0"
			},
		"first_trended_at" : "2009-10-15 19:30:01",
		"last_trended_at" : "2009-10-15 19:55:01",
		"name" : "#saveballoonboy",
		"newly_trending" : "0",
		"query" : "#saveballoonboy",
		"trend_index" : "2",
		"url" : "http://search.twitter.com/search?q=%23saveballoonboy",
		"category_id" : "11",
		"category_name" : "News",
		"locked" : false
		}, ...
	]
}

trends/locations/top

Description

A list of the #1 trend by location type.

Available formats

json

Parameters

  1. api_key: Required
  2. place_type_code: Required Woeid place type ID code. 19 = Earth, 12 = Country, 8 = Region/State, 7 = Country.
  3. callback: Optional JSONP callback parameter.

Examples

Response

JSON: 
{ "api_version" : "2.0",
	"as_of" : 1270572194,
	"trends" : [
		{ "description" : null,
		"id" : "39023",
		"last_trended_at" : "2010-03-04T18:08:29+00:00",
		"name" : "Karun Chandhok",
		"place_name" : "United States",
		"slug" : "Karun+Chandhok",
		"woeid" : "23424977"
		},
		{ "description" : { "created_at" : "2010-03-02T05:22:50+00:00",
			"text" : "People explaining why they don't care about what someone else is doing or saying",
			"score" : "0"
			},
		"id" : "41236",
		"last_trended_at" : "2010-03-04T18:09:50+00:00",
		"name" : "#BitchSoWhat",
		"place_name" : "United Kingdom",
		"slug" : "%23BitchSoWhat",
		"woeid" : "23424975"
		},
		...
	]
}

trend/revert

Description

Reverts the trend description to an earlier version.

Parameters

  • api_key: Required
  • trend_id: Required Numeric id of the trend
  • blurb_id: Required Numeric id of the description to revert to. You can get this ID from the "versions" list of a trend.
  • user_id: Required Twitter user ID
  • user_screen_name: Required Twitter user screen name
  • device_id: Required Unique ID of the connecting device. If this is restricted information, a non-sequential device-derived ID of some other form is acceptable.

Examples

Response

JSON: 
{
	"api_version":"2.0",
	"as_of":1328575080,
	"success":true,
	"message":"Trend description reverted"
}

trend/update

Description

Updates an existing trend or creates a new trend based on a trend id

Required POST Parameters

  • api_key: Required
  • trend_id: Required Numeric id of the trend to revert to. Trend_id or trend must be defined. The trend name must be url-encoded
  • trend: Required The name of the trend. Trend_id or trend must be defined. The trend name must be url-encoded
  • blurb: Required The new trend description
  • user_id: Required Twitter user ID
  • user_screen_name: Required Twitter user screen name
  • device_id: Required Unique ID of the connecting device. If this is restricted information, a non-sequential device-derived ID of some other form is acceptable.
  • category_id: Required Category for the trend. See categories for more information.

Optional POST Parameters

  • latitude: Latitude of user's geographic location.
  • longitude: Longitude of user's geographic location.
  • locale: IETF language code (RFC 5646 and RFC 4647), which is ll-US, where ll is a two-letter language code from ISO 639, and CC is a two-letter uppercase country code from ISO 3166.

Examples

api_key:
trend_id:
trend:
user_id:
user_screen_name:
device_id:
category_id:
blurb:


Response

JSON: 
{
	"api_version":"2.0",
	"as_of":1328575080,
	"success":true,
	"message":"What the trend offers user contributed definitions for trending topics on twitter.com."
}

trend/spam

Description

Marks a trend as SPAM

Parameters

  • api_key: Required
  • trend_id: Required Numeric id of the trend
  • user_id: Required Twitter user ID
  • user_screen_name: Required Twitter user screen name

Examples

Response

200 OK if successful.

categories

Description

A list of the categories available.

Available formats

json

Parameters

  1. api_key: Required
  2. callback: Optional callback parameter

Examples

Response

JSON: 
{
	"api_version":"2.0",
	"categories":
	[
		{"id":1,"name":"Entertainment"},
		{"id":2,"name":"Gaming"},
		{"id":3,"name":"Lifestyle"},
		{"id":4,"name":"Science"},
		{"id":5,"name":"Sports"},
		{"id":6,"name":"Technology"},
		{"id":7,"name":"Business"},
		{"id":8,"name":"SPAM"},
		{"id":9,"name":"Meme"},
		{"id":10,"name":"Conference or Event"},
		{"id":11,"name":"News"},
		{"id":12,"name":"Place or Location"},
		{"id":13,"name":"Holiday or Date"},
		{"id":14,"name":"Other"}
	]
}

locations/current

Description

A list of the current trending locations.

Available formats

json

Parameters

  1. api_key: Required
  2. callback: Optional callback parameter

Examples

Response

JSON: 
{
	"api_version" : "2.0",
	"as_of" : 1270490234,
	"locations" : [
		{ "count" : "326",
		"country_name" : "1",
		"name" : "Earth",
		"place_type_code" : "19",
		"place_type_name" : "Supername",
		"woeid" : "1"
		},
		{ "count" : "346",
		"country_name" : "23424768",
		"name" : "Brazil",
		"place_type_code" : "12",
		"place_type_name" : "Country",
		"woeid" : "23424768"
		},
		...
}

locations/all

Description

A list of all locations to ever trend.

Available formats

json

Parameters

  1. api_key: Required
  2. callback: Optional callback parameter

Examples

Response

JSON: 
{
	"api_version" : "2.0",
	"as_of" : 1270490456,
	"locations" : [
		{ "country_name" : "1",
		"name" : "Earth",
		"place_type_code" : "19",
		"place_type_name" : "Supername",
		"updated" : "2010-04-05T18:05:17+00:00",
		"woeid" : "1"
		},
		{ "country_name" : "23424748",
		"name" : "Australia",
		"place_type_code" : "12",
		"place_type_name" : "Country",
		"updated" : "2009-12-15T18:14:23+00:00",
		"woeid" : "23424748"
		},
		...
}

vote_up

Description

Vote the current definition up. A user may only vote once.

Available formats

json

Parameters

  1. api_key: Required
  2. blurb_id: Required Numeric id of the description to vote on. You can get this ID from the "versions" list of a trend.
  3. user_id: Required Twitter user ID
  4. user_screen_name: Required Twitter user screen name
  5. device_id: Required Unique ID of the connecting device. If this is restricted information, a non-sequential device-derived ID of some other form is acceptable.
  6. callback: Optional callback parameter

Examples

Response

200 OK if successful, with the current score of the blurb.
JSON: 
{
	"api_version":"2.0",
	"as_of":1328575080,
	"success":true,
	"score":2
}

vote_down

Description

Vote the current definition down. A user may only vote once.

Available formats

json

Parameters

  1. api_key: Required
  2. blurb_id: Required Numeric id of the description to vote on. You can get this ID from the "versions" list of a trend.
  3. user_id: Required Twitter user ID
  4. user_screen_name: Required Twitter user screen name
  5. device_id: Required Unique ID of the connecting device. If this is restricted information, a non-sequential device-derived ID of some other form is acceptable.
  6. callback: Optional callback parameter

Examples

Response

200 OK if successful, with the current score of the blurb.
JSON: 
{
	"api_version":"2.0",
	"as_of":1328575080,
	"success":true,
	"score":2
}

flag

Description

Flag the current definition as offensive. A user may only vote once.

Available formats

json

Parameters

  1. api_key: Required
  2. blurb_id: Required Numeric id of the description to flag. You can get this ID from the "versions" list of a trend.
  3. user_id: Required Twitter user ID
  4. user_screen_name: Required Twitter user screen name
  5. device_id: Required Unique ID of the connecting device. If this is restricted information, a non-sequential device-derived ID of some other form is acceptable.
  6. callback: Optional callback parameter

Examples

Response

200 OK if successful, with the current score of the blurb.
JSON: 
{
	"api_version":"2.0",
	"as_of":1328575080,
	"success":true,
	"score":2
}

Methods (V1)

trend/getByName

Returns all information about a single trend.

Available formats

json, jsonp, xml, rss

Parameters

  • URL-encoded trend name. Typically, you could get a trend name from the 'name' property of one of the trends on the Twitter Search API at http://search.twitter.com/trends.json or from another API method
  • versions: Number of previous trend explanations to include, most recent explanation first. If omitted, returns last explanation. -1 returns all.
  • api_key: Required

Examples

Be careful with special characters, the trend name should be URL-encoded:

trend/getById

Returns all information about a single trend, given a trend id.

Available formats

json, jsonp, xml, rss

Parameters

  • ID (a positive integer), returned from another What the Trend API function.
  • versions: Number of previous trend explanations to include, most recent explanation first. If omitted, returns last explanation. -1 returns all.
  • api_key: Required

Examples

trend/search (simple)

Search for a trend with the specified text. Returns up to the top 10 matching trends as a very simple carriage-return-delimited list. This is useful for auto-complete text boxes.

Parameters

  • api_key: Required
  • q: The text to search for. Make sure it's URL-encoded.

Examples

trend/search_extended

Search for a trend with the specified text. Returns up to the top 10 matching trends along with with their explanation

Available formats

rss, xml, json, jsonp

Parameters

  • api_key: Required
  • count: Number of items to return (1-10)
  • q: The text to search for. Make sure it's URL-encoded.

Examples

  • RSS for 'friday': http://api.whatthetrend.com/api/trend/search_extended/rss?api_key=xxxx&count=2&q=friday 
    	
<?xml version="1.0"?>
<rss version="2.0">
	<channel>
	<title>What The Trend?</title>
	<link>http://www.whatthetrend.com/</link>
	<description>Find out WHY terms are trending on Twitter.</description>
	<managingEditor>api@whatthetrend.com (What The Trend)</managingEditor>
	<language>en</language>
	<item>
		<pubDate>Sat, 07 Mar 2009 06:40:01 +0800</pubDate>
		<guid>108.83</guid>
		<link>http://www.whatthetrend.com/trend/%23followfriday</link>
		<title>#followfriday</title>
		<description>Game in which people recommend people to follow on Twitter, on Fridays http://mashable.tumblr.com/post/72589347</description>
	</item>
	<item>
		<pubDate>Fri, 08 May 2009 14:30:03 +0800</pubDate>
		<guid>144.518</guid>
		<link>http://www.whatthetrend.com/trend/Fridays</link>
		<title>Fridays</title>
		<description>Because it's Friday. </description>
	</item>
	</channel>
</rss>
  • XML for #followfriday: http://api.whatthetrend.com/api/trend/search_extended/xml?api_key=xxxx&count=2&q=friday 
    <?xml version="1.0"?>
	<api version="1.0">
	<trends>
	<trend>
		<id>108</id>
		<name>#followfriday</name>
		<dates>
		<firstTrend>2009-02-20T03:35:01Z</firstTrend>
		<lastTrend>2009-03-07T06:40:01Z</lastTrend>
		</dates>
		<links>
		<url>http://www.whatthetrend.com/trend/%23followfriday</url>
		<tinyUrl>http://wttrend.com/108</tinyUrl>
		</links>
		<blurb>
		<id>83</id>
		<text>Game in which people recommend people to follow on Twitter, on Fridays</text>
		<timestamp>2009-02-20T03:07:39Z</timestamp>
		</blurb>
		<versions/>
	</trend>
	<trend>
		<id>144</id>
		<name>Fridays</name>
		<dates>
		<firstTrend>2009-02-20T14:20:01Z</firstTrend>
		<lastTrend>2009-05-08T14:30:03Z</lastTrend>
		</dates>
		<links>
		<url>http://www.whatthetrend.com/trend/Fridays</url>
		<tinyUrl>http://wttrend.com/144</tinyUrl>
		</links>
		<blurb>
		<id>518</id>
		<text>Because it's Friday. </text>
		<timestamp>2009-03-06T11:42:44Z</timestamp>
		</blurb>
		<versions/>
	</trend>
	</trends>
</api>
  • JSON for #followfriday: http://api.whatthetrend.com/api/trend/search_extended/json?api_key=xxxx&count=2&q=friday 
    {
	"api": {
	"@attributes": {
		"version": "1.0"
	},
	"trends": {
		"trend": [{
		"id": "108",
		"name": "#followfriday",
		"dates": {
			"firstTrend": "2009-02-20T03:35:01Z",
			"lastTrend": "2009-03-07T06:40:01Z"
		},
		"links": {
			"url": "http://www.whatthetrend.com/trend/%23followfriday",
			"tinyUrl": "http://wttrend.com/108"
		},
		"blurb": {
			"id": "83",
			"text": "Game in which people recommend people to follow on Twitter, on Fridays.",
			"timestamp": "2009-02-20T03:07:39Z"
		},
		"versions": ""
		},
		{
		"id": "144",
		"name": "Fridays",
		"dates": {
			"firstTrend": "2009-02-20T14:20:01Z",
			"lastTrend": "2009-05-08T14:30:03Z"
		},
		"links": {
			"url": "http://www.whatthetrend.com/trend/Fridays",
			"tinyUrl": "http://wttrend.com/144"
		},
		"blurb": {
			"id": "518",
			"text": "Because it's Friday.",
			"timestamp": "2009-03-06T11:42:44Z"
		},
		"versions": ""
		}]
	}
	}
}
  • JSONP for #followfriday: http://api.whatthetrend.com/api/trend/search_extended/jsonp?api_key=xxxx&count=2&q=friday&callback=handleResponse 
    handleResponse({
	"api": {
	"@attributes": {
		"version": "1.0"
	},
	"trends": {
		"trend": [{
		"id": "108",
		"name": "#followfriday",
		"dates": {
			"firstTrend": "2009-02-20T03:35:01Z",
			"lastTrend": "2009-03-07T06:40:01Z"
		},
		"links": {
			"url": "http://www.whatthetrend.com/trend/%23followfriday",
			"tinyUrl": "http://wttrend.com/108"
		},
		"blurb": {
			"id": "83",
			"text": "Game in which people recommend people to follow on Twitter, on Fridays.",
			"timestamp": "2009-02-20T03:07:39Z"
		},
		"versions": ""
		},
		{
		"id": "144",
		"name": "Fridays",
		"dates": {
			"firstTrend": "2009-02-20T14:20:01Z",
			"lastTrend": "2009-05-08T14:30:03Z"
		},
		"links": {
			"url": "http://www.whatthetrend.com/trend/Fridays",
			"tinyUrl": "http://wttrend.com/144"
		},
		"blurb": {
			"id": "518",
			"text": "Because it's Friday.",
			"timestamp": "2009-03-06T11:42:44Z"
		},
		"versions": ""
		}]
	}
	}
})

trend/update

Updates a trend description via an HTTP POST. Note that this request will only be successful for the first 10 requests each hour from an individual IP address. Access may be blocked if this request is abused (for example, posting spammy descriptions). Please provide a human-readable name of your app in the "from" parameter.

POST Parameters

  • id (a positive integer): returned from another What the Trend API function
  • description (string): new description.
  • from (string): a string description of your application
  • api_key: Required

Examples

Response

Whether updating is successful or failed, the response is text/html, and contains a copy of the blurb submitted, with any HTML stripped and URLs linked.

© 2012 HootSuite Media, Inc. All rights reserved.

You must be logged in to do that. Log in Here
(click to close)