My favorites ▼ | Sign in
Project Home Wiki Issues Source
Search
for
Resources  
Updated Feb 7, 2012 by vanessa....@gmail.com

The Otter URI

The api is accessible via the uri: http://otter.topsy.com/

Request Syntax

All requests are implemented via HTTP GET calls. The url of the request can be broken down into three parts: Resources (described below), response format, and query parameters. A malformed request will return a response with HTTP 400 status.

GET /resource.response-format?keys=values HTTP/1.1
Host: otter.topsy.com

apikey

You can obtain a free API key for the Otter API by creating an account at http://manage.topsy.com/app.

All requests accept the API key via the apikey parameter.

GET /resource.response-format?apikey=KEY&keys=values HTTP/1.1

Resources

/authorinfo

Description: Profile information for an author (a twitter profile indexed by Topsy). The response contains the name, description (biography) and the influence level of the author.

Explanation of Influence: TopsyGlossary

Parameters:

Name Required Description
url required URL string for the author.

Example:

Fetch information about Barack Obama's Twitter profile. 

$ curl -i "http://otter.topsy.com/authorinfo.json?url=http://twitter.com/barackobama"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 03:57:16 GMT
Content-Length: 587
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:02:16 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2468
X-RateLimit-Reset: 1251345600

{
   "request" : {
      "parameters" : {
         "url" : "http://twitter.com/barackobama"
      },
      "response_type" : "json",
      "resource" : "authorinfo",
      "url" : "http://otter.topsy.com/authorinfo.json?url=http%3A%2F%2Ftwitter.com%2Fbarackobama"
   },
   "response" : {
      "name" : "Barack Obama",
      "url" : "http://twitter.com/barackobama",
      "type" : "twitter",
      "nick" : "barackobama",
      "description" : "44th President of the United States",
      "topsy_author_url" : "http://topsy.com/twitter/barackobama",
      "influence_level" : "5"
   }
}

/experts

Description: List of authors that talk about the query. The list is sorted by frequency of posts and the influence of authors. (Note: for backwards compatibility, the /authorsearch api method is an alias to /experts.)

Parameters:

Name Required Description
q required Search query string. (query syntax)
config_NoFilters optional Setting this to 1, would turn off all other filters. Default value is 0.

Accepts List Parameters

Example:

Fetch search results in json format for authors who talk about "nosql" the most. 

$ curl -i "http://otter.topsy.com/experts.json?q=nosql"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:13:46 GMT
Content-Length: 7473
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:18:45 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2494
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "q" : "nosql"
      },
      "response_type" : "json",
      "resource" : "experts",
      "url" : "http://otter.topsy.com/experts.json?q=nosql"
   },
   "response" : {
      "page" : 1,
      "total" : "1139",
      "perpage" : 15,
      "list" : [
         {
            "name" : "nosql topsy 5",
            "nick" : "nosql_topsy_5",
            "photo_url" : "",
            "description" : "",
            "influence_level" : "1",
            "hits" : 72,
            "trackback_total" : 104,
            "url" : "http://twitter.com/nosql_topsy_5",
            "topsy_author_url" : "http://topsy.com/twitter/nosql_topsy_5"
         },
         ...
      ]
   }
}

/linkposts

Description: List of urls posted by an author.

Parameters:

Name Required Description
url required URL string for the author.
contains optional Query string to filter results.
tracktype optional Type of posts. Options include: image, tweet__various (tweets and retweets) and self__tweet (tweets by user).

Accepts List Parameters

Example:

Fetch links in json format posted by Barack Obama. 

$ curl -i "http://otter.topsy.com/linkposts.json?url=http://twitter.com/barackobama"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:16:29 GMT
Content-Length: 6247
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:21:29 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2492
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "url" : "http://twitter.com/barackobama"
      },
      "response_type" : "json",
      "resource" : "linkposts",
      "url" : "http://otter.topsy.com/linkposts.json?url=http%3A%2F%2Ftwitter.com%2Fbarackobama"
   },
   "response" : {
      "page" : 1,
      "total" : "288",
      "perpage" : 10,
      "list" : [
         {
            "permalink_url" : "http://twitter.com/barackobama/status/3569838653",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/tb/my.barackobama.com/page/community/post/obamaforamerica/gGMPVm",
               "url" : "http://my.barackobama.com/page/community/post/obamaforamerica/gGMPVm",
               "trackback_total" : "43"
            },
            "date" : "1251337427",
            "content" : "Highlights from the tribute to Sen. Kennedy's life and 
                accomplishments from last year's Democratic National Convention: http://bit.ly/TJcyr",
            "date_alpha" : "3 hours ago"
         },
         ...
      ]
   }
}

/linkpostcount

Description: Count of links posted by an author. This is the efficient, count-only version of /linkposts

Parameters:

Name Required Description
url required URL string for the author.
contains optional A query filter for linkposts (the content must contain this string).
tracktype optional Type of posts. Options include: tweet__various (tweets and retweets) and self__tweet (tweets by user).

Example:

Fetch only the linkpost counts in json format that reference Topsy's Twitter account. 

$ curl -i "http://otter.topsy.com/linkpostcount.json?url=http://twitter.com/topsy"


HTTP/1.1 200 OK
Content-Length: 234
Content-Type: application/json; charset=utf-8
Expires: Tue, 22 Sep 2009 13:51:10 -0700
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2490
X-RateLimit-Reset: 1253653200
Date: Tue, 22 Sep 2009 20:46:10 GMT

{
    "request" : {
        "parameters" : {
            "url" : "http://twitter.com/topsy"
        },
        "response_type" : "json",
        "resource" : "linkpostcount",
        "url" : "http://otter.topsy.com/linkpostcount.json?url=http%3A%2F%2Ftwitter.com%2Ftopsy"
    },
    "response" : {
        "contains" : 0,
        "all" : 46
    }
}

/populartrackbacks

Description: List of most popular and unique tweets (trackbacks) that mention the query URL.

Parameters:

Name Required Description
url required URL string for the target.

Accepts List Parameters

Example:

Fetch most popular posts (tweets) in json format that reference Topsy's homepage. 

$ curl -i "http://otter.topsy.com/populartrackbacks.json?url=http%3A%2F%2Fwww.google.com%2F"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:16:29 GMT
Content-Length: 6247
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:21:29 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2492
X-RateLimit-Reset: 1251349200

{
    'request' => {
    'resource' => 'populartrackbacks',
    'response_type' => 'txt',
    'parameters' => {
      'orig_url' => 'http://google.com',
      'redirected_url' => 'http://www.google.com/',
      'url' => 'http://www.google.com/'
    },
    'url' => 'http://otter.topsy.com/populartrackbacks.txt?orig_url=http%3A%2F%2Fgoogle.com&redirected_url=http%3A%2F%2Fwww.google.com%2F&url=http%3A%2F%2Fwww.google.com%2F'
  },
  'response' => {
    'topsy_trackback_url' => 'http://topsy.com/google.com/',
    'page' => 1,
    'total' => 0,
    'trackback_total' => 125,
    'list' => [
      {
        'similar_total' => 8,
        'date' => 1274459250,
        'content' => 'RT @kevinrose: wow, http://google.com, click 'insert coin'',
        'type' => 'tweet',
        'author' => {
          'url' => 'http://twitter.com/frsh_',
          'name' => 'Chris Boyd',
          'nick' => 'frsh_',
          'photo_url' => 'http://a3.twimg.com/profile_images/564119011/16450_358726020331_903405331_9898493_4059510_n_normal.jpg',
          'topsy_author_url' => 'http://topsy.com/twitter/frsh_?utm_source=otter'
        },
        'date_alpha' => 'May 21, 2010',
        'highlight' => 'RT @kevinrose: wow, http://google.com, click 'insert coin' '
      },
         ...
      ]
   }
}

/search

Description: List of results for a query.

Parameters:

Name Required Description
q required Search query string. (query syntax)
window optional Time window for results. (Options: dynamic - will pick the most relevant window. Possible responses are 1-23 hours or 1-100 days. (For example: h6 or d10). h last hour, d last day, w last week, m last month, a all time. (DEPRECATED: auto - automatically pick the most relevant window. This will return one of the standard h,d,w,m,a window values.).
type optional The type of result. Default is nothing, which includes all types. Other supported values are image, tweet and video
query_features optional Enables QueryFeatures described in the wiki. Only works when window=dynamic

Accepts List Parameters

Example:

Fetch search results in json format for the query "barack obama" 

$ curl -i "http://otter.topsy.com/search.json?q=barack+obama&window=dynamic"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:06:32 GMT
Content-Length: 9097
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:11:31 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2498
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "window" : "auto",
         "q" : "barack obama"
      },
      "response_type" : "json",
      "resource" : "search",
      "url" : "http://otter.topsy.com/search.json?q=barack+obama&window=auto"
   },
   "response" : {
      "window" : "d2",
      "page" : 1,
      "total" : "809",
      "perpage" : 10,
      "list" : [
         {
            "trackback_permalink" : "http://twitter.com/ewerickson/status/3562164195",
            "hits" : 38,
            "trackback_total" : 157,
            "topsy_trackback_url" : "http://topsy.com/tb/www.redstate.com/erick/2009/08/26/breaking-rumors-surface-that-leon-panetta-is-resigning/",
            "url" : "http://www.redstate.com/erick/2009/08/26/breaking-rumors-surface-that-leon-panetta-is-resigning/",
            "content" : "Panetta is rumored to have sent a resignation letter to Barack Obama today:  http://bit.ly/CDMg9",
            "title" : "BREAKING: Rumors Surface That Leon Panetta is Resigning - Erick’s blog - RedState",
            "score" : 0.75521481,
            "highlight" : "Panetta is rumored to have sent a resignation letter to 
                <span class=\"highlight-term\">Barack</span> <span class=\"highlight-term\">Obama</span> today:  http://bit.ly/CDMg9"
         },
         ...
      ]
   }
}

Example:

Fetch the most popular youtube videos today. 

$ curl -i "http://otter.topsy.com/search.json?q=site:youtube.com&window=d"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:09:09 GMT
Content-Length: 7086
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:14:09 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2496
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "window" : "d",
         "q" : "site:youtube.com"
      },
      "response_type" : "json",
      "resource" : "search",
      "url" : "http://otter.topsy.com/search.json?q=site%3Ayoutube.com&window=d"
   },
   "response" : {
      "window" : "d",
      "page" : 1,
      "total" : "58258",
      "perpage" : 10,
      "list" : [
         {
            "trackback_permalink" : "http://twitter.com/danilogentili/status/3567528055",
            "hits" : 2499,
            "trackback_total" : 3450,
            "topsy_trackback_url" : "http://topsy.com/trackback?url=http://www.youtube.com/watch?v=i_KPsH7f3xo",
            "url" : "http://www.youtube.com/watch?v=i_KPsH7f3xo",
            "content" : "Após ver isso http://bit.ly/xOl3b, eu, Danilo Zentili, 
                peço perdão aos fãs da Susxa que, como @Davis_Reimberg , sonhavam ser paquitas.",
            "title" : "MEXEU COM A XUXA MEXEU COMIGO!!!",
            "score" : 24.20444298,
            "highlight" : "Após ver isso http://bit.ly/xOl3b, eu, Danilo Zentili, 
                peço perdão aos fãs da Susxa que, como @Davis_Reimberg , sonhavam ser paquitas."
         },
         ...
      ]
   }
}

/searchcount

Description: Count of results for a search query.

Parameters:

Name Required Description
q required Search query string. (query syntax)
dynamic optional If the value equals 1, the response will contain an extra window that is the best window for the given query. The possible responses are h1 through h23, or d1 through d100. These represent hourly or daily increments. NOTE: the output format of the response will change when this parameter is used.

Example:

Fetch only the search result counts in json format for a query of "Barack Obama". 

$ curl -i "http://otter.topsy.com/searchcount.json?q=Barack+Obama"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:15:16 GMT
Content-Length: 335
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:20:16 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2493
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "q" : "Barack Obama"
      },
      "response_type" : "json",
      "resource" : "searchcount",
      "url" : "http://otter.topsy.com/searchcount.json?q=Barack+Obama"
   },
   "response" : {
      "w" : 2085,
      "h" : 6,
      "a" : 572027,
      "d" : 330,
      "m" : 9122
   }
}

/searchhistogram

Description: The searchhistogram provides information to determine when a particular keyword peaked in the past days.

Parameters:

Name Required Description
q required Search query string. (query syntax)
slice optional The number of seconds for each slice. Defaults to 86400 (1 day)
period optional The number of slices. Defaults to 30 (1 month)
count_method options This has two possible values, the default is "target" and the other possible value is "citation". count_method specifies what is being counted, "target" means the number of unique links and "citation" means the number of unique tweets about links.

A searchhistorgram is a time-series of the number of distinct social media posts (tweets or links) that match a given query, over a defined time period. The granularity and the length of the time-series can be specified with the slice and period parameters.

SearchHistograms have applications in analytics, trend detection, query freshness determination and social media monitoring. The Topsy Analytics application is built on this API call.

SearchHistograms are generated from Topsy's real-time search index and are available ad-hoc for any query. It should be noted that because the search index performs "sub-sampling", it underestimates counts for older time periods. In general, counts are accurate up to 3 months for most terms and up to 1 month for very popular terms (like iPhone and Justin Bieber).

Example:

Fetch only the search result counts in json format for a query of "kindle". 

$ curl -i "http://otter.topsy.com/searchhistogram.json?q=kindle"

HTTP/1.1 200 OK
Cache-Control: max-age=5
Content-Type: application/json; charset=utf-8
Expires: Mon, 14 Feb 2011 21:35:05 GMT
Last-Modified: Mon, 14 Feb 2011 21:35:00 GMT
Server: lighttpd/1.4.26
Content-Length: 1675
Date: Mon, 14 Feb 2011 21:35:00 GMT
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9998
X-RateLimit-Reset: 1297722896
Connection: close

{"request":{"parameters":{"q":"kindle","type":"cited"},"response_type":"json","resource":"searchhistogram","url":"http://otter.topsy.com/searchhistogram.json?q=kindle&type=cited"},"response":
{"histogram":[2839,3748,4223,3530,5104,5439,5302,5192,5630,4935,4560,3687,4963,6003,6191,5068,5387,6273,4831,5069,4578,4530,5774,5918,4655,5072,5434,5086,5112,5589,5173,4751,5185,4749,5246,47
97,4917,4901,5168,5429,6291,5646,5184,5436,4995,6385,5932,5945,7589,7697,6535,4619,3774,3944,4682,3672,3515,3068,3496,5457,5491,5496,4157,3571,3125,3187,3552,5233,5561,5753,4556,3960,4118,461
3,5257,5619,4073,4240,3744,3784,4762,5053,4418,4293,4065,4061,4337,4421,3969,3909,4077,3889,3711,3968,4381,5130,5027,5249,4142,3844,3796,4245,4069,4080,4893,4512,3883,3986,4840,4641,4615,5088
,5321,4006,4834,4391,4188,3930,4211,4192,3267,2668,3285,3533,3756,3877,3337,2620,2715,3106,2833,3635,3783,3107,3018,3012,3357,3528,3998,4808,3564,5103,6132,6944,7914,7297,6831,6081,4982,5467,
6656,5724,7360,8795,5517,4521,4384,5913,6587,6021,6927,5323,4495,4641,5529,5847,6780,7274,4061,4966,4140,3034,4854,4498,3035,3188,2665,2616,3012,2697,3181,2559,2401,2217,2380,2388,2806,3772,3
724,3018,2888,2900,2812,3417,2922,3972,2985,2206,2336,3949,8987,1933,1831,1445,1517,1230,1386,1282,1069,1919,651,663,583,694,697,794,901,726,764,654,729,895,958,986,885,718,692,975,1790,1081,
1725,1239,525,592,542,605,766,1637,1064,353,341,363,507,653,743,330,48,112,318,390,477,537,506,407,345,389,442,597,758,557,411,582,520,500,703,572,521,385,354,385,422,726,1092,458,293,217,374
,418,738,822,438,366,416,542,509,591,603,431,354,589,614,736,509,617,573,385,599,660,580,581],"period":300,"count_method":"target","slice":86400}}

/searchdate

Description: Returns search results sorted by reverse chronology. All options are the same as that of /search.

This method performs regular search as /search, picks top N results based on relevance, then sort them by the timesstamp of the first citation. In other words, it is a timeline of high quality results. The quality level is controlled by parameter "zoom", the default value 10 will pick up to 100 results.

Parameters:

Name Required Description
q required Search query string. (query syntax)
window optional See /search documentation.
type optional See /search documentation.
zoom optional Zoom-level for depth / quality. Default is 10, which picks 100 results

/stats

Description: Count of tweets for a url. This is an efficient way of getting the counts only. For detailed information about a URL, use urlinfo.

Parameters:

Name Required Description
url required URL string for the target.
contains optional A query filter for trackbacks (the trackbacks must contain this string).

Example:

Fetch only the trackback counts in json format that reference Topsy's homepage. 

$ curl -i "http://otter.topsy.com/stats.json?url=http://topsy.com/"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:27:18 GMT
Content-Length: 335
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:32:18 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2486
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "url" : "http://topsy.com/"
      },
      "response_type" : "json",
      "resource" : "stats",
      "url" : "http://otter.topsy.com/stats.json?url=http%3A%2F%2Ftopsy.com%2F"
   },
   "response" : {
      "topsy_trackback_url" : "http://topsy.com/tb/topsy.com/",
      "contains" : "1931",
      "influential" : "874",
      "all" : "1931"
   }
}

/top

Description: A feed of Top 100, 1K, 5K and 20K links, photos, tweets & videos posted on the social web everyday.

Parameters:

Name Required Description
thresh required top100, top1k, top5k, top20k
type optional defaults to everything. Other values: image, video, tweet
locale optional defaults to all. Other values: en, ja, ko, de, pt, es, th, fr

Accepts List Parameters

This method returns a feed of Top 100, or 1K (1000), 5K (5000), 20K (20,000) items posted on Twitter everyday. The list is computed using a predictive algorithm, which dynamically adjusts ranking criteria to determine the threshold number of items everyday. You can select a particular threshold with the thresh parameter.

When type is not specified, the list includes all types of items. There are independent lists for type image, video and tweet, that can be accessed with the type parameter.

Several languages are supported by /top, described in the table above.

Example:

Fetch the Top 100 tweets in English. 

$ curl -i "http://otter.topsy.com/top.json?thresh=top100&type=tweet&locale=en"

HTTP/1.1 200 OK
Cache-Control: max-age=5
Content-Type: application/json; charset=utf-8
Expires: Wed, 23 Mar 2011 01:51:17 GMT
Last-Modified: Wed, 23 Mar 2011 01:51:12 GMT
Server: lighttpd/1.4.26
Content-Length: 8440
Date: Wed, 23 Mar 2011 01:51:13 GMT
X-Varnish: 1488685665
Age: 0
Via: 1.1 varnish
X-Served-By: ps391
X-Cache: MISS
Connection: close

{
   "request" : {
      "resource" : "top",
      "response_type" : "json",
      "parameters" : {
         "locale" : "en",
         "type" : "tweet",
         "thresh" : "top100"
      },
      "url" : "http://otter.topsy.com/top.json?locale=en&thresh=top100&type=tweet"
   },
   "response" : {
      "page" : 1,
      "locale" : "en",
      "total" : 500,
      "perpage" : 10,
      "last_offset" : 14,
      "hidden" : 1,
      "thresh" : "top100",
      "list" : [
         {
            "author_url" : "http://twitter.com/idothat2",
            "date" : 1300844963,
            "author_img" : "http://a1.twimg.com/profile_images/1246614074/idothattoo_normal.png",
            "content" : "RT @IDoThat2: Make a fist with your left hand, squeeze your left thumb, then put your right index finger down your throat. NO GAG REFLEX.",
            "date_alpha" : "41 seconds ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/idothat2/status/50368320272220160?utm_source=otter",
               "url" : "http://twitter.com/idothat2/status/50368320272220160",
               "mytype" : "tweet",
               "title" : "Make a fist with your left hand, squeeze your left thumb, then put your right index finger down your throat. NO GAG REFLEX.",
               "trackback_total" : 445
            },
            "author_nick" : "idothat2",
            "firstpost_date" : 1300843743,
            "topsy_author_url" : "http://topsy.com/twitter/idothat2?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/quixotic",
            "date" : 1300844892,
            "author_img" : "http://a0.twimg.com/profile_images/14300972/pic_mgmt_rhoffman_100x100_normal.gif",
            "content" : "RT @quixotic: Here&#39;s the 10 rules of massive entrepreneurship that I covered at SXSW.  http://lnkd.in/BfdBkT",
            "date_alpha" : "2 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/quixotic/status/50369753562357761?utm_source=otter",
               "url" : "http://twitter.com/quixotic/status/50369753562357761",
               "mytype" : "tweet",
               "title" : "Here&#39;s the 10 rules of massive entrepreneurship that I covered at SXSW.  http://lnkd.in/BfdBkT",
               "trackback_total" : 17
            },
            "author_nick" : "quixotic",
            "firstpost_date" : 1300844076,
            "topsy_author_url" : "http://topsy.com/twitter/quixotic?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/niw",
            "date" : 1300844714,
            "author_img" : "http://a0.twimg.com/profile_images/1255264346/discover_normal.jpg",
            "content" : "RT @niw: Mac OS Xでどうぞ→ $ say &quot;tahno see nurcomer gah popopo-poooon\\!&quot;",
            "date_alpha" : "5 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/niw/status/50293712605036544?utm_source=otter",
               "url" : "http://twitter.com/niw/status/50293712605036544",
               "mytype" : "tweet",
               "title" : "Mac OS Xでどうぞ→ $ say &quot;tahno see nurcomer gah popopo-poooon\\!&quot;",
               "trackback_total" : 21
            },
            "author_nick" : "niw",
            "firstpost_date" : 1300826225,
            "topsy_author_url" : "http://topsy.com/twitter/niw?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/herbcaen",
            "date" : 1300844451,
            "author_img" : "http://a3.twimg.com/profile_images/843522902/herb1_normal.jpg",
            "content" : "RT @HerbCaen: Caress each Spanish syllable. Don&#39;t say &quot;Frisco.&quot; Don&#39;t say &quot;San-Fran-Cis-Co.&quot; That&#39;s how tourists pronounce it. It&#39;s &quot;SanfrnSISco.&quot;",
            "date_alpha" : "9 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/herbcaen/status/50302206058053632?utm_source=otter",
               "url" : "http://twitter.com/herbcaen/status/50302206058053632",
               "mytype" : "tweet",
               "title" : "Caress each Spanish syllable. Don&#39;t say &quot;Frisco.&quot; Don&#39;t say &quot;San-Fran-Cis-Co.&quot; That&#39;s how tourists pronounce it. It&#39;s &quot;SanfrnSISco.&quot;",
               "trackback_total" : 23
            },
            "author_nick" : "herbcaen",
            "firstpost_date" : 1300827990,
            "topsy_author_url" : "http://topsy.com/twitter/herbcaen?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/ajelive",
            "date" : 1300844327,
            "author_img" : "http://a3.twimg.com/profile_images/955686894/AJE_TWITTER_ICON_normal.jpg",
            "content" : "RT @AJELive: Reports of at least 4 people killed in the #Syrian city of #Daraa, where residents say electricity has been cut off: http://aje.me/hBUe4g",
            "date_alpha" : "11 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/ajelive/status/50368232003084288?utm_source=otter",
               "url" : "http://twitter.com/ajelive/status/50368232003084288",
               "mytype" : "tweet",
               "title" : "Reports of at least 4 people killed in the #Syrian city of #Daraa, where residents say electricity has been cut off: http://aje.me/hBUe4g",
               "trackback_total" : 36
            },
            "author_nick" : "ajelive",
            "firstpost_date" : 1300843708,
            "topsy_author_url" : "http://topsy.com/twitter/ajelive?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/thinkprogress",
            "date" : 1300844316,
            "author_img" : "http://a1.twimg.com/profile_images/1256047404/TP_normal.gif",
            "content" : "RT @thinkprogress: NEW POLL: Just 7% of Americans view the federal deficit as the most important problem facing U.S. today http://thkpr.gs/ecU4DU",
            "date_alpha" : "11 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/thinkprogress/status/50362164892008449?utm_source=otter",
               "url" : "http://twitter.com/thinkprogress/status/50362164892008449",
               "mytype" : "tweet",
               "title" : "NEW POLL: Just 7% of Americans view the federal deficit as the most important problem facing U.S. today http://thkpr.gs/ecU4DU",
               "trackback_total" : 43
            },
            "author_nick" : "thinkprogress",
            "firstpost_date" : 1300842264,
            "topsy_author_url" : "http://topsy.com/twitter/thinkprogress?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/mohammad_syria",
            "date" : 1300844280,
            "author_img" : "http://a2.twimg.com/profile_images/1133769021/RWR_normal.png",
            "content" : "RT @Mohammad_Syria: Confirmed: Eyewitnesses: 6 dead bodies inside #Omari mosque right now as army committed a massacre in #Daraa #Syria #mar15",
            "date_alpha" : "12 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/mohammad_syria/status/50359652470362112?utm_source=otter",
               "url" : "http://twitter.com/mohammad_syria/status/50359652470362112",
               "mytype" : "tweet",
               "title" : "Confirmed: Eyewitnesses: 6 dead bodies inside #Omari mosque right now as army committed a massacre in #Daraa #Syria #mar15",
               "trackback_total" : 25
            },
            "author_nick" : "mohammad_syria",
            "firstpost_date" : 1300841681,
            "topsy_author_url" : "http://topsy.com/twitter/mohammad_syria?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/inhabitat",
            "date" : 1300844109,
            "author_img" : "http://a3.twimg.com/profile_images/51865670/OwliMcOwl_normal.jpg",
            "content" : "RT @inhabitat: California just launched a new energy upgrade program that can qualify residents for thousands of dollars in rebates! http://bit.ly/hGsnHc",
            "date_alpha" : "15 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/inhabitat/status/50318962348654592?utm_source=otter",
               "url" : "http://twitter.com/inhabitat/status/50318962348654592",
               "mytype" : "tweet",
               "title" : "California just launched a new energy upgrade program that can qualify residents for thousands of dollars in rebates! http://bit.ly/hGsnHc",
               "trackback_total" : 10
            },
            "author_nick" : "inhabitat",
            "firstpost_date" : 1300832116,
            "topsy_author_url" : "http://topsy.com/twitter/inhabitat?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/webseriestoday",
            "date" : 1300843994,
            "author_img" : "http://a1.twimg.com/profile_images/789016827/wst_100_normal.gif",
            "content" : "RT @webseriestoday: A First: Interactive Film with Augmented Reality: ..It’s then their job to track down the victim, fin... http://bit.ly/fbpmOS #webseries",
            "date_alpha" : "17 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/webseriestoday/status/50327403851022336?utm_source=otter",
               "url" : "http://twitter.com/webseriestoday/status/50327403851022336",
               "mytype" : "tweet",
               "title" : "A First: Interactive Film with Augmented Reality: ..It’s then their job to track down the victim, fin... http://bit.ly/fbpmOS #webseries",
               "trackback_total" : 17
            },
            "author_nick" : "webseriestoday",
            "firstpost_date" : 1300835145,
            "topsy_author_url" : "http://topsy.com/twitter/webseriestoday?utm_source=otter"
         },
         {
            "author_url" : "http://twitter.com/impolitical",
            "date" : 1300843992,
            "author_img" : "http://a0.twimg.com/profile_images/653297476/Twitter_avatar_grn_normal.jpg",
            "content" : "RT @impolitical: Hebert: Budget &quot;was not designed to restore peace in the 40th Parliament.&quot; http://ow.ly/4kcb2 #cdnpoli",
            "date_alpha" : "17 minutes ago",
            "target" : {
               "topsy_trackback_url" : "http://topsy.com/twitter.com/impolitical/status/50330927347404802?utm_source=otter",
               "url" : "http://twitter.com/impolitical/status/50330927347404802",
               "mytype" : "tweet",
               "title" : "Hebert: Budget &quot;was not designed to restore peace in the 40th Parliament.&quot; http://ow.ly/4kcb2 #cdnpoli",
               "trackback_total" : 6
            },
            "author_nick" : "impolitical",
            "firstpost_date" : 1300834843,
            "topsy_author_url" : "http://topsy.com/twitter/impolitical?utm_source=otter"
         }
      ],
      "offset" : 0
   }
}

---

/tags

Description: List of tags associated with a url.

Parameters:

Name Required Description
url required URL string for the target.

Accepts List Parameters

Example:

Fetch tags associated with Twitter's homepage. 

$ curl -i "http://otter.topsy.com/tags.json?url=http://twitter.com/"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:19:05 GMT
Content-Length: 1422
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:24:05 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2490
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "url" : "http://twitter.com/"
      },
      "response_type" : "json",
      "resource" : "tags",
      "url" : "http://otter.topsy.com/tags.json?url=http%3A%2F%2Ftwitter.com%2F"
   },
   "response" : {
      "page" : 1,
      "total" : "1091",
      "perpage" : 10,
      "list" : [
         {
            "url" : "http://topsy.com/s?q=current",
            "name" : "current"
         },
         ...
      ]
   }
}

Example:

Fetch tags associated with Barack Obama's Twitter profile. 

$ curl -i "http://otter.topsy.com/tags.json?url=http://twitter.com/barackobama"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:20:33 GMT
Content-Length: 1408
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:25:33 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2489
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "url" : "http://twitter.com/barackobama"
      },
      "response_type" : "json",
      "resource" : "tags",
      "url" : "http://otter.topsy.com/tags.json?url=http%3A%2F%2Ftwitter.com%2Fbarackobama"
   },
   "response" : {
      "page" : 1,
      "total" : "13",
      "perpage" : 10,
      "list" : [
         {
            "url" : "http://topsy.com/s?q=obama",
            "name" : "obama"
         },
         ...
      ]
   }
}

/trackbacks

Description: List of tweets (trackbacks) that mention the query URL, most recent first.

NOTE: If you are only interested in the counts, call the more efficient method /stats instead.

Parameters:

Name Required Description
url required URL for the target.
contains optional Query string to filter results.
infonly optional Boolean value that filters trackbacks to influential only (default 0)
sort_method optional the order in which to return results. Options are "influence", "date" and "-date".

Accepts List Parameters

Example:

Fetch posts (tweets) in json format that reference Topsy's homepage. 

$ curl -i "http://otter.topsy.com/trackbacks.json?url=http://topsy.com/"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 03:59:23 GMT
Content-Length: 7363
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:04:23 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2467
X-RateLimit-Reset: 1251345600

{
   "request" : {
      "parameters" : {
         "url" : "http://topsy.com/"
      },
      "response_type" : "json",
      "resource" : "trackbacks",
      "url" : "http://otter.topsy.com/trackbacks.json?url=http%3A%2F%2Ftopsy.com%2F"
   },
   "response" : {
      "topsy_trackback_url": "http://topsy.com/tb/topsy.com/",
      "page" : 1,
      "total" : "1931",
      "perpage" : 10,
      "list" : [
         {
            "permalink_url" : "http://twitter.com/imadnaffa/status/3565855201",
            "date" : "1251324809",
            "content" : "TOPSY - A search engine powered by tweets: http://topsy.com (this Search Engine can 
                        be powerful for sifting through Twitter- love it)!",
            "type" : "tweet",
            "author" : {
               "url" : "http://twitter.com/imadnaffa",
               "name" : "Imad Naffa",
               "photo_url" : "http://a3.twimg.com/profile_images/378575667/imad_blue_shirt_normal.jpg",
               "topsy_author_url" : "http://topsy.com/twitter/imadnaffa",
               "influence_level" : "4"
            },
            "date_alpha" : "6 hours ago"
         },
         ...
      ]
   }
}

Example:

Fetch posts (tweets) that reference Topsy's homepage from influential users only. 

curl -i "http://otter.topsy.com/trackbacks.json?url=http://topsy.com/&infonly=1&tracktype=tweet"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:03:25 GMT
Content-Length: 7413
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:08:20 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2499
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "infonly" : "1",
         "tracktype" : "tweet",
         "url" : "http://topsy.com/"
      },
      "response_type" : "json",
      "resource" : "trackbacks",
      "url" : "http://otter.topsy.com/trackbacks.json?infonly=1&tracktype=tweet&url=http%3A%2F%2Ftopsy.com%2F"
   },
   "response" : {
      "topsy_trackback_url": "http://topsy.com/tb/topsy.com/",
      "page" : 1,
      "total" : "874",
      "perpage" : 10,
      "list" : [
         {
            "permalink_url" : "http://twitter.com/imadnaffa/status/3565855201",
            "date" : "1251324809",
            "content" : "TOPSY - A search engine powered by tweets: http://topsy.com (this 
                        Search Engine can be powerful for sifting through Twitter- love it)!",
            "type" : "tweet",
            "author" : {
               "url" : "http://twitter.com/imadnaffa",
               "name" : "Imad Naffa",
               "photo_url" : "http://a3.twimg.com/profile_images/378575667/imad_blue_shirt_normal.jpg",
               "topsy_author_url" : "http://topsy.com/twitter/imadnaffa",
               "influence_level" : "4"
            },
            "date_alpha" : "6 hours ago"
         },
         ...
      ]
   }
}

/trending

Description: List of trending terms.

Accepts List Parameters

Example:

$ curl -i "http://otter.topsy.com/trending.json"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:25:54 GMT
Content-Length: 1375
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:30:54 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2487
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {},
      "response_type" : "json",
      "resource" : "trending",
      "url" : "http://otter.topsy.com/trending.json"
   },
   "response" : {
      "page" : 1,
      "total" : "216",
      "perpage" : 10,
      "list" : [
         {
            "url" : "http://topsy.com/s?q=dominick",
            "term" : "dominick"
         },
         ...
      ]
   }
}

/urlinfo

Description: Information about an url.

Parameters:

Name Required Description
url required URL string for the target.

Example:

Fetch information about Twitter's homepage. 

$ curl -i "http://otter.topsy.com/urlinfo.json?url=http://twitter.com/"

HTTP/1.0 200 OK
Connection: close
Date: Thu, 27 Aug 2009 04:17:51 GMT
Content-Length: 694
Content-Type: application/json; charset=utf-8
Expires: Wed, 26 Aug 2009 21:22:51 -0700
Status: 200
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2491
X-RateLimit-Reset: 1251349200

{
   "request" : {
      "parameters" : {
         "url" : "http://twitter.com/"
      },
      "response_type" : "json",
      "resource" : "urlinfo",
      "url" : "http://otter.topsy.com/urlinfo.json?url=http%3A%2F%2Ftwitter.com%2F"
   },
   "response" : {
      "topsy_trackback_url" : "http://topsy.com/tb/twitter.com/",
      "oneforty" : "Twitter: What are you doing? http://twurl.nl/pd8k44",
      "url" : "http://twitter.com/",
      "title" : "Twitter: What are you doing?",
      "trackback_total" : "24152",
      "description" : "Social networking and microblogging service utilising instant messaging, SMS or a web interface.",
      "description_attribution" : "From DMOZ"
   }
}
Comment by chris.w...@gmail.com, Nov 26, 2009

how are short urls handled? if I send a tweet with a bit.ly link

that redirects to topsy.com will there now be a urlinfo result for
topsy.com

Comment by mssat...@hotmail.com, Nov 26, 2009

GOOD

Comment by bmerr...@gmail.com, Dec 1, 2009

Chris,

We attempt to resolve all short links to their permalinks. See for example this trackback page:

http://topsy.com/tb/topsy.com/

It shows "188 shorturls"

One of the shorturls listed is http://bit.ly/10kM5I

If you look at the trackback page for that url, it resolves to the same permalink, and shows the same page:

http://topsy.com/tb/bit.ly/10kM5I

Comment by jimmy.d...@gmail.com, Jul 21, 2010

For the /search call, the default time window is 'all', NOT 'auto' (and definitely not 'JSON', which I think was a typo). For now, I'm just explicitly setting the time window for every call, but you might want to correct the typo and correct the functionality if 'all' wasn't the intended default.

Comment by bna...@gmail.com, Feb 8, 2011

Awesome

Comment by sebastia...@gmail.com, Jun 23, 2011

The authorsearch.json endpoint seems to be missing here.

Comment by ras...@gooval.com, Jul 15, 2011

Is location based info available? Can I search for results for a specific location only?

Comment by andrew.s...@gmail.com, Oct 7, 2011

Great work! Thanks.

I'm in need of getting only the "worldwide" trends. Is this not available?

Thanks!

Comment by caroline...@gmail.com, Oct 21, 2011

I need to know if it is possible to search for results for a specific geographic location (lat/lon) ?

Comment by srsmo...@gmail.com, Mar 22, 2012

Greeat API and the tutorial as well. I liked it. Easy one. Thanks. Great work


► Sign in to add a comment
Powered by Google Project Hosting